Skip to main content

Dev tools and workflow · Intermediate · 14 min

How to Resolve a Git Merge Conflict

By Padding · Updated 15 Nov 2026
Ubuntu 26.04.1 LTS · Git 2.53 (Ubuntu package)

You will cause a merge conflict on purpose, read the conflict markers, resolve it by editing the file, finish the merge, back out of a merge you do not want, and pick one side of a conflict with a single command.

On this page

Git merges two branches by combining the changes each made since they split. When the changes are in different places, it does the work for you. When both branches changed the same lines, Git cannot know which version you want. It stops, marks the disagreement in the file, and asks you to decide. That is a merge conflict, and it is a normal part of working with other people, or with yourself on two branches.

This tutorial makes a conflict in the notes repository from the last two tutorials, so you can see what Git shows you and what each way out does. The settings from the first tutorial matter here: merge.conflictStyle zdiff3 is what puts the original text into the markers.

Step 1 · Prepare two branches that disagree

Go to the repository and add a menu file on main. Then create a branch from that point, and change the same line on both sides:

Bash
cd ~/git-demo/notes
git status --short
printf 'Soup\nPasta\nSalad\n' > menu.txt
git add menu.txt
git commit -m "Add a menu"
git switch -c vegan-menu
printf 'Soup\nLentil pasta\nSalad\n' > menu.txt
git commit -am "Make the pasta vegan"
git switch main
printf 'Soup\nFresh pasta\nSalad\n' > menu.txt
git commit -am "Use fresh pasta"

The first command prints nothing when the working tree is clean. If it lists files, commit or stash them first. Both branches now changed line two of menu.txt, each in its own way, starting from the same original.

Step 2 · Merge and meet the conflict

Merge the branch into main. This is the merge that cannot finish:

Bash
git merge vegan-menu || echo "merge stopped: conflict"

Git prints CONFLICT (content): Merge conflict in menu.txt and Automatic merge failed; fix conflicts and then commit the result. The merge is now paused halfway. Nothing is lost, and nothing is committed.

Check it worked

Bash
git status

The status says You have unmerged paths and lists menu.txt under Unmerged paths: as both modified. Files that merged cleanly would be listed as staged changes. In a bigger merge, only the files named as unmerged need your attention.

Step 3 · Read the conflict markers

Git has written both versions into the file, between markers:

Bash
cat menu.txt

The file looks like this, with Soup and Salad unchanged and the disputed line in the middle:

Text
Soup
<<<<<<< HEAD
Fresh pasta
||||||| 8b1c2d4
Pasta
=======
Lentil pasta
>>>>>>> vegan-menu
Salad

Read it in three parts:

  • Between <<<<<<< HEAD and ||||||| is your side, the branch you are on. Here that is Fresh pasta from main.
  • Between ||||||| and ======= is the original line both branches started from, Pasta. This section appears because of zdiff3, and the number after the markers is the short hash of the common ancestor commit. Without the setting you would see only the two sides, and you would have to remember what the line used to say.
  • Between ======= and >>>>>>> vegan-menu is the other side, from the branch you are merging.

Your hash will differ. The original line is often what tells you what each side meant to change, which is why it is worth having.

Step 4 · Resolve the conflict

Resolving means producing the final text of the file, with every marker removed. You can open menu.txt in your editor, delete the three marker lines and the version you do not want, and keep what you do. Or you can combine the two. Say you want both ideas: fresh pasta, made vegan. Replace the whole file with the result you want:

Bash
printf 'Soup\nFresh lentil pasta\nSalad\n' > menu.txt

Before you tell Git you are done, check that no marker is left. A marker left in a file is a classic way to break a build:

Bash
grep -n -E '^(<<<<<<<|\|\|\|\|\|\|\||=======|>>>>>>>)' menu.txt || echo "no markers left"

When no markers remain, stage the file. Staging is how you tell Git that this file is resolved. Then commit to finish the merge:

Bash
git add menu.txt
git status
git commit --no-edit

git status before the commit says All conflicts fixed but you are still merging. git commit --no-edit uses the message Git prepared, Merge branch 'vegan-menu'. Leave out --no-edit to be given your editor with that message, if you want to add a note about how you resolved it.

Check it worked

Bash
git status
git log --oneline --graph --decorate -4
cat menu.txt

The tree is clean, the graph shows the merge commit with two parents, and the file holds your resolved text. Delete the finished branch:

Bash
git branch -d vegan-menu

Step 5 · Back out of a merge

If you start a merge and decide you do not want to resolve it yet, you can return to the state before it. This works as long as you have not committed the merge. First set up another conflict, a different one this time, on a new file:

Bash
printf 'Rent\nPower\n' > bills.txt
git add bills.txt
git commit -m "Add bills"
git switch -c split-bills
printf 'Rent (shared)\nPower\n' > bills.txt
git commit -am "Share the rent"
git switch main
printf 'Rent (paid)\nPower\n' > bills.txt
git commit -am "Mark the rent as paid"
git merge split-bills || echo "merge stopped: conflict"

You are in a conflict again. To cancel the merge, run:

Bash
git merge --abort
git status

Git puts everything back as it was before git merge: your branch, the index and the files. The status is clean, and bills.txt says Rent (paid). --abort only works while the merge is unfinished. If you have edited files by hand in the middle of the merge, those edits are thrown away with it.

Troubleshooting

  • error: Merging is not possible because you have unmerged files appears when you try to commit or merge again before you resolve. Finish the first merge with git add and git commit, or cancel it with git merge --abort.
  • fatal: There is no merge to abort (MERGE_HEAD missing) means no merge is in progress. Run git status to see where you are.
  • Markers end up in a committed file. Search for them with git grep -n '^<<<<<<<' and fix them in a new commit.
  • Git says both added or deleted by us. These are conflicts that are not about the text inside a file: both sides added the same filename, or one side deleted a file the other edited. The fix is the same. Decide what the file should be, make the folder match, git add or git rm the path, and commit.

Step 6 · Take one side of a conflict outright

Sometimes you already know that one side is right. After a merge conflict you can take a file as it is on one branch with git restore. --ours is the branch you are on, and --theirs is the branch you are merging in. Run the merge again:

Bash
git merge split-bills || echo "merge stopped: conflict"

Keep the incoming version of bills.txt, then stage and commit:

Bash
git restore --theirs bills.txt
cat bills.txt
git add bills.txt
git commit --no-edit

The file now says Rent (shared). git restore --ours bills.txt keeps yours instead. These commands take a whole file, so use them only when you are sure that nothing in the other side's version of the file is worth keeping.

To decide with the full text of both sides next to each other, git mergetool opens a configured merge program. It is optional, and the terminal and a text editor are enough for most conflicts.

Check it worked

Bash
git log --oneline --merges -2
git branch -d split-bills

The log lists the two newest merge commits, the ones for vegan-menu and split-bills. If you followed the branches tutorial, older merge commits sit below them, and -2 hides those. The second command deletes the finished branch.

Step 7 · Avoid conflicts where you can

Conflicts become more likely the longer two branches live apart. A few habits keep them small:

  • Keep branches short, and merge or delete them within a day or two.
  • Bring the latest main into your branch regularly with git merge main while you work on it, so that you resolve small conflicts early.
  • Do not reformat whole files in the same commit as a change. The reformatting touches lines the other side also changed.
  • Tell the people you work with when you are about to change a shared file.

Step 8 · Clean up

Keep the repository for the next tutorial. If you are finished with the series, remove it:

Bash
rm -rf ~/git-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.