Three-Way Merge Explained: Why Git Needs the Base Version and What a Conflict Really Is

Why two versions are not enough

Take a configuration file with a line timeout = 30. Your copy says timeout = 60; your colleague's says timeout = 30. A tool holding only those two copies sees a difference and nothing else. Did you raise the timeout, or did your colleague lower it? Each interpretation leads to a different merge result, and the two copies alone cannot distinguish them.

Now add the version you both started from: timeout = 30. Your copy differs from the base; your colleague's does not. You changed it; they left it alone; the merge should take your value. The base turns an ambiguous difference into an attributable change, and attribution is what lets the merge be automatic.

The four cases, line by line

A three-way merge runs two diffs — base against ours and base against theirs — and walks through the base aligning the two sets of changes. For each region of the base there are four possibilities:

The fourth row surprises people: if both sides applied the same fix, the merge takes it once and does not complain. That is why cherry-picking the same commit onto two branches and merging them later is usually painless.

The fifth row is the only one that stops the process. Note what it does and does not require. It requires that both sides changed the same region of the base — overlapping or adjacent hunks — in different ways. It does not care what the changes mean. Two edits to the same line are a conflict even if they are compatible; two edits to different functions are not a conflict even if together they break the build.

Adjacent hunks and why "I didn't touch that line" is not a defence

Hunks are regions of change plus a little context. When your hunk ends on line 40 and theirs begins on line 41, the diff algorithm cannot safely say the regions are independent: the boundary itself moved, and placing both changes requires deciding an order. Git treats touching hunks as conflicting. This is the source of most "but we edited different things" conflicts — one person added a function at the end of a file, the other added a different one at the same end, and the tool, quite reasonably, does not know which should come first.

Reading conflict markers

When a conflict is found, the merge writes both versions into the file:

<<<<<<< HEAD
timeout = 60
=======
timeout = 15
>>>>>>> feature/faster-retries

Everything between <<<<<<< and ======= is ours; everything between ======= and >>>>>>> is theirs. What this layout omits is the base — what the line said before either of you changed it — and without it you are back to the two-way guessing problem. Git's diff3 conflict style adds it:

<<<<<<< HEAD
timeout = 60
||||||| base
timeout = 30
=======
timeout = 15
>>>>>>> feature/faster-retries

Now the intent is legible: we doubled the timeout, they halved it. That is a decision for a person — perhaps the retry logic they wrote makes the shorter timeout correct — but at least it is the right decision being made. Enable it once with git config --global merge.conflictStyle diff3 (or zdiff3 in Git 2.35+, which trims lines common to both sides out of the markers). Most engineers who try it do not go back.

Resolving: four honest options

For each conflict there are exactly four outcomes, and a good merge tool offers them as buttons rather than making you edit markers by hand:

• Ours — keep our version, discard theirs.
• Theirs — the reverse.
• Both — keep ours followed by theirs. Correct more often than it sounds: two functions added at the same place, two entries appended to a list, two import lines.
• Base — revert the region to the common ancestor, discarding both edits. Rare, but it is the right answer when both changes were attempts at the same thing and a third approach is coming.

Anything else — combining half of one side with half of the other, or writing new code — is a fifth option: editing. It is sometimes necessary and always the one to double-check, because the merged result then contains lines that appeared in neither branch and were never reviewed.

"Merged cleanly" is a textual claim

A clean merge means no region of the base was changed differently by both sides. It says nothing about whether the combination makes sense. The canonical example: one branch renames a function, the other adds a new call to it under the old name, in a different file. Neither hunk overlaps; the merge is clean; the build fails. Static languages catch this at compile time, dynamic ones at run time, and a configuration file never catches it at all. The merge commit deserves the same tests as any other commit — more, since it is the first time the two sets of changes have existed together.

Rebase is a merge in a loop

Rebasing a branch replays each of its commits on top of a new base. Each replay is a three-way merge: base is the commit's original parent, ours is the new tip, theirs is the commit's own change. The conflicts you resolve during a rebase can recur on the next commit because the base moves one step each time and the same region is touched again. Git's rerere ("reuse recorded resolution") records how you resolved a conflict and reapplies it when the identical conflict reappears — switch it on with git config --global rerere.enabled true and long rebases become far less tedious.

Three-way merge outside version control

The algorithm has nothing to do with Git in particular. It applies wherever two parties edit a shared starting point: two engineers editing the same server config by hand, two translators working on the same strings file, two versions of a document that each diverged from a sent copy. In all of these you usually still have the original — the file as deployed, the file as sent — and with it the merge is mostly automatic. Without it you are reduced to reading both versions side by side and guessing at intent, which is exactly the two-way problem the base was invented to solve.

Frequently asked questions