🤝 Merge conflicts without panic

A conflict is not an error. It is a question.

1When conflicts happen (and when they don't)

Say that mantra once more before we start: a conflict is not an error, it is a question. By the end of this page you will believe it.

Here is a secret: most merges are boring. Git zips two lines of work together silently almost every time. You changed one file, the other branch changed a different file? Merged, no questions. You both edited the same file, but in different places? Git still handles it alone, without a peep.

A conflict happens in one classic situation: both lines of work changed the same lines (or lines right next to each other) in the same file. (Or one side deleted a file the other side edited.) Git looks at the two versions, and it refuses to guess which one you meant.

That refusal is a feature, not a failure. Git would rather stop and ask you than silently throw away anyone's work. Both versions are safe. Both photos are still in the album. Nothing has been lost, and nothing will be.

2Two people, one recipe card

🍳 Imagine two people edited the same recipe card while the cook was out. One wrote "2 cloves garlic". The other wrote "3 cloves garlic". When the cook comes back, the cook does not average it to 2.5 cloves. The cook holds up the card and asks: "Which one did you mean?" Git is the cook. It asks instead of guessing.

That is the whole drama of a merge conflict. Not a crash. Not corruption. A cook with a recipe card and a raised eyebrow, waiting for your answer.

3The moment of the question, drawn out

Remember the fork picture from the last lesson? Here is the smallest possible version of one. Both branches started from the same photo and changed the same line of the same file. Where the merge bead would normally appear, git stops and asks.

Notice what is in the picture: every bead is still there. Your photo, their photo, the starting photo. Git paused before taking the next one, that is all.

4What it looks like, exactly

When git asks the question, it does something wonderfully low tech: it types both versions into the file, with three marker lines around them, and lets you open it like any other text file.

# menu.txt, opened in your editor right after git stopped
tomato soup
fresh bread
<<<<<<< HEAD
1 clove garlic       ← your version
=======
4 cloves garlic      ← their version
>>>>>>> their-branch
lemon cake

Decoded line by line:

Marker line	In plain words
<<<<<<< HEAD	"Your version starts here." HEAD is the bookmark you are standing on right now.
=======	"The divider." Everything above is yours, everything below is theirs.
>>>>>>> their-branch	"Their version ends here," signed with the name of the branch it came from.

Those markers are ordinary text. Git literally typed them into the file. Nothing is locked, nothing is encrypted, nothing is broken. You could fix this with any text editor on earth, and that is exactly what you are about to do.

5The 5 step calm recipe

Every conflict, no matter how big the project, is solved the same way. Tape this list to your monitor.

Run git status. It lists every file marked "both modified". That list is your entire todo list. Nothing outside it needs your attention.
Open each listed file and find the <<<<<<< blocks. Your editor may even highlight them for you.
Decide. Keep yours, keep theirs, keep both, or write something completely new. You are the cook now. Any answer you choose is a valid answer.
Delete the three marker lines themselves. When you are done, the file should read like a normal file, with no <<<<<<<, no =======, no >>>>>>>.
git add the file, then git commit. Done. That commit is the merge commit, the new photo that contains your answer, and history carries on as if nothing happened.

⌨️ Try it yourself

Let's manufacture a tiny, harmless conflict in the playground so the real one never scares you. Same throwaway folder as always.

cd /tmp/git-playground
echo "2 cloves garlic" > menu.txt
git add menu.txt && git commit -m "recipe v1"
# make a new bookmark and step onto it (older guides call this checkout -b)
git switch -c more-garlic
echo "4 cloves garlic" > menu.txt
git add menu.txt && git commit -m "more garlic"
# now change the SAME line back on main
git switch main
echo "1 clove garlic" > menu.txt
git add menu.txt && git commit -m "less garlic"
git merge more-garlic
CONFLICT (content): Merge conflict in menu.txt
# there it is! open menu.txt, pick a version, delete the markers, then:
git add menu.txt && git commit -m "settled the garlic debate"
You just resolved a merge conflict. That is the whole skill.

6The escape hatch

One more thing, and it is the most reassuring command in this whole lesson. If you are mid conflict and you do not want to deal with it right now, you can simply take the question back.

🗣 Git's words for today. The question itself is a "merge conflict". The <<<<<<< / ======= / >>>>>>> lines are "conflict markers". And git merge --abort means "forget I asked": it returns everything to the exact moment before the merge, as if you never typed it.

Because every photo on both branches was already committed, you cannot get stuck and you cannot lose work. Worst case, you abort, have a coffee, and try again tomorrow. The two branches will wait patiently.

⚠ One real rule: never commit a file that still contains <<<<<<< markers. The markers are plain text, so git will happily save them, but your code will not run and your teammates will open the file and see your unanswered question marks. Before you commit, search the file for <<<<<<< one last time.

7Check yourself

Q. A merge conflict means...

Nothing is broken and nothing is lost. Both versions are sitting right there in the file, between the markers. Git simply refuses to guess which one you meant, so it asks.

Q. You are mid conflict and feeling overwhelmed. What is the no-shame way out?

git merge --abort. Everything returns to exactly how it was before the merge started. Have a coffee, try again later. Nothing is lost, and both branches keep every committed photo.

🧠 If you remember one thing: a conflict is just git refusing to guess: read the markers, choose a version, delete the marker lines, then git add and git commit.