How git-mediate made me stop fearing merge conflicts and start treating them like an easy game of Minesweeper!

Yair Chuchem
Dec 28, 2016 · 3 min read

If you’ve ever had to deal with git merge conflicts, then there’s a good chance that these messages give you the chills:

Auto-merging <SOURCE-FILE-PATH>
CONFLICT (content): Merge conflict in <SOURCE-FILE-PATH>
Automatic merge failed; fix conflicts and then commit the result.

They arise when performing merges, reverts, and cherry-picks, and they scare people away and make them reconsider their actions.

Image for post
Image for post

Solving these conflicts was hard, time consuming and very error-prone, using either fancy 3-way GUI merge tools or doing it manually (did I mention error prone?).

Then I learned about git-mediate, a small open-source tool by Eyal Lotem, which helps resolve merge conflicts rather easily, and most important, correctly!

Image for post
Image for post

How does it work?

First, configure git to use its “diff3” merge conflict style:

git config --global merge.conflictstyle diff3

Now when conflicts appear, they look like this in the affected files:

Image for post
Image for post

When a conflict occurs, look at it and try to figure out what changed between the base and either the upper or lower branch — choose whichever looks like a simpler change. Now apply this change on the two other parts that don’t yet have it: both the base and the other branch. After your edits, the conflict should look like this:

Image for post
Image for post

Now we run git-mediate which rewrites the file with one where the conflict is resolved and git adds it if no conflicts remain.

How does it work? It notices that for this conflict one of the branches matches the base, and replaces the conflict with the other branch, which now contains both changes.

Image for post
Image for post

If git-mediate finds that, after our changes, neither branch is identical to the base, it means that we missed parts of the change. That often happens and it’s ok. We just have to see what we missed, which is easier now that the branch is more similar to the new base, and apply that on the other two parts. We can then run git-mediate again and have our conflicts resolved.

Had we tried to resolve the conflict manually (without git-mediate) we could have easily missed whether we didn’t apply the full change, and in doing so accidentally revert changes in our conflict resolution.. By using git-mediate to verify our work and resolve the conflict for us, we avoid such mistakes.

Using git-mediate is a bit like magic, you do a small little change, press the button, and your conflict is resolved!

A few extra tips:

  • Regardless of your merging solution, large merges can often be split into several smaller ones, for example by rebasing feature-branches instead of doing one big merge.
  • When figuring out the changes in a conflict isn’t simple, git-mediate -d shows, in diff form, the two different changes from the base.

Happy merging!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store