Compare Files

To perform a two-way comparison, follow these steps:

1. Open a file in the left panel and the file you want to compare it to in the right panel. You can specify the path by using the text field, the history drop-down, or the browsing tools in the Browse drop-down menu.

   Step Result: The selected files are opened in the two side-by-side editors. A text perspective is used to offer a better view of the differences.

2. To highlight the differences between the two files, click the Perform File Differencing button from the toolbar.
3. You can use the drop-down menu on the left side of the toolbar to change the algorithm for the operation.
4. You can also use the Diff Options button to access the Files Comparison preferences page where you can choose to ignore certain types of markup and configure various options.
5. If you are comparing XML documents using the XML Fast or XML Accurate algorithms, you can enter an XPath 2.0 expression in the Ignore nodes by XPath text field to ignore certain nodes from the comparison.

Two-Way Differences

The differences are also highlighted in several colors, depending on the type of change, and dynamic lines connect the compared fragments in the middle section between the two panes. The highlighting colors can be customized in the Files Comparison / Appearance preferences page, but the default colors and their shades mean the following:

• Pink - Identifies modifications on either side.
• Gray - Identifies an addition of a node in the left side (your outgoing changes).
• Blue - Identifies an addition of a node in the right side (incoming changes).
• 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.

To compare XML file fragments, you need to copy and paste the fragments you want to compare into each side, without selecting a file. If a file is already selected, you need to close it using the Close (Ctrl + W (Command + W on OS X)) button, before pasting the fragments. If you save modified fragments, a dialog box opens that allows you to save the changes as a new document.

To navigate through differences, do one of the following:

• Use the navigation buttons on the toolbar (or in the Compare menu).
• 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.
• Click a colored area in between the two text editors.

You can edit the files directly in either editing pane. The two editors are constantly synchronized and the differences are refreshed when you save the modified document or when you click the Perform File Differencing button.

A variety of actions are available on the toolbar and in the various menus (these same actions are also available in the contextual menu in both editing panes). The tool also includes some inline actions to help you merge, copy, or remove changes. When you select a change, the following inline action widgets are available, depending on the type of change:

Append left change to right and Append right change to left

Copies the content of the selected change from one side and appends it on the other, according to the content of the corresponding change. As a result, the side where the arrow points to will contain the changes from both sides.

Copy change from left to right and Copy change from right to left

Replaces the content of a change from one side with the content of the corresponding change from the other side.

Remove change

Rejects the change on the particular side and preserves the particular content on the other side.

Oxygen XML Editor plugin offers the following two-way diff algorithms to compare files or fragments:

• Auto - Selects the most appropriate algorithm, based on the compared content and its size (selected by default).

• Characters - Computes the differences at character level, meaning that it compares two files or fragments looking for identical characters.

• Words - 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 - Computes differences for known file types or fragments. This algorithm splits the files or fragments into sequences of tokens and computes the differences between them. The meaning of a token depends on the type of compared files or fragments.

  Known file types include those listed in the New dialog box, such as XML file types (XSLT files, XSL-FO files, XSD files, RNG files, NVDL files, etc.), XQuery file types (.xquery, .xq, .xqy, .xqm extensions), DTD file types (.dtd, .ent, .mod extensions), TEXT file type (.txt extension), or PHP file type (.php extension).

  For example:

  • When comparing XML files or fragments, a token can be one of the following:
    • The name of an XML tag
    • The < character
    • The /> sequence of characters
    • The name of an attribute inside an XML tag
    • The = sign
    • The " character
    • An attribute value
    • The text string between the start tag and the end tag (a text node that is a child of the XML element corresponding to the XML tag that encloses the text string)
  • When comparing plain text, a token can be any continuous sequence of characters or any continuous sequence of whitespaces, including a new line character.

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

To perform a three-way comparison, follow these steps:

1. Open a file in the left panel and the file you want to compare it to in the right panel. You can specify the path by using the text field, the history drop-down, or the browsing tools in the Browse drop-down menu.

   Step Result: The selected files are opened in the two side-by-side editors. A text perspective is used to offer a better view of the differences.

2. Click the Three-Way Comparison button on the toolbar and select the base file in the Base field. You can specify the path by using the text field, the history drop-down, or the browsing tools in the Browse drop-down menu.
3. To highlight the differences, click the Perform File Differencing button on the toolbar.
4. You can use the drop-down menu on the left side of the toolbar to change the algorithm for the operation.
5. You can also use the Diff Options button to access the Files Comparison preferences page where you can choose to ignore certain types of markup and configure various options.

Three-Way Differences

The differences are also highlighted in several colors, depending on the type of change, and dynamic lines connect the compared fragments in the middle section between the two panes. The highlighting colors can be customized in the Files Comparison / Appearance preferences page, but the default colors and their shades mean the following:

• Pink - Identifies blocks of changes that include conflicts.
• Gray - Identifies your outgoing changes that do not include conflicts.
• Blue - 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.

To navigate through differences, do one of the following:

• Use the navigation buttons on the toolbar (or in the Compare menu).
• 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.
• Click a colored area in between the two text editors.

You can edit the files directly in either editing pane. The two editors are constantly synchronized and the differences are refreshed when you save the modified document or when you click the Perform File Differencing button.

A variety of actions are available on the toolbar and in the various menus (these same actions are also available in the contextual menu in both editing panes). The tool also includes some inline actions to help you merge, copy, or remove changes. When you select a change, the following inline action widgets are available, depending on the type of change:

Append left change to right and Append right change to left

Copies the content of the selected change from one side and appends it on the other, according to the content of the corresponding change. As a result, the side where the arrow points to will contain the changes from both sides.

Copy change from left to right and Copy change from right to left

Replaces the content of a change from one side with the content of the corresponding change from the other side.

Remove change

Rejects the change on the particular side and preserves the particular content on the other side.

Oxygen XML Editor plugin offers the following three-way diff algorithms to compare files:

• Auto - Selects the most appropriate algorithm, based on the compared content and its size (selected by default).

• Lines - Computes the differences at line level, meaning that it compares two files or fragments looking for identical lines of text.

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