Edit online

Compare Files Tool

The built-in Compare Files tool can be used to compare files or XML file fragments. The tool provides a mechanism for comparing two files or fragments, as well as the mechanism for a three-way comparison. The utility is available from the Tools > Comparison Tools menu or can be opened as a stand-alone application from the Oxygen XML Developer installation folder (diffFiles.exe).

Figure 1. Compare Files Tool

Two-Way Comparisons

The Compare Files tool can be used to compare the differences between two files or XML fragments.

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 actions in the Browse drop-down menu.

    Step Result: The selected files are opened in the two side-by-side editors. A text editing mode 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.
The resulting comparison will show you differences between the two files. The line numbers on each side and colored marks on the right-side vertical stripe help you to quickly identify the locations of the differences. Adjacent changes are grouped into blocks of changes. This layout allows you to easily identify and focus on a group of related changes.
Figure 2. Two-Way Differences
Highlighting Colors
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.
Comparing Fragments (Copy/Paste)
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 macOS)) button, before pasting the fragments. Other notes for pasting fragments:
  • As long as the fragment is more than 10 characters, the application will attempt to automatically detect the content type. It can detect the following types: XML, DTD, CSS, JSON, and Markdown (if it starts with #). If one of those content types is detected, the fragments will be displayed with syntax highlights.
  • If you save modified fragments, a dialog box opens that allows you to save the changes as a new document.
Navigate Differences
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.
Editing Actions

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.
Two-Way Diff Algorithms
Oxygen XML Developer 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.

Three-Way Comparisons

Oxygen XML Developer also includes a three-way comparison feature to help you solve conflicts and merge changes between multiple modifications. It is especially helpful for teams who have multiple authors editing and committing the same documents. It provides a comparison between a local change, another change, and the original base revision. Some additional advantages include:
  • Visualize and merge content that was modified by you and another member of your team.
  • Marks differences correctly even when the document structure is rearranged.
  • Allows you to merge XML-relevant modifications.
Figure 3. Three-Way Comparison
Compare Files
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 actions in the Browse drop-down menu.

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

  2. Click the Three-Way Comparison button on the toolbar and select the base (original) file in the Base field. You can specify the path by using the text field, the history drop-down, or the browsing actions 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.
The resulting comparison will show you differences between the two files, as well as differences between either of them and the base (original) file. The line numbers on each side and colored marks on the right-side vertical stripe help you to quickly identify the locations of the differences. Adjacent changes are grouped into blocks of changes.
Figure 4. Three-Way Differences
Highlighting Colors
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.
Navigate Differences
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.
Editing Actions

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.
Three-Way Diff Algorithms
Oxygen XML Developer 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.

Second-Level Comparisons

For both two-way and three-way comparisons, Oxygen XML Developer automatically performs a second-level comparison for the Lines, XML Fast, and XML Accurate algorithms. After the first comparison is finished, the second-level comparison for the Lines algorithm is processed on text nodes using a word level comparison, meaning that it looks for identical words. For the XML Fast and XML Accurate algorithms, the second-level comparison is processed using a syntax-aware comparison, meaning that it looks for identical tokens. This second-level comparison makes it easier to spot precise differences and you can merge or reject the precise modifications.

Figure 5. Second-Level Diff Comparison
Note: If a modified text fragment contains XML markup (such as processing instructions, XML comments, CData, or elements), the second-level comparison will not automatically be performed. In this case you can manually select a second-level comparison by doing a word level or character level comparison.

To do a word level comparison, select Show word level details from the contextual menu or Compare menu.

Figure 6. Word Level Comparison

To do a character level comparison, select Show Character Level details from the contextual menu or Compare menu.

Figure 7. Character Level Comparison