Enji's Blog
Merge Modes in Eclipse Git
Differences between EGit merge modes explained.
When resolving Git conflicts in the Eclipse IDE, the EGit plugin offers three different modes for its merge tool:
Let’s examine the differences between these three modes with a simple example. We start with the following text file:
...
This line will be edited by master
...
This line will be edited by feature.
...
This line will be edited by both.
...
This file will be edited in the master and feature branch as indicated by its original lines. In the master branch, the following edits are performed:
And here are the edits from the feature branch:
As you can see, whereas lines 2 and 4 have been edited in just one of the branches, line 6 was changed in both of them, leading to a conflict when performing a merge:
A Linux shell script that automates this process is given at the end of this post. As expected, the text file contains the usual Git conflict markers after the merge:
Note that the non-conflicting edits (lines 2 and 4) have already been merged in this file.
Now let’s inspect what the three different merge modes will show us for this simple scenario. The merge tool can either be started by double-clicking the conflicting file in the “Git Staging” view
or by selecting “Merge Tool” from the file’s context menu in the Project Explorer:
An important aspect to understanding the three merge modes is that their descriptions refer to what will be displayed in the left half of the resulting compare editor. The right half of the compare editor always shows the file’s contents from the feature branch.
“Use the working tree version of conflicting files (pre-merged by Git)”
This option displays
- in the left half: the file as it is in the working tree (i.e., in your file system, with Git conflict markers)
- in the right half: the file’s contents from the feature branch (as always)
The description “pre-merged by Git” refers to both the Git conflict markers, and the fact that the changes in the non-conflicting lines have already been merged in the working tree version.
Note that you can toggle the display of the common ancestor (the original file version before the changes in master and feature) by clicking on the “Show Ancestor Pane” button in any of the three merge modes:
The highlight colors for the lines have the following meaning:
- Blue: This is where your cursor is.
- Grey: Changes only in the master branch.
- Red: Changes in both branches (conflict).
- None: No changes, or changes only in the feature branch (which have already been merged in this mode).
“Use HEAD (the last local version) of conflicting files”
This option displays
- in the left half: the file’s contents from the master branch (i.e., the local version before the merge operation)
- in the right half: the file’s contents from the feature branch (as always)
In addition to the previously mentioned colors, this mode adds another one:
- Violet: Changes only in the feature branch (which have not been merged in this mode).
“Use the git pre-merged ‘ours’ version of conflicting files”
This option displays
- in the left half: the merged non-conflicting lines, and the lines from the master branch (“ours”) for conflicting edits
- in the right half: the file’s contents from the feature branch (as always)
Changing the merge mode
If you select the check box “Don’t ask again”, Eclipse will (as you might have guessed) stop asking you for the merge mode, and always use the option that you have chosen last. In case that you change your mind later on, you can adjust this setting in the “Diff/Merge” preferences:
Opinion
Choosing between these three merge modes is largely a matter of personal taste. For my part, I prefer using the “pre-merged ‘ours’ version” because it automatically takes care of merging the non-conflicting lines, and lets you focus on the conflicts without having to manually remove conflict markers. Also, I usually toggle the ancestor pane so that I can see what the original version (before the conflicting edits) looked like.
Example preparation script
echo -e "...
This line will be edited by master
...
This line will be edited by feature.
...
This line will be edited by both.
..." > text.txt
git init
git add text.txt
git commit -m "initial version"
git switch -c feature
sed -i 's/will be edited by feature/has been edited by feature/' text.txt
sed -i 's/will be edited by both/has been edited by feature as well/' text.txt
git commit -am "feature changes"
git switch master
sed -i 's/will be edited by master/has been edited by master/' text.txt
sed -i 's/will be edited by both/has been edited by master as well/' text.txt
git commit -am "master changes"
git merge feature