Igor Klepacki

Common scenarios for merge conflicts

• Editing the same line: Two branches have made different changes to the same line of a file.
• One branch edits a file while another deletes it: One branch makes changes to a file, while another branch deletes that same file.
• Concurrent file renaming: Two branches rename the same file differently or make changes to a file that one of the branches has renamed.

Structure of zdiff3 and diff3 conflict markers

A zdiff3 and diff3 conflict marker styles divide the conflicting area into three sections:

1. Local Changes (HEAD): Changes that are present in the current branch.
2. Base Changes (Ancestor): The common ancestor's version of this part of the file.
3. Incoming Changes (MERGE_HEAD): Changes that are present in the branch being merged into the current one.

The sections are separated by different markers:

• <<<<<<< HEAD marks the beginning of the local changes.
• ||||||| merged common ancestors marks the beginning of the base changes.
• ======= separates the local changes from the incoming changes.
• >>>>>>> MERGE_HEAD marks the end of the incoming changes.

Understanding the difference between conflict styles

Let's start from the default merge style of conflict markers. It is the most common and widely used style. It is simple and easy to understand. It shows only the local changes and the incoming changes. It is a two-way comparison.

Frankly speaking - it is not enough to resolve the conflict in a complex scenario. It is not enough to understand the context of the changes and the evolution of the code. This is where diff3 and zdiff3 come into play.

Reference example of a diff3 style conflict

Unlike previous style and apart from the common ancestor section, the diff3 does not try to aggresively resolve the conflicts by itself, which is easy spottable on the embedded drawing. The developer gets full set of information it is up to him to decide which changes to keep and which to discard.

Reference example of a zdiff3 style conflict

And here comes the zdiff3 style. As the name says - it is zealous version of a diff3. The behavior can be summed up as an merge + diff3 - there are both aggressive resolving and common ancestor features present.

Personally I find it the most useful, straightforward and productive style of conflict markers with being the most informative but not overwhelming information-wise, since changes that are the same between local and incoming are moved out of conflict markers leaving clean ground for analyzing it.

Explore the differences in practice

If you want to play with the examples from the drawings, create a new directory and use the following commands to create a conflict and see how it looks in different styles:

git init \
  && git branch -m main \
  && echo -e "Foo\nHello" > file.txt \
  && git add file.txt \
  && git commit -m "a" \
  && git branch new-branch \
  && git switch new-branch \
  && echo -e "Bar\nFarwell" > file.txt \
  && git add file.txt \
  && git commit -m "b" \
  && git switch main \
  && echo -e "Bar\nHello" > file.txt \
  && git add file.txt \
  && git commit -m "c" \
  && git merge new-branch

NOTE: Assuming, you've started exploring from zdiff3 you can create another directory and change the merge.conflictstyle to merge and diff3 in the meantime and compare the outcome

Conclusion

The zdiff3 conflict marker is a powerful tool for resolving merge conflicts in Git.

• By providing a three-way comparison (outgoing, common ancestor, incoming), it offers developers additional context, helping them understand the evolution of changes and make informed decisions.

• By being more aggressive in its approach to resolving conflicts, it can save developers time and effort by automatically resolving as many conflicts as possible. The more time you spend on the repetative manual work the more error-prone it gets. zdiff3 is a marvellous way to avoid it and minimize the hassle and frustration.

As collaboration and branch management are integral parts of modern software development, mastering tools like zdiff3 is essential for maintaining a smooth workflow.