shellstreak

How to resolve a git merge conflict

Updated · Every command on this page ran in our practice shell

Short answer

Run git status to see the conflicted files, open each one and replace the block between <<<<<<< HEAD and >>>>>>> with the text you want (deleting all three marker lines). Check with git diff --check, then git add the file. When every file is added, git commit --no-edit finishes the merge. git merge --abort cancels it instead.

A merge conflict means two branches changed the same lines and git won't guess which version is right. It looks scary, but it's always the same four steps: see which files conflict, edit them, git add them, and git commit. Every example below ran in a practice shell on a small repository for a bakery's menu; try them in the mini terminal.

Branches: create, switch, delete

A branch is a name for a line of work. git branch lists them, git branch soup creates one, git switch soup moves to it, and git switch -c soup does both at once. git branch -d soup deletes a branch that's fully merged; git branch -D soup deletes it even if it isn't.

Why a merge conflicts

On main, someone renamed Sourdough to Sourdough loaf. On the prices branch, someone raised its price. Both edits touch line 1 of menu.txt. Git merges changes to different lines on its own, but when both sides changed the same lines it stops and asks you.

example
learner@shellstreak:~/menu$ git merge prices
Auto-merging menu.txt
CONFLICT (content): Merge conflict in menu.txt
Automatic merge failed; fix conflicts and then commit the result.

See which files are conflicted

git status lists conflicted files under Unmerged paths as both modified. In short form (git status -s) they show as UU. While a merge is in progress, git won't let you commit until every one of them is resolved.

example
learner@shellstreak:~/menu$ 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:   menu.txt

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

Read the conflict markers

Git writes both versions into the file between markers. Everything between <<<<<<< HEAD and ======= is your branch's version (the one you're merging into; git labels it HEAD). Everything between ======= and >>>>>>> prices is the incoming branch's version. Lines outside the markers merged cleanly.

example
learner@shellstreak:~/menu$ cat menu.txt
<<<<<<< HEAD
Sourdough loaf 6
=======
Sourdough 7
>>>>>>> prices
Rye 5
Croissant 3

Fix the file and git add it

Edit the file so it says what it should, and delete all three marker lines. Often the right answer combines both sides; here it's Sourdough loaf 7. Any editor works. In the practice shell, which has no editor, rewrite the file with printf. Before you add it, git diff --check reports any leftover conflict marker (and trailing spaces), and prints nothing when the file is clean. Then git add the file: that's how you tell git this conflict is resolved.

example
learner@shellstreak:~/menu$ printf 'Sourdough loaf 7\nRye 5\nCroissant 3\n' > menu.txt && git diff --check && git add menu.txt && git status
On branch main
All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:
	modified:   menu.txt

Finish the merge with git commit --no-edit

Once every conflicted file is added, run git commit --no-edit. Git already prepared the message Merge branch 'prices'; plain git commit (or git merge --continue) opens your editor to let you change it. (In vim: Esc, then :wq.) The result is a merge commit with both branches as parents.

example
learner@shellstreak:~/menu$ printf 'Sourdough loaf 7\nRye 5\nCroissant 3\n' > menu.txt && git add menu.txt && git commit --no-edit && git log --oneline -n 3
[main 43dd47b] Merge branch 'prices'
43dd47b (HEAD -> main) Merge branch 'prices'
e5c914c Name the sourdough loaf
488ef37 (prices) Raise sourdough price

Keep both sides: delete just the markers

When both branches added different lines in the same place (here, one added Sunday hours and the other a holiday closing), the fix is often to keep both lines and drop the markers. sed can delete every line that starts with seven <, = or > characters. Check the result with git diff --check and cat before you git add it.

example
learner@shellstreak:~/menu$ git diff --check; sed -i '/^[<=>]\{7\}/d' hours.txt && git diff --check && cat hours.txt
hours.txt:3: leftover conflict marker
hours.txt:5: leftover conflict marker
hours.txt:7: leftover conflict marker
Mon-Fri 7-18
Sat 8-14
Sun 9-13
Closed Dec 25

Back out with git merge --abort

Not ready to decide? git merge --abort puts your branch and files back exactly as they were before the merge started. Nothing is lost: the other branch is untouched, and you can merge again later.

example
learner@shellstreak:~/menu$ git merge --abort && git status
On branch main
nothing to commit, working tree clean

Fast-forward or merge commit

Not every merge creates a merge commit. If your branch hasn't moved since the other one split off, git just slides it forward (a fast-forward). git merge soup -m "Add soup menu" names the merge commit when one is made. git merge --no-ff soup forces a merge commit anyway, so the feature shows up as one unit in the history; git merge --ff-only soup refuses unless a fast-forward is possible.

example
learner@shellstreak:~/menu$ git merge --no-ff --no-edit soup && git log --oneline
Merge made by the 'ort' strategy.
 soup.txt | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 soup.txt
cedc87e (HEAD -> main) Merge branch 'soup'
19fb53b (soup) Add lentil soup
5b27295 Add soup of the day
7460261 Add opening hours
883d03c Start the menu

Check yourself

One real exercise from the “Git branches & merging” unit. No account needed.

Resolve the conflict in menu.txt by keeping both changes: the first line should be Sourdough loaf 7, followed by Rye 5 and Croissant 3, with no markers left. Check with git diff --check, then mark it resolved and finish the merge.

What's checked: the file menu/menu.txt; the repository's merge conflicts, staged changes, commits.

Common mistakes

  • Leaving a marker line (======= is easy to miss) in the file. Run git diff --check (or grep -n '^[<=>]\{7\}' file) before you git add.

  • Editing the file but forgetting git add. Until you add it, git still counts the file as unresolved and refuses to commit.

  • Picking one side without reading the other. Often the right answer combines both changes, like Sourdough loaf 7.

  • Starting a merge with uncommitted edits. Git refuses only if they touch files the merge changes; otherwise it mixes them in with the merge. Commit or git stash them first so a conflict never tangles with unfinished work.

  • Panicking and deleting the folder. git merge --abort gets you back to where you were.

Questions

How do I keep my version or their version of a whole file?+

`git checkout --ours menu.txt` (or `git restore --ours menu.txt`) puts your branch's version in the file, and `--theirs` puts the incoming one. The file still counts as conflicted until you `git add` it, then commit to finish the merge. Both work in the practice shell too.

How do I cancel a merge?+

`git merge --abort` while the merge is still in progress. If you already committed the merge and haven't pushed it, `git reset --hard HEAD~1` removes the merge commit.

Can I avoid merge conflicts?+

Not entirely, but you can make them small: merge or pull `main` into your branch often, keep branches short-lived, and don't reformat whole files in the same change as real edits.

Reading is step one. Now make it stick.

Practise this in a five-minute lesson with instant feedback. No account needed.

Practise it now