File Comparison Tool

How to Start a File Comparison

There are various ways to automatically start the file comparison, but the most common ways are:

You can select two files (or three file if one of them is a common ancestor) in the Project Explorer view, right-click, and select one of the options in the Compare With menu (e.g. Compare With > Each Other to compare the selected files).
If you use a versioning system, you can compare files directly from the Synchronize view (e.g. double-click a file or right-click selected files and choose Open In Compare Editor) or the History view.

Visual Author Comparison Mode

The visual Author file comparison mode makes it easier to see how the compared changes will look in the final output. It includes unique features such as actions to control the tags display mode, the ability to do second-level comparisons, and it presents differences made with Change Tracking enabled.

If there is a CSS associated with the documents (either directly in the document or in the framework definition), the visual comparison tool is presented automatically when you compare XML files in Oxygen XML Author Eclipse plugin. If the comparison is automatically started in the text-based mode, you can switch to the visual comparison mode by clicking the Switch to Author Mode toolbar button.

Attention: If the documents do not have an associated CSS, the visual comparison mode cannot render the document properly, so the text-based mode is used in this situation.

You can compare versions in the Workbench with versions in the repository, or with the local edit history. You can also compare three files if a common ancestor exists. The two editors are constantly synchronized and the differences are refreshed when you save the modified document.

Text-based Comparison Mode

Oxygen XML Author Eclipse plugin also includes a text-based comparison mode. When in the Author comparison mode, you can switch to the text-based mode by clicking the Switch to Text Mode toolbar button.

Most of the options, features, and actions that are available for the visual-based comparison mode are also available in the Text comparison mode, although more algorithms are available in Text mode.

Highlight Colors

The differences are also highlighted in several colors, depending on the type of change. The highlighting colors can be customized in the Diff > Appearance preferences page. The default colors and their shades mean the following:

Pink - Identifies modifications on either side. For 3-way comparisons, it identifies blocks of changes that include conflicts.
Gray - Identifies an addition of a node in the left side (your outgoing changes). For 3-way comparisons, it identifies your outgoing changes that do not include conflicts.
Blue - Identifies an addition of a node in the right side (incoming changes). For 3-way comparisons, it identifies incoming changes that do not include conflicts.
Lighter Shade - Identifies blocks of changes that can be merged in their entirety.
Darker Shade - Identifies specific changes within the blocks that can be merged more precisely.

Navigating Differences

To navigate through differences, do one of the following:

Use the navigation buttons on the toolbar.
Select a block of differences by clicking its small colored marker in the overview ruler located in the right-most part of the window. At the top of the overview ruler there is a success indicator that turns green where there are no differences, or red if differences are found.

Toolbar Actions

A variety of actions are available on the toolbar:

Switch to Text Mode (Not available in Author comparison mode): Switches to the text-based file comparison mode.
Switch to Author Mode (Only available in Text mode): Switches to the visual Author file comparison mode.
Tags Display Mode (Only available in Author comparison mode): Allows you to select the amount of markup to be displayed in the editors. You can choose between: Full Tags with Attributes, Full Tags, Block Tags, Block Tags without Element Names, Inline Tags, Partial Tags, or No Tags.
Diff Options: Opens the Diff preferences page where you can configure various options.
Algorithm Drop-down menu (Only available in Text mode): This drop-down menu allows you to select a diff algorithm to use for the comparison (depending on whether it is a two-way or three-way comparison).
Swap Left and Right View: Swaps the file in the left pane with the one in the right pane.
Copy All Non-Conflicting Changes from Left to Right: Copies all non-conflicting changes from the file in the left pane to the file in the right pane.
Copy All Non-Conflicting Changes from Right to Left: Copies all non-conflicting changes from the file in the right pane to the file in the left pane.
Copy Current Change from Left to Right: Copies the current change from the file in the left pane to the file in the right pane.
Copy Current Change from Right to Left: Copies the current change from the file in the right pane to the file in the left pane.
Next Difference: Navigates to the next block of changes. This action is not available when the cursor is positioned on the last change block or when there are no changes.
Note: A change block groups one or more consecutive lines that contain at least one change.
Previous Difference: Jumps to the previous block of changes. This action is not available when the cursor is positioned on the first change block or when there are no changes.
Next Change: Jumps to the next change from the current block of changes. When the last change from the current block of changes is reached, it highlights the next block of changes. This action is not available when the cursor is positioned on the last change or when there are no changes.
Previous Change: Jumps to the previous change from the current block of changes. When the first change from the current block of changes is reached, it highlights the previous block of changes. This action is not available when the cursor is positioned on the first change or when there are no changes.

Contextual Menu Actions

The following contextual menu actions are available in each editor pane:

Undo: Undo changes in the currently focused editor pane.
Redo: Redo changes in the currently focused editor pane.
Cut: Cut the selection from the currently focused editor pane to the clipboard.
Copy: Copy the selection from the currently focused editor pane to the clipboard.
Paste: Paste content from the clipboard into the currently focused editor pane.
Select all: Selects all content in the currently focused editor pane.
Find/Replace: Performs a find/replace operation in the currently focused editor pane.

Algorithms

In Text mode, you can select the diff algorithm to use for the comparison using the

Algorithm Drop-down menu that is available on the toolbar. The following diff algorithms are available (depending on whether it is a two-way or three-way comparison):

Auto (only available for two-way comparisons) - Selects the most appropriate algorithm, based on the compared content and its size (selected by default).
Characters (only available for two-way comparisons) - Computes the differences at character level, meaning that it compares two files or fragments looking for identical characters.
Words (only available for two-way comparisons) - Computes the differences at word level, meaning that it compares two files or fragments looking for identical words.
Lines - Computes the differences at line level, meaning that it compares two files or fragments looking for identical lines of text.
Syntax Aware (only available for two-way comparisons) - Computes differences for the file types or fragments known by Oxygen XML Author Eclipse plugin, taking the syntax (the specific types of tokens) into consideration.
XML Fast - Comparison that works well on large files or fragments, but it is less precise than XML Accurate.
XML Accurate - Comparison that is more precise than XML Fast, at the expense of speed. It compares two XML files or fragments looking for identical XML nodes.

In Author mode, only the Auto, XML Fast, and XML Accurate algorithms are available and you can select them from the Diff preferences page (easily accessible by clicking the Diff Options toolbar button).

Second-Level Comparisons

The comparison tool automatically performs a second-level comparison for the XML Fast and XML Accurate algorithms. After the first comparison is finished, the second-level comparisons is processed on text nodes using a word-level comparison, meaning that it looks for identical words. This second-level comparison makes it easier to spot precise differences and you can merge or reject the precise modifications.

Resources

For more information about the visual editing support for JSON, watch our video demonstration: