Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Merge: Fast-Forward, Three-Way, and Conflict Resolution

Fast-forward moves a pointer; a three-way merge compares both tips to a merge base. Where ours and theirs invert, and why a squashed merge blocks re-merging.

~5 min readGit
#Git#Merge#Conflicts#CLI
3D illustration of two branch tracks joining with one conflict chip resolved

Quick Summary

A merge joins two commit histories by creating a commit with two parents, or by moving a pointer when no join is needed. Fast-forward moves the branch tip forward when the target is a strict descendant — no new commit, perfectly linear history. A three-way merge (implemented by the ort strategy since Git 2.34) compares both tips against their merge base and produces a commit combining the changes.

Conflicts appear only where both sides changed the same region of the same file relative to that merge base. Git marks them in the file with seven-character fences and stops, leaving the index in an unmerged state; the merge is finished by editing, git add, then git commit — or abandoned with git merge --abort.

Two defaults decide what you get: merge.ff and whether the target branch has a linear history. git merge --ff-only makes the fast-forward case explicit and fails rather than silently creating a merge commit, which is what most "keep history linear" policies actually want.

Basic Syntax & Core Signatures

bash
git merge feature/login # default: fast-forward if possible git merge --no-ff feature/login # always create a merge commit git merge --ff-only origin/main # fail if a merge commit would be needed git merge --squash feature/scratch # stage the combined diff, no commit, no ancestry git merge --no-commit --no-ff feature/x # stop before committing to review git merge-base main feature/login # the common ancestor used for the 3-way merge git merge-base --is-ancestor A B && echo "B contains A" git diff --name-only --diff-filter=U # list conflicted files git checkout --ours path/file.ts # keep the current branch's version git checkout --theirs path/file.ts # keep the incoming branch's version git merge --continue # after resolving and staging git merge --abort # restore the pre-merge state git rerere # reuse recorded conflict resolutions
bash
# Squash-merge on the remote (GitHub, GitLab): linear history, one commit per PR, # and no ancestry link, so the branch cannot be "continued" afterwards. git switch main git merge --squash feature/login git commit -m "feat(login): add rate limiting (#142)"

Conflict markers are configurable. merge.conflictStyle=zdiff3 adds the merge base as a third section, which turns a guess into a comparison:

text
<<<<<<< HEAD const timeout = 3000; ||||||| base const timeout = 5000; ======= const timeout = 8000; >>>>>>> feature/login

Key Comparison Table

ModeCreates a commitPreserves branch shapeReverts cleanlyUse when
Fast-forwardNoLinear, no trace of the branchWith git revert <tip> per commitFeature is a straight continuation
--no-ffYesExplicit merge bubbleWith git revert -m 1 <merge>You want the branch as one unit in history
--squashOne, authored by youNo ancestry at allWith git revertSmall PRs on a policy-linear main
Three-way (automatic)YesBubbleSame as --no-ffDiverged branches
Rebase instead of mergeNo merge commitRewritten linear historyPer commitLocal branches only
Conflict stateFile contentIndex stageCommand to move on
UnmergedMarkers present1, 2, 3Edit, git add
Resolved by taking oursNo markers0git add
Modify/deleteFile present or absent1, 2git rm or git add
Both addedMarkers, diff3 style2, 3Edit, git add
BinaryCannot merge2, 3git checkout --ours/--theirs then git add

Practical Edge Cases & Deep Dives

1. ours and theirs mean the opposite during a rebase

During a merge, --ours is your current branch and --theirs is the branch being merged in. During a rebase, Git checks out the upstream branch and replays your commits onto it, so --ours is the upstream content and --theirs is your own commit. Choosing by the label rather than by reading the file is how a "resolve" silently reverts your work.

bash
git status # "rebase in progress; onto abc123" — remember: labels inverted git diff # read the conflict, then decide, then: git add <file> git rebase --continue

If in doubt, git log --merge -p <file> shows only the commits that touch the conflicted region, from both sides.

2. Modify/delete and add/add conflicts

A modify/delete conflict means one side deleted the file and the other edited it. Git leaves the file in the working tree and marks the index; the resolution is a decision, not a text edit:

bash
git rm path/file.ts # accept the deletion git add path/file.ts # accept the modification

An add/add conflict happens when both branches created the same path independently; the index has stages 2 and 3 but no base (stage 1). git checkout --ours -- path followed by git add is the common resolution, but read both versions first — they usually implement the same feature twice, and the correct answer is a merge of both intents, not either file.

3. --squash and the ancestry trap

A squashed merge produces a commit with different content from the branch's commits and no parent link. Git cannot know the branch was merged, so re-merging the same branch later replays every commit again, and git branch --merged does not list it. If the branch continues after a squash merge, delete it and branch again from main; do not keep pushing to it.

4. Reverting a merge commit

git revert <merge> needs -m 1 to say which parent is "mainline" (parent 1 is the branch you were on when you merged). Without it, Git refuses. The revert itself is a new commit that undoes the merge, but it also means re-merging the same branch later will not bring the changes back — Git sees the merge as already applied. The fix in that case is reverting the revert, on a new branch.

bash
git revert -m 1 9c1e2f4

5. rerere: record once, resolve automatically

rerere (reuse recorded resolution) saves conflict resolutions keyed by the conflict's content, so the same conflict during a later rebase is resolved without you. It is the standard trick for long-lived branches that get rebased repeatedly:

bash
git config --global rerere.enabled true git config --global rerere.autoupdate true # stage resolutions automatically

It also helps when a merge is aborted and retried after fetching more commits: the same hunks conflict identically, and the resolution is already on disk.

6. Merge strategies and drivers

ort is the default and handles renames better than the old recursive. For generated files — lockfiles, snapshots, compiled output — a merge driver that takes one side wholesale removes an entire class of conflicts:

bash
# .gitattributes package-lock.json merge=ours *.snap merge=ours

This conflicts with reproducibility: taking "ours" for a lockfile means the merged result may not match any developer's install. Prefer regenerating the lockfile after the merge (npm install) and committing the result.

One last default worth knowing: merge.ff can be set to only per repository, which makes every git merge behave like --ff-only and fail rather than create a merge commit. Teams that want linear history usually set it in a checked-in .gitconfig include or a setup script, because a global setting silently changes behaviour in unrelated repositories.

Common Git Operation Mistakes

SymptomCauseFix
Merge created a commit when none was wantedDefault allowed a three-way mergegit merge --ff-only
Conflict markers committedgit add -A while unresolved, git commit forcedSearch for <<<<<<<, git commit --amend
Resolution reverted the other branch's work--ours/--theirs used during a rebaseRead the diff, then pick; labels are inverted
"fatal: You have not concluded your merge"Unfinished merge left in the indexgit merge --continue or git merge --abort
Rebase ran instead of a mergepull.rebase or branch.<name>.rebase set globallygit pull --no-rebase, or unset the config
Same branch merged twice, duplicating commits--squash merge and continued branchDelete the branch after the squash, re-branch from main
git revert of a merge refuses to run-m parent not specifiedgit revert -m 1 <sha>
Merge ignores a directory renameVery large structural change, low similarity thresholdgit merge -X find-renames=30%, or resolve manually

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.