Advanced merging - manual alignment with KDIFF3

Phil Gilmore

Not all merge programs are equal.  Where possible, it's nice to have the merge program automatically resolve any conflicts that it can before forcing you to make any manual merge selections.  Of the tools that I've used, KDIFF3 always does the best automatic merge.  When auto merge fails, it's usually still very easy to select the desired merge source when resolving a conflict. 

On rare occasions, KDiff3 will match common lines in the first place where you wanted to match in the second place.  If it matches in a place other than where you want it to, you will need to do a manual alignment.  This is easy to do in 2-way diff operations, but can raise some questions when doing a 3-way merge.  Here I show you how to do it in an example of why you would want to do it.

Sample Sources

Here are the sample sources I will use to demonstrate manual alignment.

Load them up into KDIFF3.

Initial alignments

You now see the initial alignments that KDIFF3 comes up with.

The first line that is common across all 3 sources is the line containing the number "1".  But what if we want it to match up lines starting with the letter "A" instead?  We have to tell it where to line up the 3 sources.  Do this with a manual alignment.  You can access it from the menu, but it's easier to do this with the hot key combination, CTRL-Y.  If you screw it up, just press CTRL-SHIFT-Y to reset your manual alignments and start over.  If you insist on using the menu, you can see the options for manual alignment in the screen shot below.

Manual alignments are done on 2 sources at a time.  This makes it confusing for a 3-way merge.  You actually achieve a 3-way alignment as a series of two 2-way alignments. 

Sequence for a 2-way manual alignment:

First manual alignment

• Warning:  If you wish to save the merge result when finished, you should start a merge before adding manual alignments.  Starting a merge will reset any manual alignments.  I do not show a merge in these screen shots for the sake of keeping the images as small as I can

Here is the first manual alignment.  Starting from KDiff's Initial alignment (right after loading the sources), click on the first line, annotated with a "1" in bright red.  Press CTRL-Y then click the second source on the line annotated with a "2" in bright red.  Press CTRL-Y to complete the alignment.

After the completion of the operation, you see the alignment between the first and second sources.  The "A" on the first two sources are aligned on the same line.  The third source has been realigned with the other sources where possible.  The first line is the "1" line.  It cannot align with the "1" line in sources 1 and 2 because it would violate the manual alignment to line up all 3.  The same applies to the "2" and "3" lines.  The first line that can be aligned across all 3 sources is the "4" line.  Lines "5" and "6" follow suit and you are left with what you see here.

Second manual alignment

Below are the alignment points for the second alignment.  Hopefully, at this point you understand the process well enough that you didn't need this screen shot to tell you what's next.

The second alignment brings all the "A" lines together.  Below is the final result. 

Remember that if you are doing a merge and you did not start the merge before the alignments, starting a merge at this point will reset your manual alignments. 

Happy merging.

Phil Gilmore (www.interactiveasp.net)