Three To Two Merge Use Cases

1. 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 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.

2. 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 their", "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.

3. 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).

4. All Changes

This will have all the possible changes from both versions.

Following configuration is used while generating the result.

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

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

5. 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.

Following configuration is used while generating the result.

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

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

6. Their Changes

This sample is the special case of merge. Lets 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 ThreeWayDitaMerge 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.

Following configuration is used while generating the result.

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

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

7. Running the sample

If you have Ant installed, use the build script provided to run the sample. Simply type the following command to run the pipeline and produce the output file inside the output directory.

ant run

This will generate result files in the output directory.

These results can also be generated seperately for each case by running following commands.

ant all-changes
ant conflicting-changes
ant their-changes

Running from command-line

Following command can be used to run above samples from command-line.

java -jar deltaxml-dita-merge.jar merge3 ancestorName ancestorFile version1Name version1File version2Name version2File resultFile result-type=value

A parameter result-type value should be all-changes, conflicting-changes or their changes.