Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is a three-way merge?

A three-way merge combines two edited versions of a file by also looking at the version they both started from, the base. For each region it asks which side changed it: if only one did, that change wins; if neither, the base stays; if both changed it differently, it is a conflict left for a person.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

A three-way merge diffs ours and theirs against the base they share, keeps every one-sided change and flags only the two-sided ones.basethe common ancestorourstitle changedtheirsfooter changedthree-way mergewho changed each line?resulttitle and footerwe editthey editourstheirsbaseboth changes, no conflict
  1. Find the base: the last version both sides share. Git calls it the common ancestor; in a pull-edit-publish loop it is the version you pulled.

  2. Diff the base against ours and against theirs. Now every line is known to be unchanged, changed by one side, or changed by both.

  3. Take a change wherever only one side made it. Where neither side touched a region, keep the base's text verbatim.

  4. Where both sides changed the same region differently, stop and mark it as a conflict. The merge cannot guess which is right.

  5. Write the result. Git records it as a merge commit with two parents; a publish tool stores it as the next version if there were no conflicts.

Source: git merge documentation

Three-way merge versus two-way merge

A two-way merge has only the two finished files. When a line differs, it cannot tell whether you changed it or the other person did, or whether one of you deleted something the other kept. It has to ask about every difference, which is why two-way merging is mostly a manual job of picking lines.

Adding the base changes everything. If a line matches the base on your side and differs on theirs, they changed it and you did not, so their version wins without a question. The merge only needs you where both sides moved away from the base in different directions. Wikipedia credits this one idea with making the switch from lock-based version control to merge-based version control possible, and the diff3 program has implemented it for decades.

Where it shows up

git merge uses it whenever the two branches have diverged: the default ort strategy, in the documentation's words, "can only resolve two heads using a 3-way merge algorithm", with the common ancestor as the base. git rebase uses it too, replaying your commits one at a time on top of the new tip, each replay a small three-way merge, which is why a rebase can stop on a conflict several times. When a history has more than one common ancestor, git merges those first into a virtual base and then merges against that.

The same idea works outside git. The Intraface CLI's pull --merge runs a line-level three-way merge on your machine: the version you pulled is the base, your edited files are ours, the board's newest version is theirs. A clean result publishes automatically; only overlapping lines get conflict markers for you to resolve.

Common mistakes

  • Picking the wrong base. If the base is not the real common ancestor, changes one side never made look like deletions or additions. Tools that track history pick it for you; if you run diff3 by hand, make sure the middle file is the shared original.
  • Expecting the merge to understand meaning. It compares text. If you renamed a function and they added a call to the old name, each change sits in its own region, so the merge is clean and the code is broken. Run the tests after every merge.
  • Reading a conflict as a bug. A conflict means both sides changed the same lines. That is information, not an error.

FAQ

What are the three files in a three-way merge?
The base, which is the version both sides started from; ours, the file as you changed it; and theirs, the file as the other side changed it. Git calls the base the common ancestor. The output is a fourth file.
Why does git use a three-way merge instead of a two-way merge?
Because the base tells it who changed what. A line that differs between the two tips but matches the base on one side was changed by the other side only, so it can be taken without asking. Without the base, every difference would need a human decision.
Does a three-way merge ever get the result wrong?
It can produce a clean merge that does not work. Two edits in different places can depend on each other, and the merge compares text, not meaning. Treat a clean merge as something to test, not as proof that the combination is correct.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.