Three To Two Merge Use Cases

Introduction

Three way merging is used when two files are modified with respect to a common ancestor version. If there are only three versions or inputs involved in a merge, then merge result can be defined as adds and deletes relative to the two branches. This is the main concept for three to two merge.

The three to two merge guide provide details about three to two way mapping.

This is useful in version control systems or configuration management systems when two people are working concurrently on the same set of files. In such scenarios, the three to two merge result will allow them to see the changes made by them. This result can have different possibilities based on the changes represented in it.

Merge cases

Following are the different three to two merge result scenarios:

All Changes : This merge result will have all of the changes made by two persons.
Conflicting Changes : This result shows only conflicting changes between two persons or two branches.
Their Changes : This result will show the changes by other person or the changes on the other branch. Different terminologies such as "mine and theirs", "local and remote" are used in such cases. Here, we are saying that changes by other person are "Their changes".

All these cases are explained in detail with the example in the following sections.

Example

Consider there are two versions EDIT1 and EDIT2 and these versions are updated simultaneously. Following diagram shows the changes on EDIT1 and EDIT2 and then EDIT2 is merge onto EDIT1. The changes shown below are with respect to a common ancestor.

Following colour conventions are used to represent the changes:

Blue : Modification
Green : Addition
Red : Deletion

The numbers given for each change by versions will have correspondence with the numbers shown in the results discussed below.

Note: Results shown below are in addition and deletion form. For example, if both modify something simultaneously, then there will be deletion by EDIT1 and addition by EDIT2 (As we are merging EDIT2 onto EDIT1).

All Changes

This will have all the possible changes from both versions.

Following configuration is used while generating the result.

JAVA

ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.ALL_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);

The following diagram shows the expected merge result with the above configuration displaying all changes.

Conflicting Changes

This result shows only conflicting changes between two versions or two branches. Simple adds, simple deletes and simple modifications are accepted automatically in this result.

The following configuration is used while generating the result.

JAVA

ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.CONFLICTING_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);

The following diagrams shows the expected merge result with the above configuration displaying only conflicts.

Their Changes

This sample is the special case of merge. Let's assume that EDIT1 is the mine and EDIT2 is theirs. The mine/local input should be specified as the second merge input using the merge function, or the first version added to the ThreeWayMerge object using addVersion. The merge result is expected to have their changes which includes:

Conflicts
All changes involving EDIT2

Here, EDIT1 is mine or local branch because we are merging EDIT2 onto EDIT1. The adds and deletes performed on EDIT1 branch will be considered correct. So, EDIT1's adds and deletes will be accepted automatically.

The following configuration is used while generating the result.

JAVA

ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.THEIR_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);

the following diagrams shows the expected merge result with the above configuration displaying conflicts and changes involving EDIT2.

Running the sample

See this Bitbucket repository for the sample files and how to run them.