+1 for telling me about diff3 alone—how often I was looking on an incomprehensible conflict, cursing whoever is responsible for not telling me what the common ancestor had to say. Thank you very much.

Well said, John of StackOverflow. The diff3 conflict resolution strategy is a hidden gem in git that has saved me uncountable conflict-resolution headaches and has turned git conflict resolution into something of a joy for me. Weird, I know!

This post is an adaptation from a StackOverflow answer that I wrote in 2012 that deserves to live on its own.

Example

Let’s take a look at this conflict. How would you resolve it?

<<<<<<< HEAD GreenMessage.send(include_signature: true) ======= BlueMessage.send(include_signature: false) >>>>>>> merged-branch

Looking at the conflict alone, it’s impossible to tell what each branch changed or what its intent was. This lack of information is the biggest cause that I see that makes conflict resolutions frustrating and incorrect.

diff3 to the rescue!

Turn this thing on!

git config --global merge.conflictstyle diff3

After running this command to turn on diff3, each new conflict will have a 3rd section, the merged common ancestor.

How do I read this?

<<<<<<< HEAD GreenMessage.send(include_signature: true) ||||||| merged common ancestor BlueMessage.send(include_signature: true) ======= BlueMessage.send(include_signature: false) >>>>>>> merged-branch

The merged common ancestor section shows what the conflicting line(s) were before either of the merged branches changed them. This is our baseline frame of reference. You’ll find the merged common ancestor code for this example on the center line between ||||||| merged common ancestor and =======

The code between <<<<<<< HEAD and ||||||| merged common ancestor shows what the code looks like at HEAD, the current commit (for rebase, this will be the rebase target).

The code between ======= and >>>>>>> merged-branch shows what the code looks like at merged-branch —the branch or commit being merged.

Note that any of the section markers may have 0 lines between them, indicating an empty section. I’ll cover this more in the examples below.

The Conflict Resolution Pattern

With diff3 or without, the pattern of merging code changes remains the same:

Compare the merged common ancestor with each of the conflicting changes. Choose one change as your starting point (usually the more complex change) and one change to apply (usually the simpler change). Apply the simpler change to the other change (merge the changes).

Let’s try this with our example.

First, compare each change (HEAD, and then merged-branch) with the merged common ancestor, trying to determine each change’s intent. HEAD changes BlueMessage to GreenMessage . Its intent is to change the class used to GreenMessage, passing the same parameters. merged-branch changes include_signature from true to false , intending to stop inclduing a signature in messages.

In this case, both changes are simple, so I’ll arbitrarily start with the code in HEAD, and apply the other change: include_signature changes from true to false .

After removing conflict section markers and everything else other than the merged code, we have this:

GreenMessage.send(include_signature: false)

Repeat for each conflicting hunk, and we’re done! Add the resulting merged files and continue with the merge/rebase/cherry-pick.

More examples, with explanations

Lines added to the same location; order ambiguous

<<<<<<< HEAD @import 'some_file'; ||||||| merged common ancestor ======= @import 'other_file'; >>>>>>> merged-branch

When the merged common ancestor is a blank section, such as this, each branch added lines at the same position. In this case, we typically want to keep both lines that were added, ordered in whichever order makes the most sense.

Example resolution:

@import 'some_file'; @import 'other_file';

Changes with the same intent

<<<<<<< HEAD # Broken; see #35 ||||||| merged common ancestor ======= # this doesn't work >>>>>>> merged-branch

Here again, each branch added lines at the same position. However in this case, both changes share a common intent: document breakage in the surrounding code. This type of conflict can also happen when multiple people fix the same bug in different ways. With the same intent, keeping both additions would be redundant here and harmful in other scenarios. Instead, we’ll pick the implementation that best accomplishes the intent, or combine the best of both.

Example resolution:

# Broken; see #35

Moved or deleted lines

<<<<<<< HEAD ||||||| merged common ancestor BlueMessage.send(include_signature: true) ======= BlueMessage.send(include_signature: false) >>>>>>> merged-branch

When one of the branch’s sections is empty, this indicates that the lines were deleted or moved in that branch. In this case, either a message is no longer being sent, or the call to BlueMessage.send has moved elsewhere. You must determine which. If the call was deleted, then merged-branch ’s change may have become irrelevant. If the change in HEAD moved the call elsewhere or changed how it was done, then we must find it and apply the include_signature change if it’s still relevant.

The resolution here is likely to delete this conflict block, and search for where we may need to apply the include_signature change elsewhere.