6.8 Resolving Conflicts

When merging branches (or otherwise combining or changing history) conflicts can occur. If you edited two completely different parts of the same file in two branches and then merge one of these branches into the other, then Git can resolve that on its own, but if you edit the same area of a file, then a human is required to decide how the two versions, or "sides of the conflict", are to be combined into one.

Here we can only provide a brief introduction to the subject and point you toward some tools that can help. If you are new to this, then please also consult Git’s own documentation as well as other resources.

If a file has conflicts and Git cannot resolve them by itself, then it puts both versions into the affected file along with special markers whose purpose is to denote the boundaries of the unresolved part of the file and between the different versions. These boundary lines begin with the strings consisting of six times the same character, one of <, |, = and > and are followed by information about the source of the respective versions, e.g.:

<<<<<<< HEAD
Take the blue pill.
=======
Take the red pill.
>>>>>>> feature

In this case you have chosen to take the red pill on one branch and on another you picked the blue pill. Now that you are merging these two diverging branches, Git cannot possibly know which pill you want to take.

To resolve that conflict you have to create a version of the affected area of the file by keeping only one of the sides, possibly by editing it in order to bring in the changes from the other side, remove the other versions as well as the markers, and then stage the result. A possible resolution might be:

Take both pills.

Often it is useful to see not only the two sides of the conflict but also the "original" version from before the same area of the file was modified twice on different branches. Instruct Git to insert that version as well by running this command once:

git config --global merge.conflictStyle diff3

The above conflict might then have looked like this:

<<<<<<< HEAD
Take the blue pill.
||||||| merged common ancestors
Take either the blue or the red pill, but not both.
=======
Take the red pill.
>>>>>>> feature

If that were the case, then the above conflict resolution would not have been correct, which demonstrates why seeing the original version alongside the conflicting versions can be useful.

You can perform the conflict resolution completely by hand, but Emacs also provides some packages that help in the process: Smerge, Ediff ((ediff)Top), and Emerge ((emacs)Emerge). Magit does not provide its own tools for conflict resolution, but it does make using Smerge and Ediff more convenient. (Ediff supersedes Emerge, so you probably don’t want to use the latter anyway.)

In the Magit status buffer, files with unresolved conflicts are listed in the "Unstaged changes" and/or "Staged changes" sections. They are prefixed with the word "unmerged", which in this context essentially is a synonym for "unresolved".

Pressing RET while point is on such a file section shows a buffer visiting that file, turns on smerge-mode in that buffer, and places point inside the first area with conflicts. You should then resolve that conflict using regular edit commands and/or Smerge commands.

Unfortunately Smerge does not have a manual, but you can get a list of commands and binding C-c ^ C-h and press RET while point is on a command name to read its documentation.

Normally you would edit one version and then tell Smerge to keep only that version. Use C-c ^ m (smerge-keep-mine) to keep the HEAD version or C-c ^ o (smerge-keep-other) to keep the version that follows "|||||||". Then use C-c ^ n to move to the next conflicting area in the same file. Once you are done resolving conflicts, return to the Magit status buffer. The file should now be shown as "modified", no longer as "unmerged", because Smerge automatically stages the file when you save the buffer after resolving the last conflict.

Magit now wraps the mentioned Smerge commands, allowing you to use these key bindings without having to go to the file-visiting buffer. Additionally k (magit-discard) on a hunk with unresolved conflicts asks which side to keep or, if point is on a side, then it keeps it without prompting. Similarly k on a unresolved file ask which side to keep.

Alternatively you could use Ediff, which uses separate buffers for the different versions of the file. To resolve conflicts in a file using Ediff press e while point is on such a file in the status buffer.

Ediff can be used for other purposes as well. For more information on how to enter Ediff from Magit, see Ediffing. Explaining how to use Ediff is beyond the scope of this manual, instead see (ediff)Top.

If you are unsure whether you should Smerge or Ediff, then use the former. It is much easier to understand and use, and except for truly complex conflicts, the latter is usually overkill.