Merge Conflicts: Don't Panic

Conflicts are normal

You merge a branch and Git says:

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

Many beginners think they broke something. You did not. A conflict is Git being honest: "Two people changed the same place in different ways, and I cannot guess which one you want. You decide."

Git merges automatically whenever it can. Changes in different files, or different parts of the same file, merge with no fuss. A conflict happens only when both branches changed the same lines (or lines right next to each other). In a team, this is routine, and resolving one takes a couple of minutes once you know the steps.

How a conflict happens

Two branches start from the same commit. Each changes the jollof price on the same line:

        main:     A --- B  (price 3200)
                   \
        price-update:  C  (price 3500)

When you merge price-update into main, Git sees that line changed on both sides to different values, so it stops and asks you.

Step 1: read the conflict markers

Git edits the conflicted file and marks the problem with three lines:

<<<<<<< HEAD
Jollof rice - 3200
=======
Jollof rice - 3500
>>>>>>> price-update

Everything between <<<<<<< and ======= is yours. Everything between ======= and >>>>>>> is theirs. The rest of the file, outside the markers, merged cleanly.

Step 2: decide and edit

Your job is to edit the file so it contains the final version you want, and to delete all three marker lines. You can:

• Keep yours, keep theirs, or
• Combine both, or write something new.

After you edit, the file should be normal text with no <<<<<<<, ======= or >>>>>>> in it. VS Code makes this easy with buttons that say Accept Current Change, Accept Incoming Change and Accept Both.

Step 3: add and commit

Telling Git "I fixed this file" is done with git add. When every conflicted file is added, you commit to finish the merge:

git add menu.txt
git commit -m "Merge price-update, keep the new price"

(You can run git commit without -m and Git proposes a ready-made merge message.) git status at any point tells you what is left to do: files listed under Unmerged paths still need you.

Try it: resolve a real conflict

This repository is in the middle of a conflicted merge. On main, the jollof price was changed to 3200. On the branch price-update, it was changed to 3500. We tried to merge price-update, and it conflicted.

1. Run git status. See the Unmerged paths, and the U badge by the file.
2. Click menu.txt in the file list and read the markers.
3. Edit it to the final version you want, with no markers. Click Save file.
4. git add menu.txt, then git commit -m "Merge price-update".
5. git log --oneline shows your merge commit with two parents.

Changed your mind? Abort

If you start a merge and feel lost, you can always back out:

git merge --abort

Git puts everything back as it was before the merge. Nothing is lost. You can then talk to your teammate, or try again.

Avoiding most conflicts

You cannot avoid all of them, but good habits prevent most:

1. Pull often. Get your teammates' changes (lesson 7) before you start new work, and before you push.
2. Keep branches short-lived. The longer a branch lives, the further it drifts from main.
3. Make small, focused commits and small pull requests.
4. Talk to your team. If two people must edit the same file, tell each other.
5. Do not reformat whole files (for example, changing every indent) in a commit with other changes. It makes every line conflict.

Try it

First, resolve the price conflict. The merge has already failed and left the markers. Keep the new, higher price (3500) from the branch.

Now try the other way out. The same kind of conflict happened, but you decide that the incoming change should wait. Abort the merge and keep main exactly as it was.