Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 78 ยท Branching and Merging

Merging Branches

Learn how git merge combines branches: fast-forward and three-way merges, merge commits, --no-ff, --squash, --ff-only, merge strategies and the graph shapes they make.

Branches let you work in parallel. Merging is how the work comes back together. When your feature is done, you merge the feature branch into main, and main then contains everything from both lines of history. git merge is one of the commands you will run most often, and understanding what it does to the history graph will save you from many confusing moments.

The key idea is that you always merge into the branch you are on. You switch to the branch that should receive the work (usually main), and then you name the branch that carries the work: git merge feature. The branch you name is left untouched; only your current branch moves. If you are still shaky on what a branch is, read Branches first.

Two kinds of merge

Git performs one of two very different operations behind the same command, depending on how the histories relate.

Fast-forward: the branch simply moves

If the current branch has no new commits of its own since the other branch split off, then the other branch is simply ahead of you on the same line. There is nothing to combine, so Git slides your branch pointer forward. No new commit is created.

TEXT
Before:   A <โ”€โ”€ B <โ”€โ”€ C              main is behind feature
                      โ–ฒ
                    main      D <โ”€โ”€ E
                                    โ–ฒ
               (C โ—€โ”€โ”€ D โ—€โ”€โ”€ E)   feature

After "git merge feature" on main:

          A <โ”€โ”€ B <โ”€โ”€ C <โ”€โ”€ D <โ”€โ”€ E
                                  โ–ฒ
                          main, feature

Three-way merge: a new commit with two parents

If both branches have new commits, the histories have diverged. Git cannot just move a pointer. It finds the merge base, the most recent commit both branches share, compares each side against that base, combines the two sets of changes, and records the result as a new merge commit that has two parents.

TEXT
Before:        โ”Œโ”€โ”€ D โ”€โ”€ E   feature
           A โ”€โ”€ B โ”€โ”€ C      main
                   
After "git merge feature" on main:

               โ”Œโ”€โ”€ D โ”€โ”€ E โ”€โ”€โ”
           A โ”€โ”€ B โ”€โ”€ C โ”€โ”€โ”€โ”€โ”€โ”€โ”€ M      main (M has parents C and E)

The name "three-way" comes from the three commits Git looks at: the two branch tips and their common ancestor. The ancestor is what lets Git tell the difference between "you changed this line" and "they changed this line". The algorithm is covered in depth in How Merge, Rebase and Diff Work Inside.

Fast-forward in action

Bash A fast-forward merge moves the pointer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

main ended up at exactly the same commit as feature. Git printed Fast-forward and a summary of the files that changed, and the graph is a straight line with no merge commit. Because the line is straight, you cannot tell afterwards that the work happened on a branch at all. Some teams like that; others want the branch to stay visible, which is what --no-ff is for (below).

Three-way merge in action

Now let both branches move. One person edits login.txt on a feature branch; someone else fixes a different file on main. The changes do not overlap, so Git can combine them automatically.

Bash A three-way merge creates a merge commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The merge printed Merge made by the 'ort' strategy. ("ort" is the default algorithm; more below). The graph now has the typical diamond shape, and %p shows two parent IDs for the merge commit: the first parent is the old tip of main, the second is the tip of feature. The first parent is special: it is the branch you were on. Commands such as git log --first-parent follow only that line, which gives you a clean "what landed on main" view that skips the individual feature commits.

We passed -m to give the message directly. Without it, Git opens your editor with a default message such as Merge branch 'feature'. In an editor-less setting like this page, -m (or the environment setting GIT_EDITOR=true) avoids the prompt.

Forcing a merge commit with --no-ff

Even when a fast-forward is possible, git merge --no-ff feature creates a merge commit. That keeps a visible bump in the graph that says "this group of commits was one unit of work", and it gives you one commit that you can later revert to undo the entire feature.

Bash Compare a fast-forward with --no-ff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Although a fast-forward was possible, we now have a merge commit. Reading with --first-parent shows just two entries on main: the base and the merge. The two feature commits are still there, reachable through the merge's second parent.

You can make this the default for a repository with git config merge.ff false, or require the opposite with git config merge.ff only.

Refusing anything but a fast-forward

git merge --ff-only feature merges only if a fast-forward is possible, and otherwise fails without changing anything. It is a safe way to say "just update my branch and never create a surprise merge commit". It is especially useful for git pull --ff-only (see push, pull and Tracking Branches).

Bash --ff-only refuses diverged branches (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The real error is fatal: Not possible to fast-forward, aborting. The branches have diverged, so the only way to combine them is a real merge. The last command shows another outcome: merging a branch whose commits are already contained in your current branch prints Already up to date. and does nothing.

Squash merges

git merge --squash feature takes all the changes from feature, applies them to your working tree and index, and stops without committing. You then commit once, writing one message. The result is a single ordinary commit with one parent; there is no link to the feature branch.

Bash Squash a feature branch into one commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The output says Fast-forward only because main had no commits of its own, but the next line, Squash commit -- not updating HEAD, is the important one: the changes sit in the index (git status -s shows A b.txt) and nothing is committed yet. The three messy commits (wip, wip 2, fix typo) became one tidy commit on main. The graph shows that feature and main are not connected by a merge, so Git still considers feature unmerged: git branch -d feature would refuse, and you must use -D once you are sure. Squash merging is popular on pull-request platforms because the history on main has one commit per feature. The price is that the detailed steps are gone from main, and that you cannot later tell from the graph alone which branch a commit came from.

Merge strategies, briefly

You rarely need to choose, but you should know the names:

Option Meaning
-s ort The default strategy (since Git 2.34). Fast, handles renames, and merges two heads
-s recursive The older default; ort replaced it and the name is now an alias for it
-s ours Records a merge but keeps your tree, ignoring the other side's content entirely
-X ours / -X theirs Normal merge, but on conflicting hunks prefer our / their side
-X ignore-space-change Treat whitespace-only differences as unchanged
-s octopus Merge more than one branch at once (used automatically when you list several)

Be careful with the difference between -s ours (a strategy: throws the other branch's changes away but marks them merged) and -X ours (an option: only decides conflicts). Mixing them up silently discards work.

What to check before and after a merge

  • Before: git status should be clean. Merging with uncommitted changes can work, but if the merge fails you will be juggling two sets of changes. Commit or stash first.
  • Make sure you are on the right branch with git branch --show-current. The most common merge accident is merging the wrong way round, ending up with main merged into feature.
  • Preview what is coming: git log main..feature --oneline lists the commits the merge would bring in, and git diff main...feature shows the combined change (see Comparing Commits, Branches and Files).
  • After: git log --graph --oneline to confirm the shape, and run your tests. A merge without textual conflicts can still break the program, for example when one side renames a function the other side calls.

If the merge goes wrong mid-way, git merge --abort returns you to the state before it began. What to do when Git stops because of overlapping edits is the topic of the next lesson, Resolving Merge Conflicts.

Merging is not the only way to integrate work. Rebasing replays your commits on top of another branch to keep history linear, and cherry-picking copies single commits. Merging is the safest of the three on shared branches because it never rewrites existing commits.

Pitfalls professionals know

  • Merging the target into your feature branch regularly (git merge main while on feature) is fine and keeps conflicts small, but it adds many merge commits. Some teams prefer rebasing for this; agree on one habit.
  • Merge commits made by a plain git pull are a classic source of noisy history. See push, pull and Tracking Branches.
  • --no-ff and --squash change what "merged" means to Git. After a squash, Git does not know the branch was merged. Delete such branches with -D and only after checking.
  • A merge commit is a normal commit. You can show it (git show -m), blame through it and revert it (with -m 1, see Reverting Commits Safely).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You are on main and run git merge feature. Which branch moves?

    You always merge into the current branch. main moves to the result; feature is left exactly as it was.
  2. 2. When does Git perform a fast-forward merge?

    If the other branch is simply ahead on the same line of history, Git only moves the pointer. No merge commit is made.
  3. 3. How many parents does a commit created by git merge --squash have?

    A squash merge makes an ordinary commit with a single parent, so the graph does not link it to the feature branch.
  4. 4. What does git merge --ff-only feature do when the branches have diverged?

    --ff-only refuses anything except a fast-forward. It prints that a fast-forward is not possible and leaves your branch alone.
  5. 5. What is the difference between -s ours and -X ours?

    -s selects a merge strategy; ours keeps our tree and records the merge. -X passes an option to the normal strategy, which only affects conflicts.

Summary

  • Merge into the branch you are on: switch to the receiver, then git merge other.
  • A fast-forward just moves the pointer; a three-way merge makes a commit with two parents using the common ancestor.
  • --no-ff always creates a merge commit; --ff-only refuses anything else; --squash applies the changes and leaves you to make one single-parent commit.
  • The first parent of a merge is the branch you were on; git log --first-parent follows it.
  • Check git status before merging, preview with git log main..feature, and use git merge --abort to back out.
  • Strategies (ort, ours, octopus) and options (-X ours, -X theirs) are different things.

Next: Resolving Merge Conflicts