Merge Directories with Change Tracking Highlights

Attention: This script is bundled with the all platforms distribution of Oxygen XML Author Eclipse plugin. To run the script, you are required to purchase a special scripting commercial license.

The Merge Directories with Change Tracking Highlights script (mergeDirsTrackChanges.sh, found in the scripts subfolder inside Oxygen's installation directory) can be used to merge 2 directories (based on a 2-way comparison). All pairs of modified XML files involved in the process are merged by saving the Author mode comparison results as documents with highlighted tracked changes that can be later reviewed and accepted or rejected.

Arguments for the Merge Directories with Change Tracking Highlights Script

sh mergeDirsTrackChanges.sh pathOfBaseDir pathOfDirToMergeWith [[pathOfOutDir] [-nb noBackupOfBaseDir] [-nu noUpdateOfModifNonXMLFiles] [-na noAddingFilesOnlyPresentInDirToMergeWith] [-nd noDeletionOfFilesOnlyPresentInBaseDir] [-cm createChangeTrackingMarkersForAddedXMLFiles]] [-help | --help | -h | --h]

pathOfBaseDir

Mandatory argument that specifies the path of the base directory (it can also be provided as a URL using file:// protocol).

pathOfDirToMergeWith

Mandatory argument that specifies the path of the directory to merge with (it can also be provided as a URL using file:// protocol).

pathOfOutDir

Optional argument that specifies the path of the directory where the merge operation results are saved to (it can also be provided as a URL using file:// protocol). If present, it must appear immediately after the first two mandatory arguments. If absent, the merge results are saved to the base directory, by overwriting it. You cannot choose the same directory specified as the directory to merge with as the output directory (the merge process is aborted in this case).

-nb noBackupOfBaseDir

Set to true if you do not want a backup copy of the base directory on the hard disk. There are 2 situations when a backup of the base directory is performed automatically and the backup operation must succeed to proceed with the merge. Otherwise, the merge process is aborted if the output directory is not specified (i.e. the pathOfOutDir argument is not present) or the specified output directory is the base directory itself.

The backup copy will have the same parent directory as the base directory and its name will be the name of the base directory suffixed by ".OXY.BAK". The default value is false, which means that for either of the 2 previously mentioned situations, a backup copy of the base directory will be kept on the hard disk.

-nu noUpdateOfModifNonXMLFiles

Set to true if you want to keep the non-XML files at their versions from the base directory. The default value is false, which means that all files in the output directory that are copies of non-XML files in the base directory will be replaced by their corresponding files in the directory to merge with.

-na noAddingFilesOnlyPresentInDirToMergeWith

Set to true if you want to skip adding the files that are only present in the directory to merge with to the output directory as well. The default value is false, which means that all files that are only present in the directory to merge with are also added to the output directory.

-nd noDeletionOfFilesOnlyPresentInBaseDir

Set to true if you want to preserve the files that are only present in the base directory. The default value is false, which means that all files that are only present in the base directory and initially copied to the output directory are deleted.

-cm createChangeTrackingMarkersForAddedXMLFiles

Set to true if you want to create change tracking markers for the XML files only present in the directory to merge with (that will be added to the output directory). Although these files have no counterparts in the base directory, change tracking markers of the type "entire content added/inserted" will be created. The option is not necessarily intended for the merge process itself, but it might prove a useful addition when you want to apply various Oxygen transformation scenarios to the resulting output directory. For example, if you merge 2 versions of a DITA project and then want a PDF to highlight the changes between those versions, you can apply a transformation on the resulting ditamap file. The -am option presents the new DITA files as "added content" in the resulting PDF. Note that the option is only considered if the -na argument is absent or is explicitly set to false (default value).

-help | --help | -h | --h

Displays help text.

Notes:

The merge process has a preliminary phase where the entire structure and content of the base directory is copied to the output directory.
For boolean arguments, it is not necessary to provide the "true" value. Their presence in the argument list is equivalent to setting their value to "true" (and their absence from the argument list is equivalent to setting their value to "false"). However, constructs of the form bool_option true|false are accepted and interpreted accordingly.
Once the merge operation is complete, a report file is created and saved in the output directory (in a separate subdirectory named ".__OXY__MERGE__REPORT"). Loading the report file in Oxygen XML Author Eclipse plugin provides additional functionality. Aside from the fact that the report provides an overview of the merge process, it also provides links to all the files in the resulting output directory. You can use the respective links to load the XML files in the editor, then switch to Author mode to review the tracked changes and accept or reject them.

Examples of Compare Directories Script

Example 1: Compare Directories Without Updating non-XML Files

The following command results in merging dir1 and dir2 into outdir, but without updating the non-XML files in dir1 detected with changes to their version in dir2:

sh scripts/mergeDirsTrackChanges.sh dir1 dir2 outdir -nu

Example 2: Compare Two Directories and Overwrite the First One

The following command results in merging dir1 and dir2 by overwriting dir1. However, the dir1 is backed up first:

sh scripts/mergeDirsTrackChanges.sh dir1 dir2

Example 3: Compare Directories and Create Change Tracking Markers

The following command results in merging dir1 and dir2 into outdir and creating change tracking markers (of the type "entire content added/inserted") for all XML files that are only present in dir2 (to be added to the outdir):

sh scripts/mergeDirsTrackChanges.sh dir1 dir2 outdir -cm

Figure 1. Example of a Merged File with Change Tracking Markers Opened in Author Mode