What is a merge conflict? (two changes, same lines, someone has to choose)

What it actually is

A merge conflict is git telling you: two versions of this file changed the same lines differently, and I don’t know which one you actually want. Most of the time git merges changes on its own without you noticing, because two branches usually touch different parts of a file. The conflict only happens when both sides edited the identical line or block, and git has no logical way to pick a winner.

Think of two people editing the same paragraph of a shared document while offline, then trying to combine their copies afterward. If they each rewrote different paragraphs, you can stitch the document back together easily. If they both rewrote the same sentence, someone has to sit down, look at both versions, and decide which sentence stays. Git is that stitching step: it merges everything it safely can, then stops and hands you the sentence both people rewrote.

Why your AI just did this

Your agent almost always hits this while combining two lines of work: pulling in the latest changes from a shared branch, merging a git worktree or feature branch back into main, or applying a pull request, while a file it also edited locally has since changed on the other side too. Git pauses the merge right there instead of guessing, and writes both versions directly into the file using conflict markers, <<<<<<<, =======, >>>>>>>, so nothing is silently overwritten. A careful agent will read both sides, work out which change was actually intended (or that both need to be kept), edit the file to the final result, then remove the markers and continue.

When you’ll run into it

• Running git status and seeing both modified: <file> under “Unmerged paths”, that file has an unresolved conflict sitting inside it right now.
• Opening the file and seeing something like:

  <<<<<<< HEAD
  const greeting = "Hello, world!";
  =======
  const greeting = "Hey there!";
  >>>>>>> feature-branch

• The terminal printing Automatic merge failed; fix conflicts and then commit the result. right after a git merge or git pull (pull is really fetch plus merge in one step, so it fails the same way).
• Your agent pausing mid-task to say something like “there’s a conflict in Header.tsx, here’s how the two versions differ, which one do you want?”
• Two agent sessions, or an agent and a teammate, working on the same file on different branches and both touching the same function.

What to check

• Every <<<<<<<, =======, and >>>>>>> line is gone from the file. A leftover marker is broken code, not a resolved conflict
• The file still runs after resolving it, it’s easy to keep syntactically invalid code by accident when stitching two versions together
• git status shows the file has moved out of “Unmerged paths” once you git add it
• If you’re unsure which side is correct, ask your agent to explain what each version was trying to do before you pick
• If it’s turned into a mess you don’t understand, git merge --abort backs out cleanly to before the merge started, nothing is lost

Say it like a dev

Instead of: “the code has weird broken symbols in it now” Say: “there’s a merge conflict, I need to resolve it and remove the conflict markers”

Instead of: “just make it work again” Say: “pick which version of these lines is correct, or combine them, then delete the markers”

Instead of: “cancel whatever it’s doing to this file” Say: “run git merge --abort to back out of this merge cleanly”