Merge conflicts: how to work through one

A merge conflict happens when two branches changed the same line in different ways, and git will not decide for you which version is right.

As long as the edits do not overlap, git combines them without a word: different files, different places in one file, all of it goes together on its own. Only the piece that was touched twice becomes disputed. The stop looks like this:

$ git merge feature-x
Auto-merging report.txt
CONFLICT (content): Merge conflict in report.txt
Automatic merge failed; fix conflicts and then commit the result.

The merge halted halfway. git status tells you what did not line up:

$ git status
On branch main
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   report.txt

The markers in the file

Git wrote both versions into the file and separated them with three marker lines:

Title
<<<<<<< HEAD
contact: help@example.com
=======
contact: team@example.com
>>>>>>> feature-x
end

Between <<<<<<< HEAD and ======= sits the version from the branch you are standing on. Between ======= and >>>>>>> feature-x sits the version from the branch you are merging in. The rest of the file is untouched.

The order of the fix

Open the file in an editor and make the disputed spot look the way it should look after the merge. Keep one of the versions, or write a third one, and delete all three marker lines:

Title
contact: team@example.com
end

Then tell git the question is settled and finish the merge:

$ git add report.txt       # mark the conflict resolved
$ git status
On branch main
All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

$ git commit
[main 2a2aa47] Merge branch 'feature-x'

There can be several conflicted files. Go through every entry under Unmerged paths and only then commit.

If you lose the thread halfway through, there is always a way out:

$ git merge --abort        # call the whole merge off

The repository goes back to exactly the state it was in before git merge: the markers vanish from the files and both branches sit on their old commits. Nobody's work is lost.

Common mistakes

A forgotten marker. git add does not inspect the content, so a stray ======= line can go into the commit along with your text. Read the file with your own eyes before git add, or better, look at git diff --staged.

Running git add without editing the file. The command marks the conflict resolved; it does not resolve it. Editor first, git add second.

A conflict does not mean the repository is broken. It means one line was edited in two places, and git asks which version to keep instead of quietly throwing someone's work away.

Where this is in the book

Chapter 5. Branches: parallel versions of a project walks through a conflict end to end, from the CONFLICT line to the closing commit.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.