Merge conflicts in git

Back

If you work with git and you are faced with the task of merging branches, there may be this uneasy feeling just before you execute the merge that it won’t work perfectly. This happens when git does not know what to do when the lines it has to consolidate and merge together conflict each other.

So, if you run the merge command and it tells you that there has been a merge conflict, it means that you need to step in to fix the conflict.

What do you need to know, git-wise?

Right after git says there is a merge conflict, you need to realise that you are technically suspended in the middle of the merge commit. Nothing has been commited yet, and every file that has conflicts will be unstaged.

In the files with the merge conflicts, there will be portions denoted as such:

<<<<<<< HEAD
[content from current master branch that HEAD is pointing to]
=======
[content that git is trying to merge automatically]
>>>>>>> new_branch_to_merge_later

What do you need to do?

All you have to do when you reach this part is to edit it into the end state. This is the only part where subject matter knowledge is required. Make sure you delete the angle brackets and equal signs put in by git.

Once this is completed to satisfaction, save the file, then add the files to the staging area with git add [files]. After which, you need only run the following command:

$ git commit

This should merge cleanly, with the standard git merge commit message template in place.

Level 2

Now that we understand how merge conflicts are solved in theory, we can explore some better ways to handle them. There are many tools that can aid in the conflict resolution of your merges. These may be summoned with the command:

$ git mergetool

More likely than not, this is not set up for you. Not to worry. If you happen to use vim or neovim, you can set things up so that git uses your configuration of vim/neovim as a merge tool to resolve conflicts:

$ git config --global merge.tool nvimdiff

The above command tells git that your preferred merge tool on your system is neovim (substitute nvimdiff for vimdiff if you don’t use neovim). Now, whenever you call git mergetool mid-conflict, a neovim instance begins, with the following layout.

  ╔═══════╦══════╦════════╗
  ║       ║      ║        ║
  ║ LOCAL ║ BASE ║ REMOTE ║
  ║       ║      ║        ║
  ╠═══════╩══════╩════════╣
  ║                       ║
  ║        MERGED         ║
  ║                       ║
  ╚═══════════════════════╝

These 4 views are:

• LOCAL: this is the file from the current branch
• BASE: the common ancestor, how this file looked before both changes
• REMOTE: the file you are merging into your branch
• MERGED: the merge result; this is what gets saved in the merge commit and used in the future

You will notice as you scroll through the file that the cursors in all 4 views move roughly in tandem. This is to give you as much context as is required to solve the conflict. The file at the bottom is the only one you should attempt to edit, as it is the resulting file after editing.

Once done, save using :wqa which is short for :wqall to save and quit from the editor. Then, as previously mentioned, you finish the merge with a commit:

$ git commit

This time, there is an extra step required. To facilitate the merge tool, a few temporary files were created. These files must be deleted to keep a clean working directory:

$ git clean -f

What do I do if I mess up?

I can’t know what sort of errors you run into, git-wise. However, some tips for git troubleshooting may help. To view git history in a sensible way that gives more insight as to the state of git, use this instead of git log or git reflog:

$ git log --oneline --decorate --all --graph

And if you want to jump back to a pre-merge state, simply run the following:

$ git reset --hard [commit HASH]

Where [commit HASH] is the hash of the commit which you wish to jump back to.

General rules to follow pre-merge

Make sure you are on the correct branch when you run the command above. Also make sure that you are on the correct branch when you plan to execute a merge.

Best Regards,
Philip