Resolve merge conflicts

In chapter 4, Git merged on its own. But sometimes it stops and asks for your help: that's a conflict. Good news: it's normal, it happens to everyone, and it's always resolved with the same method.

By the end of this chapter, you will be able to:

• ●Explain why a conflict happens
• ●Find the conflicted files with git status
• ●Read the conflict markers in a file
• ●Choose the right version: yours, the other one or a mix
• ●Finish the merge with git add and git commit
• ●Cancel a merge with git merge --abort

Imagine a shared document. You and a teammate edit the same sentence at the same time. The software can't guess which one to keep: it asks you to decide.

A conflict is not an error, and nothing is broken. It's Git telling you: "I can't decide for you".

Let's take a concrete example with my-portfolio:

Git warns you right away:

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

First step: find out which files are involved. Your reflex, 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:   index.html

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

Conflicted files are in the Unmerged paths section, marked both modified (changed on both sides). Here, a single file: index.html.

Open the conflicted file in your editor. Git added markers that show both versions, one above the other:

<<<<<<< HEAD
<h1>Bonjour</h1>
=======
<h1>Welcome</h1>
>>>>>>> feature/header

• ●<<<<<<< HEAD: the start of the conflict. Right below, your version, from the branch you're on (here main).
• ●=======: the separator between the two versions.
• ●>>>>>>> feature/header: the end of the conflict. Right above, the version from the other branch, whose name is shown.

Resolving a conflict means writing the final version of the passage. You have three options:

• ●Keep your version (the top one): you delete the bottom version.
• ●Keep the other version (the bottom one): you delete the top version.
• ●Combine both: you write a mix, for example <h1>Bonjour and welcome</h1>.

In every case, you also delete the three marker lines. For example, if you keep your version, the passage becomes:

<h1>Bonjour</h1>

Once all markers are gone from the file, tell Git the conflict is resolved with git add, then finish the merge with a commit:

[main 4e9a1c7] Merge feature/header, keep the Bonjour title

Check that everything is in order:

On branch main
nothing to commit, working tree clean

Lost in the middle of a conflict, or want to talk to your team first? You can cancel everything:

Your repository goes back exactly to how it was before the git merge. Nothing is lost, on either side. You can run the merge again when you're ready.

Conflicts are normal, but a few habits make them rarer and smaller:

• ●Run git pull often: you work on the latest version.
• ●Merge often: a branch that lives for three weeks drifts much further from main than a branch that lives for two days.
• ●Make small, focused commits: fewer lines touched, fewer collisions.
• ●Talk to your team: if you need to edit the same file, coordinate.
• ●Split your code into small files: two people are less likely to touch the same one.

Your cheat sheet for this chapter:

• ●Leaving <<<<<<< markers in the code: the file no longer works. Search for <<<<<<< in your files before committing.
• ●Running git add without rereading the file: check that the result is what you want.
• ●Erasing the other person's work without understanding it: read both versions, and ask if needed.
• ●Forgetting a file: as long as a file stays in Unmerged paths, Git refuses the commit. Run git status again.
• ●Running git merge --abort every time out of fear: knowing how to cancel is useful, but resolving a conflict is a skill you learn quickly.

How does Git know there's a conflict? It doesn't compare two versions of the file, but three:

• ●The version on your branch (HEAD)
• ●The version on the other branch
• ●The version of the common ancestor: the last commit both branches share, before they split

If a line changed on only one side compared to the ancestor, Git takes that change without hesitation. If it changed on both sides, differently, it's a conflict. This is called a three-way merge.

You can find the common ancestor of two branches:

3f2a1b4c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a

Last quiz of the course: check that you can resolve a conflict. Click the answer that looks right: every answer is explained.