Synchronization Links

When comparing large text or binary files that contain many changes or moved blocks of lines, comparison results can sometimes appear to be unhelpful in places. You can add synchronization links to a file comparison to specify points of similarity between the files to improve results. Synchronization links are especially useful in cases where inserted, removed or changed lines cause the file comparison to show detailed changes between entirely unrelated lines.

Information When enabled, the Automatically link recognized semantic elements (functions, classes, etc.) option is able to add certain synchronization links automatically for some types of files. Automatically added synchronization links are coloured grey, rather than the usual blue, thus distinguishing them from manually added links.

The example below shows a scenario where a synchronization link is used to improve comparison results.


The screenshot below shows an example file comparison. The methods functionB and functionC have been swapped in the second file. There are sufficient similarities between functionB and functionC that Merge tries to compare them against each other:

Partial screenshot showing linking lines

Information The Text comparisonsLine pairingCompare and highlight lines based on words (rather than characters) option has been unchecked for the screenshots in this topic. This makes the individual character differences clearly visible.

A synchronization link can be provided to the file comparison so that functionB in the first file is compared against functionB in the second file. To add a synchronization link, right-click within the central linking-lines panel, and choose the Add Synchronization Link Here command:

Partial screenshot showing synchronization links context menu

Synchronization links appear as blue lines that connect a point within one file to a point within the other file:

Partial screenshot showing a newly-added synchronization link

Synchronization links can be repositioned within the linking lines panel by moving the mouse pointer over the blue arrow-head, clicking, and then dragging up or down. The file comparison results are updated shortly after you release the mouse button. The screenshot below shows the result of dragging the right arrow-head down to the top of functionB.

Partial screenshot showing an adjusted synchronization link

Merge has now marked the two functionC blocks as removed and inserted, with the result that you can see how functionB has changed between the two files. The merging buttons and text editing can be used as usual to make any modifications that may be required.

When you’ve finished examining functionB, the synchronization links can be repositioned to enable comparison of functionC:

Partial screenshot showing a repositioned synchronization link

You can add as many synchronization links as you like to a file comparison. A synchronization link arrow-head may point to the same position as another synchronization link, but synchronization link lines should not cross over one-another. If they do, the synchronization links that cross will turn red and will be ignored by the file comparison:

Partial screenshot showing ignored, overlapping synchronization links

Use the Remove Synchronization Link and Remove All Synchronization Links commands on the context menu (see the second screenshot above) to remove synchronization links.