Git Branching for Beginners

A branch is a separate line of work. You make one, change things, and your main version stays exactly as it was until you decide to bring the work in.

git switch -c add-login     # create a branch and move to it
# ...edit, add, commit as normal...
git switch main             # back to the main version
git merge add-login         # bring the work in
git branch -d add-login     # tidy up

That is the whole everyday loop. The rest of this page is what each step means and what to do when it goes wrong.

What a branch really is#

It is not a copy of your files. It is a movable label pointing at one commit.

Your history is a chain of commits. main is a label on the newest one. When you create a branch you make a second label on the same commit. Commit while that label is checked out and it moves forward, while main stays put.

A---B---C          <- main
         \
          D---E     <- add-login

That is why branching is instant even in a huge project, and why having several branches costs you nothing.

The commands#

git branch                  # list local branches, * marks the current one
git branch -a               # include remote ones

git switch -c new-feature   # create and move to it
git switch main             # move to an existing branch
git switch -                # back to the previous one

git branch -d new-feature   # delete (refuses if unmerged)
git branch -D new-feature   # delete anyway — you will lose those commits
git branch -m better-name   # rename the current branch

You will also see git checkout -b in older guides. It does the same thing. switch was added later specifically because checkout did too many unrelated jobs.

When to branch#

Working alone, you can live on main for a while and nothing bad happens. Branch when:

• You are trying something you might throw away. If it does not work, delete the branch — main never knew about it.
• You want to fix something urgent while a bigger change is half-finished.
• Anyone else is involved. At that point it stops being optional.

Name branches after the work: add-search, fix-login-crash. Not test2.

Merging#

Merge into the branch you are standing on, so switch there first:

git switch main
git merge add-login

If main has not moved since you branched, Git just slides the label forward — a “fast-forward”, with no merge commit. If both have moved, Git creates a merge commit joining the two lines. Both are normal.

Merge conflicts#

A conflict means the same lines changed on both branches and Git will not guess. It looks alarming and is completely routine.

git merge add-login
# CONFLICT (content): Merge conflict in app.py
# Automatic merge failed; fix conflicts and then commit the result.

Open the file. Git has marked the disagreement:

<<<<<<< HEAD
greeting = "Hello"
=======
greeting = "Hi there"
>>>>>>> add-login

Above ======= is what is on your current branch. Below it is what is coming in. To resolve:

1. Edit the file so it reads how you want. Keep one version, the other, or write something new.
2. Delete all three marker lines — <<<<<<<, ======= and >>>>>>>.
3. Stage and commit:

git add app.py
git commit

Run git status at any point — it lists exactly which files still need attention.

To abandon the whole thing and go back to before the merge:

git merge --abort

Working with a branch on GitHub#

git switch -c add-search
# ...work, add, commit...
git push -u origin add-search

The -u links your local branch to the remote one, so from then on plain git push and git pull know where to go.

GitHub will then offer to open a pull request — a page proposing your branch be merged into main, with room for discussion and review. It is a GitHub feature, not a Git one, and it is how nearly every team and open-source project accepts changes.

Once it is merged, tidy up:

git switch main
git pull
git branch -d add-search

Keeping a long-running branch up to date#

If main has moved on while you worked, pull its changes into your branch so you deal with conflicts now rather than at the end:

git switch main
git pull
git switch add-search
git merge main

You will also hear about git rebase, which replays your commits on top of the new main for a tidier history. It is worth learning later. Merging is easier to reason about and harder to get wrong, so start there.

Switching with uncommitted changes#

Git will not let you switch if it would overwrite unsaved work. Either commit it, or put it aside:

git stash              # shelve everything uncommitted
git switch main
# ...do the urgent thing...
git switch add-search
git stash pop          # bring your work back

Where to go next#

• Git and GitHub explained — the basics this builds on
• How to build a programming portfolio