Lesson 3 of 8 in Git and collaboration

Branches and merging

Core10 minWritten for Git 2.28 or newer

A branch is a movable label on a commit that lets you work on a change without disturbing the main line. Merging joins the work from one branch into another, either by moving a label forward or by creating a commit with two parents.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Staging and writing commits

The problem this solves

Real changes take time. While you rework a deploy script for a day, the rest of the team still needs a working main line to fix bugs and release. If you both edit the same folder, one of you waits or breaks the other.

A branch gives your change its own line of commits. Because a branch is only a label, creating one is instant and does not copy any files. You can start one for every small task.

Branches only help if work flows back. Merging is how it does, and understanding its two shapes explains the history you see in real projects.

How it works

Branches are labels on commits
Branches are labels on commitsCommits C1, C2 and C3 form a chain; main points to C2, feature points to C3, and HEAD points to feature, so new commits extend the feature branch.parentparentpoints topoints topoints toC1C2C3made on featuremainfeatureHEADyou are here
  • Data
  • Control
  • People and clients

Commits C1, C2 and C3 form a chain; main points to C2, feature points to C3, and HEAD points to feature, so new commits extend the feature branch.

  1. C2 to C1: parent
  2. C3 to C2: parent
  3. main to C2: points to
  4. feature to C3: points to
  5. HEAD to feature: points to
A merge commit joins two lines of work
A merge commit joins two lines of workWhen both main and feature moved on from a shared base commit, the merge commit has two parents, one from each line.parentparentparent 1parent 2Base commitwhere they splitCommit on mainCommit on featureMerge commithas two parents
  • Data
  • Control

When both main and feature moved on from a shared base commit, the merge commit has two parents, one from each line.

  1. Commit on main to Base commit: parent
  2. Commit on feature to Base commit: parent
  3. Merge commit to Commit on main: parent 1
  4. Merge commit to Commit on feature: parent 2

In the first diagram, main and feature are two labels on one chain. Switching branches moves HEAD to the other label and makes the working tree match that commit. That is why files appear and disappear when you switch.

Merging has two shapes. If main has not moved since you branched, git can just slide the main label forward to the same commit as feature. This is called a fast-forward, and it creates no new commit.

If both branches moved on, as in the second diagram, git builds a new merge commit. It compares each side with the shared base commit, combines the changes, and records the result with two parents. If both sides changed the same lines, git cannot choose and asks you. That is a conflict, covered next.

Try it yourself

Fresh throwaway folder again. You will see a fast-forward merge first, then a merge commit.

  1. 1
    Set up with one commit
    mkdir git-lab-3 && cd git-lab-3
    git init -b main
    git config user.name "Your Name"
    git config user.email "you@example.com"
    echo "base" > app.txt
    git add app.txt && git commit -m "Add app.txt"
  2. 2
    Create a branch and commit on it
    git switch -c add-greeting
    echo "hello" > greeting.txt
    git add greeting.txt && git commit -m "Add greeting"
    git log --oneline --graph --all

    git switch -c <name> creates a branch and moves to it in one step.

  3. 3
    Switch back and watch the file vanish
    git switch main
    ls

    greeting.txt is not listed. Your working tree now matches the commit main points to. The file is safe inside the branch.

  4. 4
    Merge as a fast-forward
    git merge add-greeting
    git log --oneline --graph --all

    The output includes the word Fast-forward. main did not move while you worked, so git only moved its label. The graph is one straight line.

  5. 5
    Make both branches move, then merge
    git switch -c add-footer
    echo "footer" > footer.txt
    git add footer.txt && git commit -m "Add footer"
    git switch main
    echo "header" > header.txt
    git add header.txt && git commit -m "Add header"
    git merge add-footer --no-edit
    git log --oneline --graph --all

    Now the graph forks and rejoins. The merge commit has two parents.

  6. 6
    Delete branches you no longer need
    git branch -d add-greeting add-footer
    git branch

    -d refuses to delete a branch whose commits are not merged anywhere, so it is the safe version. The commits stay in history because the merge reached them.

What breaks, and where to look

  • error: Your local changes to the following files would be overwritten by checkout

    WHY IT HAPPENS
    You have uncommitted edits to a file that differs between the two branches. Switching would overwrite your edits, so git refuses.
    CHECK FIRST
    Run git status. Commit the work, or set it aside with git stash and bring it back with git stash pop after switching.
  • You are in 'detached HEAD' state.

    WHY IT HAPPENS
    You checked out a commit ID or a tag instead of a branch. HEAD points straight at a commit, so new commits belong to no branch and become hard to find later.
    CHECK FIRST
    Run git status. It says HEAD detached at <id>. To keep work done here, run git switch -c rescue-branch. To leave without keeping it, run git switch main.
  • error: the branch 'add-footer' is not fully merged

    WHY IT HAPPENS
    git branch -d found commits on that branch that no other branch contains. Deleting would make them hard to reach.
    CHECK FIRST
    Run git log main..add-footer to list the commits only that branch has. Merge it if you want them. Use git branch -D only when you are sure you want to drop them.

When not to use this

  • A branch that lives for weeks drifts away from main, and the eventual merge becomes painful. The branching strategies concept covers how teams avoid this.
  • Merging is not the only way to combine work. Rebasing replays your commits on top of another branch for a straighter history, but it rewrites commits, so it needs the care described in the undoing concept.

Check yourself

Why is creating a branch cheap?

A branch is just a label pointing at a commit. No files are copied.

When does a merge create no new commit?

When the target branch has not moved since the branch started. Git fast-forwards by sliding the label forward.

What makes a commit a merge commit?

It has two parents, one from each line of work that was joined.

Lesson 33 of 92 in the DevOps path

Search

Search cheat sheets and projects