Compare Directories

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 Compare Directories script (compareDirs.sh, found in the scripts subfolder inside Oxygen's installation directory) can be used to compare two directories and get the comparison results in various formats.

Arguments for the Compare Directories Script

sh scripts/compareDirs.sh firstDirPath [-a dirPathAlias] secondDirPath [-a dirPathAlias] [[baseDirPath [-a dirPathAlias]] [-sl suppressLinks] [-if includeFilesFilter] [-ia includeArchives] [-ef excludeFilesFilter] [-ed excludeSubdirsFilter] [-cm comparisonMode] [-alg comparisonAlg] [-als algStrength] [-iws ignoreWS] [-ipi ignorePI] [-icm ignoreComments] [-idt ignoreDocType] [-itn ignoreText] [-ins ignoreNS] [-ind ignoreNSDecl] [-inp ignorePrefixes] [-iao ignoreAttrOrder] [-iee ignoreExpStateForEmptyElems] [-enx XPathExprToExcludeNodes] [-out outputFormat] [-outfile outputFile] [-merge mergeOperation] [-mergeout outputDirPathForMerge]] [-help | --help | -h | --h]

firstDirPath

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

secondDirPath

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

baseDirPath

Optional argument that specifies the path of the base directory that the other two directories will be compared against in a 3-way comparison (it can also be provided as a URL). If present, it must appear immediately after the first two mandatory arguments.

-a dirPathAlias

Optional argument used as the directory path alias to be displayed in the HTML-formatted operation report instead of a long directory path. If present, it must appear immediately after a directory path.

-sl suppressLinks

Set this to true to suppress links to the compared directories and files shown in the HTML-formatted operation report. Default value = false.

-if includeFilesFilter

Use this argument to only include files that match the specified pattern in the comparison (e.g. .xml, .json). Default value = *.

-ia includeArchives

If set to true, files from archives are included in the comparison. Default value = false.

-ef excludeFilesFilter

Use this argument to exclude files that match the specified pattern from the comparison (e.g. *.jpg).

-ed excludeSubdirsFilter

Use this argument to exclude sub-directories that match the specified pattern from the comparison (e.g. .svn, _svn, .git).

-cm comparisonMode

Specifies the comparison mode. There are three modes available: content, binary, and timestamp. Default value = content.

-alg comparisonAlg

Specifies the algorithm to be used for the comparison. Possible values: auto, chars, words, lines, syntax_aware, xml_fast, and xml_accurate. Default value = auto.

-als algStrength

Specifies the strength of the algorithm to be used for the comparison. Possible values: low, medium, high, and very_high. Default value = medium.

-iws ignoreWS

If set to true, whitespaces are ignored if differences consist only of whitespaces. Default value = false.

-ipi ignorePI (only for the XML-aware algorithms)

If set to true, processing instructions are ignored in the comparison. Default value = false.

-icm ignoreComments (only for the XML-aware algorithms)

If set to true, comments are ignored in the comparison. Default value = false.

-idt ignoreDocType (only for the XML-aware algorithms)

If set to true, DOCTYPE sections are ignored in the comparison. Default value = false.

-itn ignoreText (only for the XML-aware algorithms)

If set to true, text content is ignored in the comparison. Default value = false.

-ins ignoreNS (only for the XML-aware algorithms)

If set to true, namespaces are ignored in the comparison. Default value = false.

-ind ignoreNSDecl (only for the XML-aware algorithms)

If set to true, namespace declarations are ignored in the comparison. Default value = false.

-inp ignorePrefixes (only for the XML-aware algorithms)

If set to true, prefixes are ignored in the comparison. Default value = false.

-iao ignoreAttrOrder (only for the XML-aware algorithms)

If set to true, the order of attributes is ignored in the comparison. Default value = false.

-iee ignoreExpStateForEmptyElems (only for the XML-aware algorithms)

If set to true, the expansion state for empty elements is ignored in the comparison. Default value = false.

-enx XPathExprToExcludeNodes

Specifies an XPath expression to exclude certain nodes from the comparison.

-merge mergeOperation

If set to true, a merge operation is invoked after the comparison. Default value = false.

Notes:

This argument is considered only for 3-way comparisons (i.e. only if the baseDirPath argument is provided).
The merge operation is similar to the same process in any versioning system. Following the comparison between the first and second directories (relative to the base folder), all the differences of the type incoming are considered and the content of the first directory is updated accordingly.
Conflicting changes are not addressed.
After the comparison, a report is created that provides details about the changes that were made.

-mergeout outputDirPathForMerge

Invokes a merge operation after the comparison and also allows you to specify the output directory path for the merge operation. For example, it allows you to specify a specific existing or new directory where the results of the merge operation is saved, other than the first directory path for the comparison (which is what happens when using only the -merge argument). The path of the directory can also be provided as a URL using file:// protocol. This argument and the -merge argument are not dependent on each other.

-out outputFormat

Specifies the format of the output. Possible values: yaml/grouped, yaml/raw, json/grouped, json/raw, xml/grouped, xml/raw, html, html/ifcr, htm, or htm/ifcr. Default value = yaml/grouped.

Notes:

If you choose to save/redirect the console output to a file, this argument establishes the type of the output file and its content is formatted accordingly. If you skip specifying the "/grouped" or the "/raw" qualifiers, "/grouped" takes precedence.
If you choose the html or htm output format, it is recommended that you also choose to save/redirect the console to the specified HTML file to view the comparison result in your preferred browser.
The "/ifcr" qualifier for the html or htm values is considered only if the -outfile argument is also present. IFCR is an acronym for Include File Comparison Reports and it means that, along with generating the directory comparison report, separate file comparison reports will be generated for all modified file pairs. These reports are available through links from the main report and are saved to a specific directory based on the value provided by the outfile argument. It will have the same parent directory and the same name as the outputFile plus -OXY-FC-REPORTS added to the end of its name.
The html value, as well as the grouped, raw, or ifcr qualifiers, are not considered if the -merge argument is present.

-outfile outputFile

Specifies the path for an output file to save the comparison results, instead of presenting them in the console. The content of the output file is formatted according to the -out argument. The output file path can also be provided as a URL using file:// protocol.

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

Displays help text.

Notes:

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.
File markers used in reports are as follows: M = modified, O1 = only found in 1st directory, O2 = only found in 2nd directory.

Examples of Compare Directories Script

Example 1: Compare Directories and Include Archives While Excluding JPEGs

The following command results in archives being included in the comparison, while JPEGs are excluded:

sh scripts/compareDirs.sh dir1 dir2 -ia true -ef *.jpg

Example 2: Compare Directories Only Including XML Files While Excluding Comments and the Attribute Order

The following command only includes XML files (even from archives) in the comparison, while ignoring the comments and attribute order:

sh scripts/compareDirs.sh dir1 dir2 -if *.xml -ia -iao -icm

Example 3: Compare Directories Only Including XML Files While Excluding Comments and the Attribute Order

The following command redirects the comparison results to a JSON file named "results.json", with "raw" mode formatting:

sh scripts/compareDirs.sh dir1 dir2 -out json/raw > results.json

Example 4: Compare Directories and Generate Comparison Report

It is possible to generate a report in the form of an HTML file that contains the results of the comparison. The following command compares the directories and redirects the console to the specified HTML file to view the comparison results:

sh scripts/compareDirs.sh dir1 dir2 -out html -outfile results.html

Figure 1. Example of an HTML Report for Directory Comparison

Resources

For more information about the file comparison script and how to generate comparison reports in various formats, see the following resources:

Tip: For some GitHub use case samples of this script, see Oxygen Comparison Template and Oxygen Comparison Action.