Skip to content

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 -> a1b2c3d

HEAD 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 -> e4f5g6h

Step by step ​

1. See what branches exist ​

bash
git branch

Output:

* main

The * 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/main

2. Create a new branch ​

bash
git branch feature-search

No output on success. Run git branch again:

  feature-search
* main

A 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-search

Output:

Switched to branch 'feature-search'

Now git branch shows:

* feature-search
  main

git 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 -> a1b2c3d

5. Switch back to main and see the difference ​

bash
git switch main

Your working files revert to what main points to. The index.html no longer has the search placeholder.

bash
git log --oneline

Shows only the commits on main. The feature-search commit is not visible.

bash
git log --oneline feature-search

Shows 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-header

Now you have three branches:

* bugfix-header
  feature-search
  main

Fix 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-header

Output:

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-header

Output:

Deleted branch bugfix-header (was c3d4e5f).

The branch is gone. The commits it contained are still reachable through main.

What's happening here ​

StepWhat Git doesKey idea
git branch <name>Creates a pointer at the current commitA branch is just a name for a commit
git switch <branch>Moves HEAD to that branch, updates working treeHEAD determines what you see and where new commits go
git commit on a branchAdvances the branch pointer to the new commitBranches move forward, not sideways
git merge <branch>Combines histories by advancing or creating a merge commitTwo branches become one timeline again
git branch -d <name>Deletes the pointerThe commits stay, the name is gone

Common mistakes ​

MistakeWhat happensHow to fix
Forgetting to switch before committingNew commit goes to the wrong branchCherry-pick it to the right branch, reset the wrong one
Working on main by accidentFeature commits pollute main's historyCreate a branch from the first feature commit, reset main back
Deleting a branch that has unmerged commitsGit refuses: "not fully merged"Use -D (force delete) if you are sure the commits are not needed
Creating a branch but never switching to itCommits still go to the original branchgit switch <new-branch> before you start editing
Multiple branches diverging farMerge becomes complexMerge or rebase frequently to keep branches short-lived

When to use branches ​

  • Every new feature gets its own branch. Keeps main deployable 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 main if 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 visually

Next 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.

Git Master — Git Reference for Every Skill Level