Compare Files

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 Files script (compareFiles.sh, found in the scripts subfolder inside Oxygen's installation directory) can be used to compare files (2-way or 3-way) and get the comparison results in various formats.

Arguments for the Compare Files Script

sh scripts/compareFiles.sh firstFilePath secondFilePath [[baseFilePath] [-ct contentType] [-alg comparisonAlg] [-als algStrength] [-iws ignoreWS] [-ipi ignorePI] [-icm ignoreComments] [-icd ignoreCDATA] [-idt ignoreDocType] [-itn ignoreText] [-ins ignoreNS] [-ind ignoreNSDecl] [-inp ignorePrefixes] [-iao ignoreAttrOrder] [-iee ignoreExpStateForEmptyElems] [-enx XPathExprToExcludeNodes] [-out outputFormat]] [-help | --help | -h | --h]

firstFilePath

Mandatory argument that specifies the first file path (it can also be provided as a URL).

secondFilePath

Mandatory argument that specifies the second file path (it can also be provided as a URL).

baseFilePath

Optional argument that specifies the path of the base file that the other two files will be compared against in a 3-way comparison (it can also be provided as a URL).

-ct contentType

Specifies the content type of the files to be compared. Possible values (based on known extensions of some of the most common file types): .xml, .dtd, .css, .rnc, .xquery, .json, .yaml, .java, .js, .c, .cpp, .pl, .py, .php, .sql, .bat, .sh, .properties, .txt. The option is used to force the file handling to the specific type of file. Otherwise, the file extension is auto-detected.

-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 baseFilePath argument is provided).
The merge operation is similar to the same process in any versioning system. Following the comparison between the first and second files (relative to the base file), all the differences of the type incoming are considered and the content of the first file is updated accordingly.
If conflicting changes are detected, the merge operation is aborted and the first file remains unchanged.
After the comparison and merge, a report is created that provides some 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 merged file. Instead of directly affecting the first compared file (which is what happens when using only the -merge argument), a new file is created with the same name as the first file and it is saved in the specified directory. The path of the output directory can also be provided as a URL. This argument and the -merge argument are not dependent on each other.

-out outputFormat

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

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 choose any of the html, html/inlineCSS, htm, or htm/inlineCSS output formats, 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 inlineCSS qualifier for the html and htm values implies that the CSS-based generated HTML code is more suitable to be directly inserted in emails (as most email clients only accept inline CSS styling for HTML emails.
The html and htm values (with or without the inlineCSS qualifier) 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.

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

Displays help text.

Note: 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

Examples of Compare Files Script

Example 1: Compare Files and View Results in XML Format

The following command compares the files (ignoring the namespaces and prefixes) and redirects the console output to the results.xml file (XML-formatted):

sh scripts/compareFiles file1 file2 -ins -inp -ind -out xml > results.xml

Example 2: Compare Files with Line by Line Algorithm

The following command compares the files using the lines algorithm and ignores whitespaces:

sh scripts/compareFiles.sh file1 file2 -alg lines -iws

Example 3: Compare Files 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 files and redirects the console to the specified HTML file to view the comparison results:

sh scripts/compareFiles.sh file1 file2 -out html -outfile outFileName.html

Figure 1. Example of File Comparison Report in HTML Format

Resources

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

Webinar: The New Oxygen Compare and Merge Scripts.
Video: Generating File Comparison Reports Using Command-Line Scripts.