Merge conflicts: when git needs a human
Both sides changed the same line. Only you can decide the winner.
A conflict is not an error — it is git refusing to guess which version you meant, and handing you the decision.
01Why conflicts happen
You run a merge and git stops with CONFLICT. Take a breath: nothing is broken, no work is lost, and nothing needs to be fixed — one decision needs to be made. Both main and your branch changed the same lines of the same file, and git cannot know which wording is correct. Guessing would be a bug; stopping to ask is a feature.
Understand what git did with the file in that moment: it wrote both versions into the file, separated by markers, and left the rest of the merge waiting. The ball is in your court, and it stays there as long as you like.
Auto-merging notes.txt
CONFLICT (content): Merge conflict in notes.txt
Automatic merge failed; fix conflicts and then commit the result.Automatic merge failed — but the parts that were not conflicting have already merged. You are mid-merge now: the only way out is forward (resolve) or abort.
02The markers, decoded
Open the conflicted file and you find strange brackets. Between <<<<<<< HEAD and ======= is your side — the version on the branch you were standing on (HEAD means where you are, remember). Between ======= and >>>>>>> feature is their side — the branch you merged in.
Every marker line is scaffolding: <<<<<<< says side one begins, ======= says here is the fence, >>>>>>> says side two ends. The names beside them — HEAD and feature — tell you whose version is whose.
| marker | meaning |
|---|---|
| <<<<<<< HEAD | your side starts (the branch you stand on) |
| ======= | the fence between the two sides |
| >>>>>>> feature | their side ends (the branch merged in) |
<<<<<<< HEAD
the version on main
=======
the version on feature
>>>>>>> feature03Resolving, step by step
The resolution is yours to design: keep your side, keep theirs, or write a blend of both. Edit the file until it says what it should really say — and delete every marker line, the <<<<<<<, the =======, and the >>>>>>> included. They are packaging, not content; leaving them in means committing the scaffolding into your project.
When the file looks right, git add it. Adding is you signing the decision: this file is settled. Once every conflicted file is added, git commit finishes the merge — an ordinary commit, with a message, landing as the photograph that unites the two lines.
- —1. edit the file — keep what is correct, delete the markers
- —2. git add <file> — sign off on the decision
- —3. git commit -m "..." — finish the merge
cat the file first and read both sides slowly. Most conflicts resolve to one side in full or a one-line blend — but only once you have actually read what both sides were trying to do.
04The emergency exit
If you get lost halfway — markers deleted wrongly, file in a worse state than you found it — git merge --abort undoes the entire merge. Your folder returns to exactly how it was before you typed git merge: the conflict vanishes, both branches are as they were, nothing is lost.
Abort is not failure; it is the undo button for the whole operation. Professional developers abort messy merges, take a breath, and try again with a clearer head. The merge will wait.
They look scary in tutorials because tutorials must show them. In real life they are occasional, small, and each one makes you faster at reading them.
Practice
We set up both sides to disagree about notes.txt. Walk the whole resolution calmly — every step is one you have already learned.
01.Merge feature and watch the conflict appear.
hint: git merge feature
02.Look inside the file to see both sides.
hint: Try: cat notes.txt
03.Resolve the file: write the final text, with no conflict markers left.
04.Stage the settled file.
05.Commit the merge.
hint: Try: git commit -m "merge feature"