Edit online

Compare Directories Against a Base (3-Way) Tool

The Compare Directories Against a Base (3-way) tool allows you to perform three-way comparisons on directories to help you identify and merge changes between multiple modifications of the same directory structure. It is especially helpful for teams that have multiple authors contributing documents to the same directory system. It offers information about conflicts and changes, and includes actions to easily merge, accept, overwrite, or ignore changes to the directory system.

How to Perform 3-Way Directory Comparisons

To perform a 3-way directories comparison, follow these steps:

Select Compare Directories Against a Base (3-way) from the Tools > Comparison Tools menu.

Step Result: This opens a dialog box that allows you to select the 3 file sets that will be used for the comparison.

Figure 1. Compare Directories Against a Base File Set Chooser
Select the file sets to be compared:
- Base directory - This is the original (base) file set before any modifications were made by you or others.
- Directory with your changes - This is the file set with changes that you have made. This file set will be displayed in the left panel in the comparison tool.
- Directory with changes made by others - This is the file set with changes made by others that you want to merge with your changes. This file set will be displayed in the right panel in the comparison tool.
Click the Compare button to compare the file sets and open the comparison and merge tool.
Use the features and actions described in the next section to identify and merge the changes.

3-Way Directory Comparison and Merge Tool

The 3-way directory comparison and merge tool includes the following information, features, and actions:

Number of Changes and Conflicts

The first thing you see in the top-left corner of the tool is the grand total of all the changes made by others, changes made by you, and the number of conflicts.

Filter Buttons

In the top-right corner you can use the toggle buttons to filter the list of modifications:

Show all files: Use this button to show all modified and unmodified files, as well as conflicts.
Show only files modified by you and others: Filters the list to show all files that have been modified, including conflicts.
Show only files modified by others: Filters the list to only show the files that were modified by others.
Show only files modified by you: Filters the list to only show the files that were modified by you.
Show only conflicting files: Filters the list to only show files that contain conflicts.

List of Files Panel

This panel shows the list of files in the compared file sets based upon the filter button that is selected. This panel includes the following sortable columns:

Name - The file names.
Status - An icon that represents the file status. Red icons indicate some sort of conflict. Gray icons indicate modifications made by you. Blue icons indicate modifications made by others.
Description - A description of the file status.
Merge Action - This column provides a drop-down menu for each file that allows you to choose some merge actions depending upon its status. A default action is always set to Automatically merge the changes made by others with your changes. If there is a conflict, the default is <Select action> and you are required to make a selection. Click this column to access the drop-down menu where you can make a selection. The same actions are available in the contextual menu.

Tip: If the solution proposed in the Merge Action column for any particular file is not satisfactory, you can change it directly in that column (even if that file is not selected) without automatically re-triggering the comparison (except for in certain cases where re-triggering the comparison is necessary).

You can click a file to open it in the file comparison panel (the file from your file set is shown in the left panel while the file from the file set with changes made by others is shown in the right panel). For image files, the comparison panel shows a preview of the image. For other binary files, a preview is not available and you will just see its status.

File Comparison Panels

If you click a file in the top panel, the file is opened in this file comparison section. The file from your file set is shown in the left panel and the file from the other file set is shown in the right panel.

Note: If Oxygen XML Author does not recognize the file type, a dialog box will be displayed that allows you to select the type of editor you want it to be associated with for this comparison (if you want Oxygen XML Author to remember this association, you can select the Associate file type with editor option at the bottom of the dialog box).

This panel includes the following information and toolbar actions:

File Path

The first thing you see in this panel is the file path where merge actions will be applied if you make changes.

Close

Closes the file comparison panel.

Algorithm Drop-down Menu

This drop-down menu allows you to select one of the following diff algorithms to be used for file comparisons:

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. This algorithm is not available when the file comparison is in Author comparison mode.
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.

Diff Options

Opens the Files Comparison preferences page where you can configure various options.

Perform Files Differencing

Looks for differences between the two files displayed in the left and right side panels.

Synchronized scrolling

Toggles synchronized scrolling. When toggled on, a selected difference can be seen in both panels.

Ignore Whitespaces

Enables or disables the whitespace ignoring feature. Ignoring whitespace means that before performing the comparison, the application normalizes the content and trims its leading and trailing whitespaces. This option is not available when the file comparison is in Author mode.

Tags Display Mode

Allows you to select the amount of markup to be displayed in the Author visual mode. You can choose between:

Full Tags with Attributes,

Full Tags,

Block Tags,

Block Tags without Element Names,

Inline Tags,

Partial Tags, or

No Tags.

Copy Change from Right to Left

Copies the selected difference from the file in the right panel to the file in the left panel.

Copy All Changes from Right to Left

Copies all changes from the file in the right panel to the file in the left panel.

Next Block of Changes (Ctrl + Period (Command + Period on macOS))

Jumps 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 Block of Changes (Ctrl + Comma (Command + Comma on macOS))

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 (Ctrl + Shift + Period (Command + Shift + Period on macOS))

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 (Ctrl + Shift + Comma (Command + Shift + M on macOS))

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.

First Change (Ctrl + B (Command + B on macOS))

Jumps to the first change.

Left-Side File (Your changes)

Above the panel you can see the file path and the following two buttons:

Save: Saves changes made to the file.
Reload: Reloads the file.

Right-Side File (Changes made by others)

Above the panel you can see the file path and the following two buttons:

Reload: Reloads the file.

Displaying Changes in the File Comparison Panels

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.

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.

Direct Editing Actions in the File Comparison Panels

In addition to selecting merge actions from the drop-down menus in the Merge Action column in the top panel, you can also edit the files directly in the left pane (your local changes). The two editors are constantly synchronized and the differences are refreshed when you save the modified document (Save button or Ctrl+S) or when you click the Perform File Differencing button.

A variety of actions are 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 right change to left: Copies the content of the selected change from the right side and appends it on the left side.
Copy change from right to left: Replaces the content of a change in the left side with the content of the change in the right side.
Remove change: Removes the change from the left side.

Anytime you save manual changes ( Save button or Ctrl+S), the selection in the Merge Action column in the top panel automatically changes to Use merged and a copy of the original file is kept so that you can revert to the original file if necessary. To discard your manual changes and revert to your original changes, select a different action in the Merge Action drop-down menu.

Open Merged Files

If you select this option, all the files that will be modified by the merge operation will be opened in the editor after the operation is finished.

Applying Changes

When you click the Apply button, all the merge actions you have selected and the changes you have made will be processed.

If there are unresolved conflicts (conflicts where no merge action is selected in the Merge Action drop-down menu), a dialog box will be displayed that allows you to choose how to solve the conflicts. You can choose between the following:

Keep your changes - If you select this option and then click Apply, your local changes will be preserved for the unresolved conflicts.
Overwrite your changes - If you select this option and then click Apply, your local changes will be overwritten with the changes made by others, for the unresolved conflicts.
Cancel - You can click the Cancel button to go back to the merge tool to resolve the conflicts individually.

Canceling Changes

If you click the Cancel button at the bottom of the merge tool, all the changes you made in the tool will be lost.

Author Visual Mode

The Comparison and Merge tool includes an Author mode that displays the files in a visual mode similar to the Author editing mode in Oxygen XML Editor/Author. This makes it easier to see how the compared changes will look in the final output. This visual mode is available when the compared files are detected as being XML. To determine whether the files are initially opened in the merge tool's Text or Author mode, it detects the Initial Edit Mode in the Document Type Association configuration and the mode the files were last opened in Oxygen XML Editor/Author.

Note: This mode is not available if the Enable file comparison in Author mode option is not selected in the Diff > Files Comparison preferences page.

This visual mode includes unique features such as a Tags Display Mode drop-down button on the toolbar that allows you to select the amount of tags to display in this visual mode. This mode also presents differences that were made using the Track Changes feature (although the Track Changes feature is not available in the comparison tool).

Figure 4. File Comparison Tool - Author Mode

Author Mode Algorithms

The visual Author mode offers the following diff algorithms to compare files:

Auto - Selects the most appropriate algorithm, based on the compared content and its size (selected by default).
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.

Author Mode Second-Level Comparisons

The visual Author mode automatically performs a second-level comparison for the XML Fast and XML Accurate algorithms. After the first comparison is finished, the second-level comparison 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.