git Merges Demystified

Last time in our git series, we looked into branching and merging - setting the ground work for how to merge code when your working by yourself. While that is all well and good, the real power is in collaborating with a team. In this post, we discuss the dreaded merge conflict, what they are, and how to resolve them.

Setting the stage

To explain a merge conflict, it is easier to tell the story of two developers - in out case Dev A and Dev B. They are both awesome developers and always branch from the right branch, check in their code, and write great commit messages. They have both been assigned to different features on our project.


First they pull the latest code from their git repository and they both independently create branches to work on.

All the same


Developer A finishes all her coding and commits on her branch.

Dev A commits


Developer B finishes all his coding and commits on his branch. Note at this point we don’t care about time and the commit dot is just for representation purposes.

Dev B commits


Developer A is ready to merge the feature that she worked on and simply merges the code. The base branch didn’t have any changes so there were not any issues.

Dev A merges


Developer B has also completed his coding and goes to merge his code into the base branch, but is greeted with a message similar to your branch is behind and cannot merge his code. This is because Developer A’s changes updated the base branch and might have changed some of the same code as Developer B’s. Either way Developer B’s base branch needed updating.

Dev B tries to merge


So Developer B, knowing his way around git, switches back to his branch and then pulls Developer A’s changes on the base branch into his branch. Then using his choice of merge tool whether it be a text editor or something fancy like meld, he merges the changes and then commits the code.

Dev B pulls the changes


Now that all of the branches match, Developer B can now merge their code to the base branch without any problems.

Dev a merges code

Things to ponder

What we just went through is the typical issue when merging code that shares files or parts. There are many way to eliminate or reduce this from happening to you and your team. They are:

  1. Have smaller concise files - this not only helps with git, but also makes general development a lot easier.

  2. Only commit what you know you changed. Many IDE’s - I’m looking at you Visual Studio, will create a bunch of this and that type of files when you use them. When your working alone it’s fine to be lazy and commit all the changes, but when working on a team you really need to have structured commits. My rule of thumb is if I didn’t write it, then don’t add it to your commit. This is one of the biggest causes of merge conflicts that I have seen.

  3. Pull often from the base branch. The longer you go without updating your branch from the base the harder it will be to merge into it. This also drives quicker feature branches which can be merged back into the base quickly. It’s just less maintenance and work all around.

What’s next?

Now you should be able to handle merging like a pro. Like anything, practice will only increase your understanding. You might even want to try causing a merge conflict on a simple project, just so you can see it before you really need to deal with it. From here on out, the git series is going to focus on the lesser used commands in git, which will make working with git even easier. We’ll also start looking at different patterns to use with git such as pull requests and git flow.

If you missed one of the articles, select it from the below series link.

Links to the other posts in the Learning git series

  1. Intro to git - Part 1
  2. The git cycle
  3. Setting up git
  4. Initializing git
  5. What's a remote in git
  6. git branches simply explained
  7. git Merges Demystified
  8. How to use git flow
  9. git stash and pop

Always follow the manufacturers instructions, this write up is simply the way that I do it, and it may or may not be the right way. Use your common sense when applying products to or altering your stuff and always wear the appropriate safety gear.