Three-Way File Comparisons

The Professional Edition of Merge enables you to compare and merge three files side-by-side. Note that merging capability is available only for text comparisons and folder comparisons.

  • Three-way file merging is frequently used to merge two derived files into a common-ancestor or base version.
  • The need to do this typically arises when more than one person is working simultaneously on a set of source files stored in a version control or configuration management system.
  • Merge integrates with a number of such configuration management systems. Find out more.
  • Three-way file comparisons can be launched directly from a three-way folder comparison, allowing efficient integration of entire branches of source code.
  • Merge Professional also supports Automatic File Merging, to speed up three-way merges.

A three-way file comparison

To switch between two-way and three-way comparisons select Two-Way Vertical or Three-Way Vertical from the Layout toolbar button. You can also select WindowTwo-way Vertical and WindowThree-way Vertical, or press Ctrl+Cmd+2 and Ctrl+Cmd+3.

Ordering of files within the comparison display

Merge is designed to be most effective when the common ancestor file is used as the centre file of the three files being compared, with the two modified versions on either side. The differences between each of the revisions and the ancestor are clearly displayed in this arrangement. If one of the two derived files has been created by someone other than you, it is suggested that it is placed in the left pane.

Using three-way file comparisons

All of the comparison, editing and merging features of two-way file comparisons apply to three-way comparisons.

Working with the common ancestor file in the middle file panel, you can merge changes from the two derived revisions into it to produce a final, merged file. When doing this, it is usually prudent to verify that each and every change is wanted and compatible with the others you have already accepted.

Whereas the scrollbar Previous change in pane and Next change in pane buttons (and equivalent keyboard shortcuts) navigate within a specific file pane, the toolbar Previous Change in Comparison and Next Change in Comparison buttons operate across the whole comparison. (The corresponding keyboard shortcuts are Ctrl+Option+ and Ctrl+Option+.)

For two-way comparisons, the difference between navigating through changes within a specific file and across the whole comparison is of no practical import. However, the difference is significant for three-way comparisons.

Suppose, for example, that the scrollbar Previous change in pane and Next change in pane buttons in the left file pane are used (or the equivalent keyboard shortcuts with the left file having input focus). These would navigate through all the changes between the left and middle files. However, they would not jump to any changes that existed only between the middle and right files. Only by stepping through the changes of the middle file could you be certain not to miss any differences in the entire comparison.

By way of contrast, the toolbar Previous Change in Comparison and Next Change in Comparison buttons (and equivalent keyboard shortcuts) automatically switch focus to the middle file of a three-way comparison, before jumping to the previous or next change. They thus step through every single change in the entire comparison, whether between the left/middle files or between the middle/right files.

Information The toolbar Previous Change in Comparison and Next Change in Comparison buttons also enable fluid navigation between every change in every file of a split-view folder comparison. For more information, see the Navigation section of the Comparing Folders topic.

Overlapping changes

Particular care should be taken when merging changes from the two derived revisions that relate to the same section of the ancestor file. These are so-called overlapping changes (sometimes known as conflicting changes) and are clearly indicated in Merge because the linking lines connect the changes from the derived files to the same section of the ancestor file. The in-place editing capability is especially useful in these situations to allow fine-grained modifications to be made.

You can quickly highlight conflicting changes with a red conflict icon by previewing an automatic merge.

Non-overlapping changes

For non-overlapping changes, a single mouse click is usually all that is required to merge a change into the ancestor file. However, even with non-overlapping changes it is important that every one is carefully inspected to ensure it is compatible with the changes from the other derived files. It is not usually safe to assume that changes are compatible merely because they do not textually overlap. This is especially true of program source code.

Automatic merging

Merge provides the ability to automatically merge two derived files into the common ancestor. Although this is a useful feature, care should be taken to ensure that the results of the automatic merge are appropriate.