Why conflicts happen
Intermediate Core Git Git CLI
Why this matters
The word "conflict" sounds like breakage, and the wall of markers that appears in the file looks like corruption. Neither is true. Understanding the comparison Git performs takes five minutes and turns the whole topic from alarming into mechanical.
What Git compares
When you merge, Git finds the common ancestor: the commit where the two lines of work separated. Then it compares three versions of every file — the ancestor's, yours, and theirs — line by line:
| Situation | What Git does |
|---|---|
| Neither side changed the line | keeps it |
| Only your side changed it | takes yours |
| Only their side changed it | takes theirs |
| Both sides changed it, to the same text | takes it once |
| Both sides changed it, differently | conflict: marks the file and stops |
The important part is the third row. Two people can edit the same file all day with no conflict, as long as they edit different lines. That is why merges usually pass in silence: Git resolves them by taking whichever side moved.
What it looks like
$ git pullFrom https://gitlab.com/northwind-trails/trailguide
b6ae751..e3e760c main -> origin/main
Auto-merging docs/faq.md
CONFLICT (content): Merge conflict in docs/faq.md
Automatic merge failed; fix conflicts and then commit the result."Auto-merging" then "CONFLICT" is the normal pair: Git tried, combined what it could, and stopped at the part it could not. git status then explains exactly where you stand:
$ git statusOn branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
(use "git pull" if you want to integrate the remote branch with yours)
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: docs/faq.md
no changes added to commit (use "git add" and/or "git commit -a")Three phrases to notice, because they are the whole procedure: "You have unmerged paths" (you are mid-merge), "both modified" (the conflicting file), and the two hints — git add to mark a file resolved, git merge --abort to undo the whole thing.
To list only the conflicted files, which matters when there are many:
$ git diff --name-only --diff-filter=Udocs/faq.mdWhen conflicts can occur
| Operation | Can conflict | Notes |
|---|---|---|
git merge |
yes | the classic case |
git pull |
yes | it contains a merge |
git rebase |
yes | once per replayed commit (lesson 11.5) |
git cherry-pick |
yes | same mechanism |
git stash pop |
yes | your stash against the current files |
git revert |
yes | if the code moved since |
git switch, git commit, git log |
no | these never combine two versions |
Why documentation conflicts so easily
Prose is more conflict-prone than code, for two reasons worth knowing if you write docs:
- Reflowing. Re-wrapping a paragraph changes every line in it, so any other edit inside that paragraph conflicts. Keeping one sentence per line, where the project allows it, almost eliminates this.
- Everyone edits the top. README intros, FAQ first answers and changelog headings attract simultaneous edits.
Binary files are the extreme case: two versions of an image cannot be combined at all, so Git can only ask you to pick one whole file (lesson 11.2).
Common mistakes
- Panicking and deleting the file to "start clean". The markers are a normal state;
git merge --abortis the clean exit. - Assuming a conflict means someone did something wrong. It means two people worked on the same lines, which is normal.
- Expecting Git to pick the newer change. It has no way to know which is better, and guessing would lose work.
- Thinking a conflict is on the server. It happens entirely in your working tree; the remote is untouched until you push.
Try it yourself
Goal: create a conflict deliberately and look at it, without resolving it yet.
- In the playground, on
main, note the first answer indocs/faq.md. - Create a branch:
git switch -c docs/conflict-demo, change that answer to one wording, commit. - Go back:
git switch main, change the same line to a different wording, commit. - Merge:
git merge docs/conflict-demo. Read the CONFLICT line. - Run
git statusandgit diff --name-only --diff-filter=U. - Undo it all:
git merge --abort, thengit statusto confirm you are clean.
Expected result: step 4 reports CONFLICT (content): Merge conflict in docs/faq.md; step 5 lists that one file; step 6 returns everything to normal as if nothing happened.
Show solution
The --abort in step 6 is the point of the exercise: a conflict is completely reversible until you commit the merge. Keep the branch; lesson 11.3 resolves this same conflict properly.