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 provides details about three to two way mapping.
This is useful in version control systems or configuration management systems when two persons 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
The following are the different three to two merge result scenarios:
ALL_CHANGES : This merge result will have all of the changes made by two people.
CONFLICTING_CHANGES : This result shows only conflicting changes between two people or two branches.
THEIR_CHANGES : This result will show the changes by the 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 the 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. The 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.
The 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.
The following configuration is used while generating the result.
ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.ALL_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);The following diagram shows the expected merge result with 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.
ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.CONFLICTING_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);The following diagrams shows the expected merge result with 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 second version added to the ThreeWayMerge object using addVersion. 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.
ThreeWayMerge m= new ThreeWayMerge();
m.setResultPreset(ThreeWayResultPreset.THEIR_CHANGES);
m.merge(ancestorFile, edit1Version, edit2Version, resultFile);The following diagrams shows the expected merge result with above configuration displaying conflicts and changes involving EDIT2.
Running the sample
To run this sample, all the files you need together with instructions are available on Bitbucket