Merging

The mental model

A merge takes two commits, almost always the tips of two branches, and produces a result that contains both histories. The result is one of two shapes: either Git slides the target branch's pointer forward along an existing chain, or it builds a new commit whose two parents are the tips you merged.

Which shape you get depends entirely on whether the histories have diverged. If the branch you are merging is purely "ahead" of where you stand, there is nothing to reconcile and Git can fast-forward. If both sides have moved since they last agreed, Git has to combine real changes and records a merge commit that points back to both of them.

The everyday command is short:

git switch main
git merge feature

Read it as "while standing on main, pull feature in." The current branch is always the destination. The named branch is the source. After the command, the current branch reflects both histories; the source branch is untouched.

Fast-forward merge

A fast-forward is the simplest case. The target branch's tip is already an ancestor of the source branch's tip, meaning the target has done nothing new since they diverged. Git does not need to build a new commit; it just moves the target's branch pointer forward.

Git tells you when this happens:

$ git merge feature
Updating f42c576..3a0874c
Fast-forward
 src/app.js | 12 ++++++++++++
 1 file changed, 12 insertions(+)

"Fast-forward" is the giveaway. No merge commit was created, the history stays linear, and the only thing that changed is which commit main points to.

True (three-way) merge

When both branches have moved since they parted ways, the histories have diverged. Git cannot just slide a pointer; it has to combine two sets of changes and record that combination as a commit. This is called a three-way merge because three commits are involved: the two branch tips and their common ancestor.

If the two diffs touch different lines, Git combines them automatically and writes the result as a merge commit. If they touch the same lines differently, Git stops and asks you to resolve the conflict by hand. The mechanics of conflict resolution are the subject of the next topic.

Git announces a three-way merge differently:

$ git merge feature
Merge made by the 'ort' strategy.
 src/parser.js | 24 ++++++++++++++++++++----
 src/util.js   |  3 +++
 2 files changed, 23 insertions(+), 4 deletions(-)

The new merge commit has two parents (the previous tip of main and the tip of feature), an author and committer (usually you), and a message. By default Git writes "Merge branch 'feature' into main"; you can edit it before saving.

Controlling fast-forward: --ff, --no-ff, --ff-only

Three flags decide whether fast-forwarding is allowed when a fast-forward is technically possible. The flag matters only for cases that could fast-forward; when histories have diverged, only a three-way merge can succeed.

git merge feature              # default: fast-forward if possible
git merge --no-ff feature      # always record a merge commit
git merge --ff-only feature    # fast-forward or fail

Merge strategies

When Git has to combine real diffs, it chooses a strategy: an algorithm for computing the merged tree. You almost never pick one explicitly, but knowing what is there helps when you read merge output or a defaults discussion.

Pass a strategy with -s:

git merge -s ours obsolete-experiment    # keep current tree, record the merge
git merge -s octopus topic-a topic-b     # merge three histories at once

Note: there is no top-level theirs strategy. The opposite of -s ours -- "use the other side's content" -- is available as a strategy option, covered next.

Strategy options (-X)

Where -s picks the algorithm, -X tunes it. The two most useful options resolve conflicts automatically by preferring one side:

git merge -X ours feature       # on conflict, keep our version
git merge -X theirs feature     # on conflict, keep their version

The distinction between -s ours and -X ours matters. -s ours throws away the other branch's content entirely, regardless of conflicts. -X ours still performs a normal merge -- non-conflicting changes from both sides land in the result -- and only falls back to our version when Git would otherwise stop on a conflict.

A few other -X options that come up:

• -X ignore-all-space, -X ignore-space-change -- treat whitespace-only differences as non-conflicting. Useful when one branch reformatted a file.
• -X renormalize -- run line-ending normalization on both sides before comparing. Helpful when CRLF/LF settings have changed.
• -X diff-algorithm=patience (or histogram) -- swap the diff algorithm. Occasionally produces a cleaner result on heavily reorganized files.

Squash merges

A squash merge is technically not a merge at all -- it just borrows the verb. git merge --squash <branch> stages the combined changes from the named branch but does not create a merge commit and does not record the branch's commits as part of history. You then commit those staged changes yourself, producing a single ordinary commit on the current branch.

git switch main
git merge --squash feature
git commit -m "Add CSV import"

The result on main is one commit whose tree contains everything feature built, but whose history shows no link to feature at all. This is the model GitHub uses for "Squash and merge" pull requests: many small WIP commits on the branch collapse into one tidy commit on the target.

Aborting and undoing

A merge in progress -- one Git started but stopped on a conflict, or one you started and want to back out of -- can be rolled back with:

git merge --abort

This restores the working tree and index to their state before the merge started. It works only while the merge is mid-flight. git reset --merge is a related, slightly older command useful in some edge cases involving uncommitted changes; --abort is the modern recommendation.

Once a merge has been committed, undoing it is a different problem. If you have not pushed the merge anywhere, git reset --hard HEAD~1 drops it and rewinds to the previous tip. If you have already published it, you should revert the merge with git revert -m 1 <merge-commit>, which records a new commit that undoes the merge's effects without rewriting history. Revert is covered in a later chapter on undoing work.

Visualizing merges

Reading the merge structure of a project is much easier once you train yourself to look at the graph rather than the linear log. The everyday incantation:

git log --oneline --graph --all --decorate

You will see ASCII branches splitting and joining at each merge commit. A fast-forward shows up as a straight line; a true merge shows up as a diamond. --decorate annotates each commit with the branches and tags pointing at it, which makes "where am I and where is the merge base" much clearer.

Merge vs rebase

Git offers two ways to integrate one branch's work into another: merge and rebase. Merge preserves the actual history -- the two lines of development really happened in parallel, and the merge commit records exactly that. Rebase rewrites the source branch's commits on top of the target so the result looks linear, as if the work had always happened sequentially.

Both are useful; they answer different questions. Merge answers "what is the real shape of this project's history?" Rebase answers "what is the cleanest story to tell about this work?" Rebasing gets its own topic later in this chapter.

Common pitfalls

Worked examples

git switch -c hotfix
# edit, commit, edit, commit
git switch main
git merge hotfix
# Updating a1b2c3d..e4f5g6h
# Fast-forward
git log --oneline --graph
# * e4f5g6h (HEAD -> main, hotfix) Fix typo in error message
# * d9e8c7b Defensive check on null input
# * a1b2c3d Earlier commit on main

git switch main
git merge --no-ff hotfix
# Merge made by the 'ort' strategy.
git log --oneline --graph
# *   3f2c8a1 (HEAD -> main) Merge branch 'hotfix'
# |\
# | * e4f5g6h (hotfix) Fix typo in error message
# | * d9e8c7b Defensive check on null input
# |/
# * a1b2c3d Earlier commit on main

git merge-base main feature
# 7a8b9c0d1e2f...
git log --oneline 7a8b9c0..main
# commits on main since the branch point
git log --oneline 7a8b9c0..feature
# commits on feature since the branch point

git switch main
git merge --squash feature
# Squash commit -- not updating HEAD
# Automatic merge went well; stopped before committing as requested
git status
# Changes to be committed:
#   modified:   src/import.js
#   new file:   tests/import.test.js
git commit -m "Add CSV import"
git branch -D feature