What is Fast-Forward

A fast-forward is a merge where the target branch has not diverged — the branch being merged is a direct descendant. Git moves the branch pointer forward without creating a merge commit.

How it works

If main points to commit c3 and feature points to c5, where c5's ancestry includes c3, then main is an ancestor of feature. Merging feature into main is a fast-forward — Git simply moves main from c3 to c5.

git checkout main
git merge feature        # fast-forward: main advances to c5
git merge --ff-only feature  # fail if not fast-forwardable

No merge commit is created. No tree is computed. The ref file is updated — one write, O(1).

If the branches have diverged (both have new commits since their common ancestor), fast-forward is not possible. Git performs a three-way merge instead, creating a merge commit with two parents.

--ff-only enforces that the merge must be a fast-forward. If the branches have diverged, the merge is rejected — forcing you to rebase first.

Why it matters

Fast-forward merges produce linear history with no merge commits, making git log and git bisect simpler. Many teams require fast-forward merges (via rebase workflow) to keep the main branch's history clean.

See How Git Merging Works for when fast-forward applies and when three-way merge is needed.