Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Concepts

Fast-forward merges

Learn when Git performs a fast-forward merge, how --no-ff and --ff-only change the result, and how to configure the default with merge.ff.

A fast-forward happens when the branch you merge into has not moved since the other branch split off. The target commit is already a descendant of your current commit, so there is nothing to combine: Git just moves your branch pointer forward. No new commit is created, and the history stays a straight line.

If both branches have new commits, a fast-forward is impossible and Git creates a merge commit with two parents instead. You can also force a merge commit even when a fast-forward would work.

Terminal
git merge feature              # fast-forwards if possible, else merge commit
git merge --no-ff feature      # always create a merge commit
git merge --ff-only feature    # fast-forward or fail; never create a commit

Try it

Bash Fast-forward versus 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.

Bash --ff-only when histories have diverged

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.

Syntax

Terminal
git merge [--ff | --no-ff | --ff-only] <branch>
git config merge.ff true|false|only
git config branch.<name>.mergeoptions --no-ff
Option Behavior
--ff (default) Fast-forward when possible, otherwise create a merge commit.
--no-ff Always create a merge commit, even if a fast-forward is possible.
--ff-only Fast-forward or abort with an error ("Not possible to fast-forward").

merge.ff set to false means --no-ff; set to only means --ff-only.

Usage notes

  • When it applies. git merge-base --is-ancestor HEAD feature succeeds exactly when a fast-forward is possible.
  • Why use --no-ff. The merge commit marks where a feature began and ended, so the whole feature can be reverted with git revert -m 1 <merge>, and git log --first-parent reads like a list of features.
  • Why use --ff-only. It guarantees a linear history and never surprises you with an accidental merge commit. git pull --ff-only is a safe pull that fails when you must decide between merge and rebase.
  • Fast-forwards never conflict, since no content is combined.
  • Squash merges are different. git merge --squash never fast-forwards and does not record the branch as merged; it stages the combined changes for you to commit.
  • After a rebase, the branch sits directly on top of its target, so integrating it is a fast-forward (see Merge versus rebase).