Appearance
Understanding Branches
Branches let you work on multiple things at the same time without interfering with yourself. Think of them as parallel universes for your code.
Scenario
You have a working project on main. You want to add a search feature. It will take a few days and might break things. You also need to fix a bug in the current code. Branches let you do both: the bug fix goes to main right away, the search feature stays in its own branch until it's ready.
What is a branch?
A branch is a movable pointer to a commit. When you make a new commit, the branch pointer moves forward with it.
Before commit: main -> a1b2c3d
After commit: main -> e4f5g6h -> a1b2c3dHEAD is Git's way of saying "where you are right now." It usually points to a branch, and the branch points to a commit:
HEAD -> main -> e4f5g6hStep by step
1. See what branches exist
bash
git branchOutput:
* mainThe * marks the active branch. Right now there is one branch: main.
Add -a to see remote branches too:
bash
git branch -a* main
remotes/origin/main2. Create a new branch
bash
git branch feature-searchNo output on success. Run git branch again:
feature-search
* mainA new branch called feature-search exists, pointing at the same commit as main. You are still on main.
3. Switch to the new branch
bash
git switch feature-searchOutput:
Switched to branch 'feature-search'Now git branch shows:
* feature-search
maingit switch changes which branch HEAD points to. Your working files update to match the commit that branch points to. Since both branches point to the same commit right now, nothing changes in your files.
4. Make a commit on the new branch
Edit a file, stage it, commit:
bash
echo "search bar coming soon" >> index.html
git add index.html
git commit -m "add search placeholder"Output:
[feature-search a1b2c3d] add search placeholder
1 file changed, 1 insertion(+)Now feature-search has moved forward. main stayed where it was.
feature-search -> a1b2c3d -> b2c3d4e
main -> a1b2c3d5. Switch back to main and see the difference
bash
git switch mainYour working files revert to what main points to. The index.html no longer has the search placeholder.
bash
git log --onelineShows only the commits on main. The feature-search commit is not visible.
bash
git log --oneline feature-searchShows the feature-search commit. Each branch has its own history.
6. Create a second branch from main
bash
git switch main
git branch bugfix-header
git switch bugfix-headerNow you have three branches:
* bugfix-header
feature-search
mainFix a bug, commit:
bash
echo "fixed header alignment" >> style.css
git add style.css
git commit -m "fix header alignment"Each branch now has different commits. They diverged from main.
main -> a1b2c3d
feature-search -> a1b2c3d -> b2c3d4e (search placeholder)
bugfix-header -> a1b2c3d -> c3d4e5f (header fix)7. Merge the bug fix back into main
bash
git switch main
git merge bugfix-headerOutput:
Updating a1b2c3d..c3d4e5f
Fast-forward
style.css | 1 +
1 file changed, 1 insertion(+)The merge was a "fast-forward" because main had not moved since bugfix-header branched off. Git just moved the main pointer forward to match bugfix-header.
8. Clean up the merged branch
bash
git branch -d bugfix-headerOutput:
Deleted branch bugfix-header (was c3d4e5f).The branch is gone. The commits it contained are still reachable through main.
What's happening here
| Step | What Git does | Key idea |
|---|---|---|
git branch <name> | Creates a pointer at the current commit | A branch is just a name for a commit |
git switch <branch> | Moves HEAD to that branch, updates working tree | HEAD determines what you see and where new commits go |
git commit on a branch | Advances the branch pointer to the new commit | Branches move forward, not sideways |
git merge <branch> | Combines histories by advancing or creating a merge commit | Two branches become one timeline again |
git branch -d <name> | Deletes the pointer | The commits stay, the name is gone |
Common mistakes
| Mistake | What happens | How to fix |
|---|---|---|
| Forgetting to switch before committing | New commit goes to the wrong branch | Cherry-pick it to the right branch, reset the wrong one |
| Working on main by accident | Feature commits pollute main's history | Create a branch from the first feature commit, reset main back |
| Deleting a branch that has unmerged commits | Git refuses: "not fully merged" | Use -D (force delete) if you are sure the commits are not needed |
| Creating a branch but never switching to it | Commits still go to the original branch | git switch <new-branch> before you start editing |
| Multiple branches diverging far | Merge becomes complex | Merge or rebase frequently to keep branches short-lived |
When to use branches
- Every new feature gets its own branch. Keeps
maindeployable at all times. - Every bug fix gets its own branch. Lets you merge fixes without pulling in unfinished features.
- Experiments get branches. If the experiment fails, delete the branch and the experiment disappears.
When not to use branches
- Tiny changes (typo fix, one-line config change). Commit directly to
mainif your workflow allows it. - Research spikes you plan to discard. A branch is fine, but consider a worktree or even a separate clone if you need to keep the main checkout clean.
Quick reference
bash
git branch # List local branches
git branch <name> # Create a branch at current commit
git switch <name> # Switch to a branch
git switch -c <name> # Create and switch in one command
git merge <name> # Merge <name> into current branch
git branch -d <name> # Delete a merged branch
git branch -D <name> # Force delete (unmerged)
git log --oneline --graph --all # See all branches visuallyNext steps
Now you can create branches, switch between them, and merge them back. Read the merging basics guide for what happens when two branches edit the same file. Then try the branch lifecycle guide for naming conventions and team workflows.