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:
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:
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
git statusThe 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:
cat menu.txtThe file looks like this, with Soup and Salad unchanged and the disputed line in the middle:
Soup
<<<<<<< HEAD
Fresh pasta
||||||| 8b1c2d4
Pasta
=======
Lentil pasta
>>>>>>> vegan-menu
SaladRead it in three parts:
- Between
<<<<<<< HEADand|||||||is your side, the branch you are on. Here that isFresh pastafrommain. - Between
|||||||and=======is the original line both branches started from,Pasta. This section appears because ofzdiff3, 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-menuis 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:
printf 'Soup\nFresh lentil pasta\nSalad\n' > menu.txtBefore 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:
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:
git add menu.txt
git status
git commit --no-editgit 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
git status
git log --oneline --graph --decorate -4
cat menu.txtThe tree is clean, the graph shows the merge commit with two parents, and the file holds your resolved text. Delete the finished branch:
git branch -d vegan-menuStep 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:
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:
git merge --abort
git statusGit 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 filesappears when you try to commit or merge again before you resolve. Finish the first merge withgit addandgit commit, or cancel it withgit merge --abort.fatal: There is no merge to abort (MERGE_HEAD missing)means no merge is in progress. Rungit statusto 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 addedordeleted 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 addorgit rmthe 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:
git merge split-bills || echo "merge stopped: conflict"Keep the incoming version of bills.txt, then stage and commit:
git restore --theirs bills.txt
cat bills.txt
git add bills.txt
git commit --no-editThe 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
git log --oneline --merges -2
git branch -d split-billsThe 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
maininto your branch regularly withgit merge mainwhile 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:
rm -rf ~/git-demoNext steps
- Recover when a merge or another command went wrong: undo mistakes in Git.
- Share your branches and review them: push to GitHub over SSH and open a pull request.
- Review the basics of branches: create, switch and merge branches in Git.
Related tutorials
- How to Install and Configure GitYou will install Git 2.53 from Ubuntu 26.04's own packages, set your name and email, make main the default branch, choose an editor and a few safe defaults, use a different email for work projects, and create an SSH key to use with GitHub.
- How to Make Your First Git Commits and Read the HistoryYou will turn a folder into a Git repository, make commits in small steps, check what changed before you commit, ignore files that do not belong in history, rename and delete files, and read the history back in several ways.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials