Resolving Merge Conflicts Step by Step

Sooner or later two branches change the same line. You change your tagline on main to “Front-end developer in Lagos.” while your tagline branch, started earlier, rewrote the same line to “Front-end developer who loves accessible UI.” Git can’t know which is right, so it stops and asks. That’s all a merge conflict is: a question. I’ve helped hundreds of people through their first one, and the panic always comes from the unfamiliar markers, never from the actual problem.

What Git tells you

git switch main
git merge tagline

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

You’re now in the middle of a merge. Any files that merged cleanly are already staged. Run git status to see the rest:

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:   index.html

no changes added to commit (use "git add" and/or "git commit -a")

Read that output; it’s the whole procedure. Fix the conflicts, mark each file resolved with git add, then git commit. Or abort.

Reading the markers

Open index.html. Git has written both versions into the file, fenced by markers:

    <h1>Maya Okafor</h1>
<<<<<<< HEAD
    <p>Front-end developer in Lagos.</p>
=======
    <p>Front-end developer who loves accessible UI.</p>
>>>>>>> tagline

• The top half, from the opening marker labelled HEAD down to =======, is your side: the branch you’re on, here main.
• The bottom half, from ======= down to the closing marker labelled tagline, is their side: the branch you’re merging in.

Everything outside the markers merged without trouble. A file can contain several of these blocks, so search the file for the opening marker (seven less-than signs) until there are none left.

Resolving it, step by step

1. Decide what the result should be. Not “which side wins” by reflex; what should the page actually say? Often it’s a combination. Here, both facts are good:

    <h1>Maya Okafor</h1>
    <p>Front-end developer in Lagos who loves accessible UI.</p>

2. Remove every marker. The three marker lines must go. Git doesn’t read the file to check; it’s your job.

3. Check the result. Open the page in a browser, run your tests (npm test once the portfolio has them), and run:

git diff --check

It warns about any leftover conflict markers. Five seconds well spent.

4. Mark it resolved and finish.

git add index.html
git status        # "All conflicts fixed but you are still merging."
git commit        # editor opens with "Merge branch 'tagline'"; save and close

git merge --continue does the same as that final git commit. The merge commit now has two parents, like any other.

If you know one side should win for a whole file, skip the editing: git restore --ours index.html keeps your branch’s version and git restore --theirs index.html keeps the incoming one. Then git add it as usual.

Bailing out

If a conflict is bigger than you expected, or you merged the wrong branch, you can always retreat:

git merge --abort

Your branch, index and files go back to exactly how they were before git merge. Nothing is lost. It’s often smart to abort, update or tidy the branch, and try again with a clear head.

The same markers and the same fix-add-continue routine appear whenever Git combines two versions of a line: during a rebase, when you apply a stash, and when git pull merges someone else’s work into yours. Learn the routine once here and every later conflict in this course will look familiar. Only the command you use to continue or abort changes.

Making conflicts easier to read

By default you see only the two sides. Ask Git to show the original lines too:

git config --global merge.conflictStyle zdiff3

Now each conflict has a third section between ||||||| and ======= showing the merge base. Seeing what the line was before either change usually makes the right answer obvious: you can see what each side meant to do, not only what it ended up with.

Editors help too. VS Code highlights each block with buttons such as Accept Current Change, Accept Incoming Change and Accept Both Changes, plus a three-way merge editor. Use them, but read the result; Accept Both often produces two <p> tags where you wanted one.

Merging is one way to combine histories. Next you’ll meet the other, rebasing, and the one rule that keeps it safe.