diff, compare
The diff or compare command performs a side-by-side comparison of two files, directories, or URLs. The entities to be compared can be of different kinds (for example, you can compare a file URL like http://server/file.txt to a file path like C:\file.txt). Note that it is valid to compare files with URLs, for example, but not files and directories (or URLs and directories). Comparison of Microsoft Word 2003 or later documents (.docx, .dotx) is also supported. See Comparing Word Documents.
Most often, a comparison involves a "left" side and a "right" side to compare. However, three-way comparisons are also possible when comparing files or URLs—but not directories. The files or directories to be compared can all be on a DiffDog Server machine or on a DiffDog client machine. You can also compare local files or directories with remote ones. For examples, see Running Comparisons.
Comparison result
The format of the output comparison result can be text, XML, or HTML and is selected by the --output-mode option. By default the output is not quiet, which means that it will be displayed at the command line. Set the --quiet option to true suppress the display at the command line. Output can additionally be sent to file by using --output-file option. Tip: If you get an empty output file, try changing the --mode option, which specifies the type of comparison to be performed.
Syntax
diffdogserver diff [options] {path path [path]}
diffdogcmdlclient diff [options] {path path [path]}
Notes
•A path may be a file or directory path, or a URL path in the format http://server/segment.
•You can supply two paths or three paths as the arguments.
•You can supply paths not only as arguments, but also by setting the options --client-left, --client-right, or --server-left, --server-right (see below). Use the second alternative if the client does not run on the same machine as DiffDog Server.
•The paths must not be specified as a mix of arguments and options; they must be specified as one or the other.
•The job argument can be specified more than once in order to run multiple database comparison jobs in one run of the command.
•The --server and --port options apply to diffdogcmdlclient only. They specify the connection details of the server.
Options
The options below are listed in alphabetical order. You can specify defaults for most of the options below in the client configuration file. If you use a client configuration file, note the following:
•When an option is set at the command line but it is commented out in client configuration file, the command line option applies.
•When an option is set both at the command line and in a client configuration file, the command line option applies.
•When an option is not set at the command line but is set (uncommented) in configuration file, the configuration file option applies.
•When an option is set neither at the command line nor in the configuration file, it takes the default value as described in the command line help and in the documentation below.
If the server administrator has restricted access to server paths for security reasons, comparisons cannot use server file paths directly but must use an alias that the server administrator has assigned. This is done by specifying the alias in the --alias option (of the diff, compare and run, import, load commands). See Aliases for Server Folders for more information about this feature.
This option is meaningful if the comparison involves a server path (that is, if options --server-left or --server-right are set). Valid values for this option are aliases as defined in the Server Configuration File. To output the list of available aliases, run the aliases command. For more information, see Restricting Access to Server Paths.
|
Specifies the left side of the comparison. It must be a path to a local file or directory.
|
In a three-way comparison, it specifies the local path to the "middle" file.
|
Specifies the right side of the comparison. It must be a path to a local file or directory.
|
Specifies the path to a client configuration file containing the datadiff information and the details of the connection to DiffDog Server.
If you do not set the --c option, then diffdogcmdlclient attempts to read the client configuration file from the same directory as the executable. If there is no configuration file in the same directory, then the default values displayed by the showcfg CLI command and in the topic Client Configuration File are used.
|
Specifies whether a directory comparison should compare file contents in addition to any other options that might be set separately, such as file size or modification date. When set to false, the comparison ignores file contents, which will result in a faster, though less accurate, comparison. By default, this option is set to false.
|
Applicable for directory comparisons. It specifies that directory comparison should ignore the given number of seconds (+/-) when comparing modification times. By default, it is set to 0, which means the comparison will not ignore modification time differences.
|
Applicable for directory comparisons. The default value is false, which means that a case-sensitive comparison is performed.
|
Applicable for directory comparisons. When set to true, directory comparisons include file size; if not, file size is ignored. The default value is false.
|
Applicable for directory comparisons. When set to true, directory comparisons include modification time; if not, modification time is ignored. The default value is false.
|
This option is applicable for directory comparisons. Directory filters enable you to include or exclude certain files or sub-directories from the comparison based on criteria you define. Valid values for this option are directory filters as they are defined in the Client Configuration File, in the [dir.filter] group. For example, if the configuration file defines a filter [dir.filter:svn], the equivalent setting at the command line would be the option: --directory-filter=svn
On Windows, if DiffDog is installed on the same machine as DiffDog Server, then you can additionally specify any directory filter that already exists in DiffDog (either built-in or custom). For example, to set the built-in filter "No SVN directories" at the command line, use this: --directory-filter="No SVN directories"
For more information about creating directory filters with DiffDog, refer to the DiffDog documentation.
Note: If the filter cannot be found, an error occurs and no comparison takes place.
|
Applicable for comparison of Word documents. When set to true, bold formatting is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable for comparison of Word documents. When set to true, font color is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable for comparison of Word documents. When set to true, font name is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable for comparison of Word documents. When set to true, font size is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable for comparison of Word documents. When set to true, italic formatting is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable for comparison of Word documents. When set to true, underline formatting is taken into account for comparisons. Otherwise it is not. The default value is false.
|
Applicable when comparing Word documents or directories containing Word documents. In the case of directory comparisons, the option will apply only to Word documents in that directory. When set to true, blank lines will be ignored during comparisons. Otherwise they are not. The default value is false.
|
Applicable when comparing Word documents or directories containing Word documents. In the case of directory comparisons, the option will apply only to Word documents in that directory. When set to true, case will be ignored during comparisons. Otherwise it is not. The default value is false.
|
This option is applicable when comparing Word documents or directories containing Word documents. In case of directory comparisons, the option will apply only to Word documents in that directory.
The option defines how whitespace characters should be treated for comparison. Whitespace characters are any of the following: space, tab, carriage return, and line feed.
|
This option specifies if blank lines should be ignored in comparison. Valid values are true and false. The default value is false.
The option applies depending on the current --mode option. If --mode=text, it applies to text files, and is equivalent to the --text-ignore-blank-lines option. If --mode=xml, it does not affect the comparison. If --mode=doc, it applies to Word documents and is equivalent to --doc-ignore-blank-lines option. If you do a directory comparison, it applies to each kind of comparison that might occur in that directory.
|
This option is applicable to both file and directory comparisons. The option applies depending on the current --mode option. If --mode=text, it applies to text files and is equivalent to the --text-ignore-case option. If --mode=xml, it applies to XML files and is equivalent to --xml-ignore-case-in-names and --xml-ignore-case-in-text options. If --mode=doc, it applies to Word documents and is equivalent to the --doc-ignore-case option. If you do a directory comparison, it applies to each kind of comparison that might occur in that directory.
When set to true, case will be ignored during comparisons. Otherwise it is not. The default value is false.
|
Sets the reporting level to show information, warning, or error messages. Valid values are:
•none: Suppress all logging •info: Report information, warning, and error messages •warning: Report error and warning messages •error: (Default) Report only error messages
|
Specifies the comparison type to be performed. The option and its values (given below) can be applied to both file and directory comparisons. In the case of directory comparisons, the default "auto" option is a "quick" comparison. It compares files in the directory and its sub-directories by size and date modified. Selecting any of the other values for directory comparisons does the comparison with file contents treated as the selected value (for example, as XML files).
|
This option enables you to write the command output to a text file on the client machine. The value must specify a valid file path on the client machine. Use the --om option to set the output file format.
|
Specifies the output format of the generated report. The following values are available: auto (default option), text, xml, html.
Note: The option --output-mode=text is not supported when comparing XML files or Word documents.
|
Specifies the port on which DiffDog Server listens for requests. If this option is not set, then the port specified in the Client Configuration File will be used (29800 by default). The --port option overrides the setting in the config file.
|
Prevents the standard output from being displayed at the command line. Valid values are:
•true: Do not display standard output in the terminal window. •false: (Default) Display standard output in the terminal window.
|
Specifies the server on which DiffDog Server listens for requests. If this option is not set, then the server specified in the Client Configuration File will be used (127.0.0.1 by default). The --server option overrides the setting in the config file.
|
This option enables you to write the command output to a text file on the server machine. The value must specify a valid file path on the server machine. Use the --om option to set the output file format.
|
This option enables you to add a remote path to the comparison. It specifies the left side of the comparison (a path to a file or directory accessible to the server).
|
This option enables you to add a remote path to the comparison. It specifies the middle side of the comparison (applicable in a 3-way comparison). The value must be a path to a file or directory accessible to the server.
|
This option enables you to add a remote path to the comparison. It specifies the right side of the comparison (a path to a file or directory accessible to the server).
|
This option is applicable when comparing text documents or directories containing text documents. In case of directory comparisons, the option will apply only to text files in that directory. When set to true, case will be ignored during comparisons. Otherwise it is not. The default value is false.
|
This option is applicable when comparing text documents or directories containing text documents. In case of directory comparisons, the option will apply only to text files in that directory. The option specifies whether blank lines should be ignored when comparing text files. Valid values are true and false. The default value is false.
|
This option is applicable when comparing text documents or directories containing text documents. In case of directory comparisons, the option will apply only to text files in that directory.
The option defines how whitespace characters should be treated for comparison. Whitespace characters are any of the following: space, tab, carriage return, and line feed.
|
This option is applicable to file and directory comparisons. The option applies depending on the current --mode option. If --mode=text, it applies to text files, and is equivalent to the --text-whitespace-mode option. If --mode=xml, it applies to XML files. If --mode=doc, it applies to Word documents and is equivalent to --doc-whitespace-mode option. If you do a directory comparison, it applies to each kind of comparison that might occur in that directory based on the file extension.
The option defines how whitespace characters should be treated for comparison. Whitespace characters are any of the following: space, tab, carriage return, and line feed.
If the compared files are XML, normalization and stripping affects whitespace characters that are inside attribute or element values. Other whitespace characters are disregarded.
|
This option is applicable for XML comparisons. An XML filter contains rules that ignore specific XML attributes or elements for comparison. Valid values for this option are XML filters as they are defined in the Client Configuration File, in the [xml.filter] group. For example, if the configuration file defines a filter [xml.filter:ignore-abc-elems], the equivalent setting at the command line would be the option: --xml-filter=ignore-abc-elems
On Windows, if DiffDog is installed on the same machine as DiffDog Server, then you can additionally specify any XML filter that already exists in DiffDog. For more information about creating directory filters with DiffDog, refer to the DiffDog documentation.
Note: If the filter cannot be found, an error occurs and no comparison takes place.
|
This option is applicable when comparing XML files or directories containing XML files. In case of directory comparisons, the command will apply only to XML files in that directory. When set to true, a case-insensitive comparison of XML node names will be performed. The default value is false.
|
This option is applicable when comparing XML files or directories containing XML files. In case of directory comparisons, the command will apply only to XML files in that directory. When set to true, a case-insensitive comparison of XML text nodes will be performed. The default value is false.
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. Valid values:
|
This option is applicable when comparing XML files. When set to true, XML namespaces will be ignored. The default value is false.
|
This option is applicable when comparing XML files. When set to true, XML prefixes will be ignored. For example, let's assume that you want to compare the XML files below. Both files contain identical elements but the prefixes are different.
By default, the --xml-ignore-prefixes option is false, which means the files will not be considered equal. However, if the option --xml-ignore-prefixes is set to true, then prefixes will be ignored and the files will be considered equal.
|
This option is applicable when comparing XML files. When set to true, the text content of XML nodes will be ignored for comparison. This is useful if you want to compare only the structure of two XML files, disregarding the actual node content. The default value is false.
|
This option is applicable when comparing XML files. Set this option to true if you want all XML attributes to be ordered before comparison. For example, let's assume that you want to compare the following two XML files:
In the listing above, the order of attributes is different in both files, although the attributes are the same. If you set the option --xml-order-by-attributes to true, the application will order attributes before comparison, and, consequently, the files will be reported as equal. The default value is false, meaning that files are not equal if the order of attributes is not the same.
|
This option is applicable when comparing XML files. Set this option to true if you want all XML elements to be ordered before comparison. For example, let's assume that you want to compare the following two XML files:
In the listing above, the left and right files contain exactly the same elements, only in a different order. If you set the option --xml-order-by-elements to true, the application will order all elements before comparison, and consequently, the files will be reported as equal. The default value is false, meaning that files are different if the order of elements is different.
|
This option is applicable when comparing XML files. There are instances where multiple elements have exactly the same name and attributes, but attribute values are different. To sort by specific attributes before comparing, set this option to a named list of attributes created in the Client Configuration File, in the [xml.orderby:<name_of_your_list>] group.
For example, let's assume that you want to compare the following two XML files:
In the listing above, the left and right files are not equal. However, if you ordered all phone elements by ext attribute, then the files would become equal. To make such comparisons possible, first modify the client configuration file as follows:
You can now run the diff command with the option --xml-order-by-attribute-list=mylist. When you do this, the application orders elements by ext attribute, and, as a result, the files are reported as equal. If the option --xml-order-by-attribute-list is not set, files such as the ones above would be reported as NOT equal.
As an alternative, to order by all attributes, set the option --xml-order-by-attributes=true instead of setting this option.
Note: If you set the --xml-order-by-attribute-list option, make sure to also set the --xml-order-by-elements=true.
On Windows, when DiffDog is installed on the same machine as DiffDog Server, you can set this option to a custom attribute list created in DiffDog. For more information about creating custom attribute lists with DiffDog, refer to the DiffDog documentation.
|
This option is applicable when comparing XML files. There are instances where multiple elements have exactly the same name and attributes; only the text of elements is different. Set this option to true if you want to order such elements by their inner text before comparison. For example, let's assume that you want to compare the following files:
In the listing above, the left and right files are not equal. However, if you set the option --xml-order-by-text to true, the application would order elements by their text, and, as a result, the files would be reported as equal. The default value is false, meaning that ordering of elements by text does not take place, and files such as the ones above are not equal.
Note: If you set the --xml-order-by-text option, make sure to also set the --xml-order-by-elements=true.
|
This option is applicable when comparing XML files. When set to true, then all entities in the document are resolved. Otherwise, the files are compared with the entities as is. By default, this option is false.
|
This option is applicable when comparing XML documents or directories containing XML documents. In case of directory comparisons, the option will apply only to XML files in that directory.
The option defines how whitespace characters should be treated for comparison. Whitespace characters are any of the following: space, tab, carriage return, and line feed. This option specifically affects whitespace characters that are inside element and attribute values. Whitespace characters that are outside attribute or element values are disregarded for comparison.
|
This option is applicable when comparing ZIP files. When set to true, ZIP files will be treated as directories instead of binary files. By default, this option is false.
|
Examples
To compare only local files or directories, supply them as arguments, which will be interpreted in the following index order. Two arguments (i) : left side, right side. Three arguments (ii): left side, middle, right side. While the --mode option is not mandatory, it is recommended to explicitly set it to either text, binary, or xml. In the first example above, it is set to text since two text files are being compared. In the second example, it is set to xml.
(i) diffdogcmdlclient diff file1.txt file2.txt --mode=text
(ii) diffdogcmdlclient diff file1.xml file2.xml file3.xml --mode=text
Alternatively, you can specify the files to compare through options instead of arguments. For example, the command below supplies two XML files via options—not arguments. Note the client/server locations of the files
(i) diffdogcmdlclient diff --client-left=file1.xml --client-right=file2.xml
(ii) diffdogcmdlclient diff --client-left=file1.xml --server-right=file2.xml --client-right=file3.xml
The command below compares a file on the client with a file on the server. The file on the server is expected to be in a folder that has an alias of public. Further, it is assumed that this alias has already been defined by an administrator on the server.
diffdogcmdlclient diff --client-left=file1.txt --server-right=file2.txt --mode=text --alias=public
To display a list of aliases defined on the server, run the aliases command. To save an alias as default, set the server-alias option in the Client Configuration File. This way, you will no longer need to specify an alias at the command line.