Merge conflicts are often a part of life for working on complex development projects. In this guide we'll look at how you can deal with them, and when they will occur.

When do merge conflicts occur?

A merge conflict in Git will occur if you have made changes to the same file on a the branch you are on, and the one you are trying to merge into. In this case, Git won't know which one should be used - so it will throw a merge conflict error.

Consider the scenario where a change has been made to file.md in the main branch and my-branch. When we checkout main and try to merge my-branch into main, we will run into the following error:

git merge my-branch

Auto-merging file.md
CONFLICT (content): Merge conflict in file.md
Automatic merge failed; fix conflicts and then commit the result.

Git doesn't know what to do here, so it's our job to try and resolve it.

Stabilizing the current branch

Sometimes, when we try to merge a file, the merge will fail completely:

error: Your local changes to the following files would be overwritten by merge:
        file.md
Please commit your changes or stash them before you merge.

This happens because we have uncommitted changes on our current branch. We need to close all changes on our current branch before we can merge. To do that, you can run git stash (I covered git stash in more detail here), or you can simply commit your changes on this branch to stabilize it:

git add -A
git commit -m "My commit message"

Now that our branch is stabilised, we can try to run git merge my-branch (where my-branch is your branch) to merge our branch back into main. If we run into merge conflicts now, we need to resolve them.

How to resolve merge conflicts in git via GUI

If you're using a modern code editor like Visual Studio Code, then merge conflicts will appear in the GUI where you can accept incoming changes or accept the current changes on your branch. This provides a pretty easy way to fix your conflicts. In Visual Studio Code, this is represented in conflicting files via the GUI shown below. You have a number of options:

• "Accept Current Changes" - this will use your current branch's content.
• "Accept Incoming Changes" - this will use the content from the branch you are merging in.
• "Accept Both Changes" - this will keep both, one under the other.
• "Compare Changes" - this will bring up an additional screen to compare changes side by side.

Once you review all conflicts, you can then add your files and commit them as normal:

git add -A
git commit -m "My commit message"

How to resolve merge conflicts in git via Terminal

In some cases, you may not have a GUI to resolve merge conflicts. There are a number of commands you can use.

First, git status will tell you the files affected:

git status
On branch my-branch
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:   file.md

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

As we can see, only file.md is affected. Next, we can use git diff to see the difference between this branch and the one we are merging into:

++<<<<<<< HEAD
 +Some  a
 +Some b
 +Some conflict c 
 +Some conflict d
 +Some e
++=======
+ Some conflict 1
+ Some b
+ Some conflict c
+ Some conflict 2
 -Some f
++Some f
++>>>>>>> main

Here, everything after ++<<<<<<< and before ++======= represents the current branch changes, while anything after ++======= and before ++>>>>>>> main represents the branch you are merging in.

We can also see the conflicting commits by running git log --merge

Aborting your merge during a merge conflict

Sometimes you realise you're in a bit too deep on this merge conflict - in which case you can undo it by running git merge --abort.

git merge --abort

This will bring us back to a non-merge state so we can resolve merge conflicts manually in both branches, before trying to merge again.

Resolving by accepting incoming or current changes

Another easy way to resolve merge conflicts on certain files is to use the --theirs and --ours option on git checkout. Our merge conflict was on file.md. If I want to accept all incoming changes for file.md from the branch I am trying to merge, I could write:

git checkout --theirs file.md

This checks out the file.md from "their" version of code. If I wanted to use the version in my current branch, I'd use --ours. Both --ours and --theirs expects a file as an argument - so this has to be done on a file by file basis.

Easy, right? That's fine for merging in entire files, but what if we have multiple merge conflicts within a file?

Resolving by editing the file itself

Remember, when you create a git merge conflict, we ended up with content that looked like this when we ran git diff?

++<<<<<<< HEAD
 +Some  a
 +Some b
 +Some conflict c 
 +Some conflict d
 +Some e
++=======
+ Some conflict 1
+ Some b
+ Some conflict c
+ Some conflict 2
 -Some f
++Some f
++>>>>>>> main

That content also exists in your file where the conflict happens (without the + and -, of course). The easiest way to resolve a merge conflict when you want to do it without any help from a GUI is to go to the file in question, and simply remove the section you don't want to accept. That just means deleting the text between <<<<<<< HEAD and ======= if you want to accept current, or the text between ======= and >>>>>>> if you want to accept incoming.

Adding and commiting your changes

Once you've resolved your merge conflicts, don't forget to add and commit your changes on the current branch, so they remain saved:

git add -A
git commit -m "Merge message"

Conclusion

We have powerful tools in our code editors to resolve merge conflicts. Having said that, sometimes limitations in environments mean we have to resolve our own git merge errors - or we may just prefer doing this work from terminal. Some specific edge cases may also mean we have to do this work from terminal.

In any case, merge conflicts are a part of development with git, and they can be resolved simply by removing the content we don't want anymore from the files where the conflicts exist. We can also use git checkout --theirs or git checkout --ours to resolve issues more quickly.