Resolving a conflict, step by step

The calm four-step procedure

A conflicted merge feels broken, but structurally it is just a paused merge. Git stopped mid-operation and is waiting for exactly two things from you, fixed files and then a commit.

Knowing the fixed procedure is what turns a five-alarm moment into two calm minutes, which is why every working engineer has it memorized.

1. See the damage report. git status lists each conflicted file under Unmerged paths as both modified. Only those files need you.
2. Edit each conflicted file. Keep your side, keep theirs, or write a combination, then delete the three marker lines. The file should end up looking exactly how you want it to look, since the markers are scaffolding rather than content.
3. Stage the fixed file with git add cake.txt. During a conflict, add carries the extra meaning that this file is resolved.
4. Finish the merge with git commit. Git pre-fills a message like Merge branch 'brown-butter', and accepting it finishes the job.

$ git add cake.txt
$ git commit
[main 9c8b7a6] Merge branch 'brown-butter'

The most common beginner mistake is step 2 half-done, fixing the text but leaving a stray >>>>>>> line behind, which then gets committed as garbage and usually breaks the file for everyone. Search each file for <<<, ===, and >>> before staging it.

Performing step 2 by hand

The conflicted file held the marked block from lesson 6-1, and the decision is that the incoming side wins, so the middle line should read Add brown butter. Resolving it means writing the file as you want it to end up, with no markers anywhere.

printf "Preheat oven to 180C\nAdd brown butter\nBake for 25 minutes\n" > cake.txt
cat cake.txt

Output

Preheat oven to 180C
Add brown butter
Bake for 25 minutes

The resolved file is just the text you want. There is no <<<<<<<, no =======, and no >>>>>>>, because all three were scaffolding that Git inserted to show you the choice.

Doing it with printf here makes the point clearly, but in real work you edit the file in your editor and delete the marker lines by hand. The end state is the same either way, and the end state is the only thing Git checks.

A recorded session

This session finishes the merge. cake.txt has already been edited, the wanted line kept, and the marker lines deleted.

Each step below shows the command and the output it printed.

Step 1. Check which files are still marked as conflicted.

~/recipe-book $ git status
On branch main
You have unmerged paths.
  (fix conflicts and run "git commit")

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

Note that both modified is a status you only see during a conflict, and that Git prints the next two commands as hints.

Step 2. Mark cake.txt as resolved.

~/recipe-book $ git add cake.txt

Step 3. Seal the merge with a commit, letting Git supply the message.

~/recipe-book $ git commit
[main 9c8b7a6] Merge branch 'brown-butter'

The resulting commit is the two-parent merge commit from lesson 5-3, no different for having needed a human decision along the way.

The escape hatch, and avoiding conflicts

Mid-conflict and overwhelmed? You can always back out completely.

$ git merge --abort

This cancels the merge and returns the repository to the exact state it was in before you ran git merge. Nothing is lost, so the correct response to feeling out of your depth is to abort, breathe, and try again when you have time to think.

Preventing every conflict is impossible, but keeping them small is not.

• Merge often. Short-lived branches touch fewer lines, so they collide less.
• Keep commits focused. Lesson 2-3's habit pays off here, because small changes conflict in small, readable ways.
• Talk to your team before two people rewrite the same file, which is the cheapest fix of all.

Once the markers are gone, tell Git the conflict is resolved with git add on the file, then complete the merge with git commit.

The add is what marks each conflicted file as resolved, which is a second meaning the command only carries during a merge. The commit then seals the whole thing with the merge commit.

Both steps are required. Until you finish them, the repository stays in the mid-merge state and git status keeps saying You have unmerged paths, which is Git's way of refusing to let you forget an operation is half-done.

The full command is git merge --abort.

It rewinds the repository to its pre-merge state, discarding the partial merge and the marker-filled files along with it.

The command only exists while a merge is actually in progress, and it is the reason a conflict is never a trap. Whatever the markers look like, there is always a way back to the moment before you typed git merge.