Altova DiffDog Server 2023 

The diff 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 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 (not directories). The files or directories to be compared can be on a machine where DiffDog Client runs or on the remote machine where DiffDog Server runs. A combined approach (comparison of local files or directories with remote ones) is also possible.

 

Syntax

DiffDogCmdlClient diff [options] {path path [path]}

 

On Linux, use an all-lowercase to call the executable. In addition, on Linux and macOS, you might need to add the prefix "./" before the name of the executable when calling it from the current directory of the command shell.

 

This command can also be called using the compare alias. You can use compare and diff interchangeably.

 

Arguments

path

A path may be a file or directory path, or a URL path in the format http://server/segment.

 

Supplying paths as arguments is just one of the two ways to pass input paths to the diff command. The second way to supply paths is by setting the options --client-left, --client-right, or --server-left, --server-right. Use the second approach if DiffDog Client does not run on the same machine as DiffDog Server.

 

In other words, if you set the options --client-left, --client-right, or --server-left, --server-right, then no paths must be specified as arguments. Otherwise, two paths exactly must be supplied as argument. (To perform a three-way comparison, three paths can be specified as arguments.)

 

Options

The options applicable to the diff command are listed below.

 

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 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.

 

 

--alias, --a

If the server administrator has restricted access to server paths for security reasons, you can no longer run comparisons that refer server file paths directly, see also Restricting Access to Server Paths. Instead, you need to specify the name of an alias by means of the --alias option.

 

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.

 

--config, --c

This option specifies the path to a client configuration file. For more information, see Client Configuration File.

 

If you do not set the --c option, the DiffDog Command Line Client executable attempts to read the client configuration file from the same directory. If there is no configuration file in the same directory as the executable, the default values as described in the command line help and this documentation apply.

 

--client-left, --cl

This option specifies the left side of the comparison (must be a path to a local file or directory).

 

--client-middle, --cm

This option is applicable in a 3-way comparison. It specifies the local path to the "middle" file (also known as the "common ancestor").

 

--client-right, --cr

This option specifies the right side of the comparison (must be a path to a local file or directory).

 

--dir-compare-contents, --dc

This option specifies if directory comparison should compare file contents in addition to any other options that might be set separately (such as file size and modification date). When this option is false, the comparison ignores file contents (this will result in a faster, though less accurate, comparison). By default, this option is false.

 

--directory-filter, --df

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], use the following syntax to set the filter at the command line:

 

--directory-filter=svn

 

On Windows, when DiffDog is installed on the same machine as DiffDog Server, you can specify as option value 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 the following syntax:

 

--directory-filter="No SVN directories"

 

To view or create a directory filter in DiffDog:

 

1.On the Tools menu, click DiffDog Options.

2.Click the Directory Comparison tab.

 

For more information about creating directory filters with DiffDog, refer to DiffDog documentation (https://www.altova.com/documentation).

 

If the filter cannot be found, an error occurs and no comparison takes place.

 

--dir-compare-mod-times-ignore-seconds, --di

This option is 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.

 

--dir-ignore-case, --dic

This option is applicable for directory comparisons. By default, this value is false, which means that a case sensitive comparison is performed. For example, the directories below would be treated as not equal (since the file name is different in the right directory).

 

source/

|-- ReadMe.txt

source/

|-- readme.txt

 

To ignore the case and perform a case-insensitive comparison, set this option to true. In this case, a directory called "SomeDir" would be equal to "somedir", or a file "file.TXT" would be equal to "file.txt".

 

--dir-compare-sizes, --ds

This option is applicable for directory comparisons. When set to true, it specifies that directory comparison should compare files by size. Otherwise, this comparison criterion is ignored. By default, this option is false.

 

--dir-compare-mod-times, --dt

This option is applicable for directory comparisons. When set to true, it specifies that directory comparison should compare files within a directory by modification time. Otherwise, this comparison criterion is ignored. By default, this option is false.

 

--doc-format-bold, --dfb

This option is applicable for comparison of Word documents. Valid values:

 

true

Take bold formatting into account during comparison.

false

(Default) Ignore bold formatting.

 

--doc-format-font-color, --dfc

This option is applicable for comparison of Word documents. Valid values:

 

true

Take font color into account during comparison.

false

(Default) Ignore font color.

 

--doc-format-font-name, --dff

This option is applicable for comparison of Word documents. Valid values:

 

true

Take font name into account during comparison.

false

(Default) Ignore font name.

 

--doc-format-font-size, --dfs

This option is applicable for comparison of Word documents. Valid values:

 

true

Take font size into account during comparison.

false

(Default) Ignore font size.

 

--doc-format-italic, --dfi

This option is applicable for comparison of Word documents. Valid values:

 

true

Take italic formatting into account during comparison.

false

(Default) Ignore italic formatting.

 

--doc-format-underline, --dfu

This option is applicable for comparison of Word documents. Valid values:

 

true

Take underline formatting into account during comparison.

false

(Default) Ignore underline formatting.

 

--doc-ignore-blank-lines, --dib

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. Valid values:

 

true

(Default) Ignore blank lines.

false

Take blank lines into account during comparison.

 

--doc-ignore-case, --doc

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. Valid values:

 

true

Perform a case-insensitive comparison (for example, "A" and "a" are treated as equal).

false

(Default) Perform a case-sensitive comparison (for example, "A" and "a" are not treated as equal).

 

--doc-whitespace-mode, --dws

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.

 

asis

(Default) Treat whitespace characters as is (that is, do not apply normalization or stripping). This means that whitespace characters are always relevant for comparison.

normalize

Text A is equal to Text B if, after normalization, characters in Text A correspond to those in Text B. “Normalization” means that multiple consecutive occurrences of whitespace characters are replaced by a single space character. In addition, the leading and trailing whitespace characters are trimmed for each line of text.

strip

Text A is considered equal to Text B if, after stripping whitespace characters, characters in Text A correspond to those in Text B. In other words, any whitespace characters are stripped from the text and considered not relevant for comparison.

 

--ignore-blank-lines

This option specifies if blank lines should be ignored in comparison. Valid values are true and false. By default, this 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.

 

--ignore-case

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. Valid values:

 

true

Perform a case-insensitive comparison (for example, "A" and "a" are treated as equal).

false

(Default) Perform a case-sensitive comparison (for example, "A" and "a" are not treated as equal).

 

--loglevel, --L

Sets the reporting level for information, warning, and error messages. Valid values:

 

none

Suppress all logging.

info

Report information, warning, and error messages.

warning

Report error and warning messages.

error

(Default) Report only error messages.

 

--mode, --m

This option specifies the comparison type to be performed. Valid values:

 

auto

(Default) Let the application determine if the supplied arguments are files or directories and set the comparison mode automatically based on file extension. For example, if files are detected to be XML, then an XML comparison is performed. You can always view or change the default mapping between specific file extensions and comparison modes, see Client Configuration File.

binary

Treat files as binary.

doc

Treat files as Microsoft Word documents.

text

Treat files as text.

xml

Treat files as XML.

 

--output-file, --o

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.

 

--output-mode, --om

This option lets you specify the format in which the comparison output is to be created (text or XML). Valid values:

 

auto

(Default) Let the application decide.

text

Write output file as text.

 

Note:The option --output-mode=text is not supported when comparing XML files or Word documents.

xml

Write output file as XML.

 

--port

This option specifies the port on which DiffDog Server listens for requests. Setting this option is meaningful if DiffDog Server runs on a port other than the default 29800. As an alternative to setting this option at the command line, you can set it in the Client Configuration File. Note that, if you set this value at the command line, it takes precedence over the one defined in the configuration file.

 

--quiet, --q

Prevents the standard output from being displayed at the command line. Valid values:

 

true

Do not display standard output in the terminal window.

false

(Default) Display standard output in the terminal window.

 

--server-output-file, --s

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.

 

--server

This option specifies the server address on which DiffDog Server listens for requests. Setting this option is meaningful if DiffDog Server runs on a server other than the default localhost. As an alternative to setting this option at the command line, you can set it in the Client Configuration File. Note that, if you set this value at the command line, it takes precedence over the one defined in the configuration file.

 

--server-left, --sl

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).

 

--server-middle, --sm

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.

 

--server-right, --sr

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).

 

--text-ignore-case, --ic

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. Valid values:

 

true

Perform a case-insensitive comparison (for example, "A" and "a" are treated as equal).

false

(Default) Perform a case-sensitive comparison (for example, "A" and "a" are not treated as equal).

 

--text-ignore-blank-lines, --ib

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 if blank lines should be ignored in comparison, when comparing text files. Valid values are true and false. By default, this value is false.

 

--text-whitespace-mode, --tws

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.

 

asis

(Default) Treat whitespace characters as is (that is, do not apply normalization or stripping). This means that whitespace characters are always relevant for comparison.

normalize

Text A is equal to Text B if, after normalization, characters in Text A correspond to those in Text B. “Normalization” means that multiple consecutive occurrences of whitespace characters are replaced by a single space character. In addition, the leading and trailing whitespace characters are trimmed for each line of text.

strip

Text A is considered equal to Text B if, after stripping whitespace characters, characters in Text A correspond to those in Text B. In other words, any whitespace characters are stripped from the text and considered not relevant for comparison.

 

--whitespace-mode, --ws

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.

 

asis

(Default) Treat whitespace characters as is (that is, do not apply normalization or stripping). This means that whitespace characters are always relevant for comparison.

normalize

Text A is equal to Text B if, after normalization, characters in Text A correspond to those in Text B. “Normalization” means that multiple consecutive occurrences of whitespace characters are replaced by a single space character. In addition, the leading and trailing whitespace characters are trimmed for each line of text.

strip

Text A is considered equal to Text B if, after stripping whitespace characters, characters in Text A correspond to those in Text B. In other words, any whitespace characters are stripped from the text and considered not relevant for comparison.

 

If the compared files are XML, normalization and stripping affects whitespace characters that are inside attribute or element values. Other whitespace characters are disregarded.

 

--xml-filter, --xf

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], use the following syntax to set the filter at the command line:

 

--xml-filter=ignore-abc-elems

 

On Windows, when DiffDog is installed on the same machine as DiffDog Server, you can specify as option value any XML filter created with DiffDog. To view or define an XML filter in DiffDog, take the following steps:

 

1.On the Tools menu, click Comparison Options.

2.Click the XML tab.

3.Locate the option Filter out specific elements/attributes, and the click the Ellipsis dds_ic_ellipsis button .

 

For more information about creating XML filters with DiffDog, refer to DiffDog documentation (https://www.altova.com/documentation).

 

If the filter cannot be found, an error occurs and no comparison takes place.

 

--xml-ignore-case-in-names, --xicin

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 identifier names will be performed. For example, let's assume that you want to compare the following XML files:

 

<book ID="1"/>

<book id="1"/>

 

In the listing above, the attribute ID is uppercase in the left file and lowercase in the right file. If --xml-ignore-case-in-names=true, case is ignored, so the files above are treated as equal. By default, this option is false, which means files such as the ones above are not equal.

 

--xml-ignore-case-in-text, --xicit

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 non-markup text will be performed. For example, let's assume that you want to compare the following XML files:

 

<book hardcover="yes">
  <genre>fiction</genre>
</book>

<book hardcover="Yes">
  <genre>Fiction</genre>
</book>

 

In the listing above, the value of attribute hardcover is lowercase in the left file and capitalized in the right file. The same is true for the value of the genre element. To treat these two files as equal, set --xml-ignore-case-in-text=true. By default, this option is false, which means files such as the ones above are not equal.

 

--xml-ignore-markup-attributes, --xima

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML attributes when comparing.

false

(Default) Take XML attributes into account when comparing.

 

--xml-ignore-markup-comments, --ximc

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML comments when comparing.

false

(Default) Take XML comments into account when comparing.

 

--xml-ignore-markup-cdata, --ximcd

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML character data (CDATA) when comparing.

false

(Default) Take XML CDATA into account when comparing.

 

--xml-ignore-markup-doctype, --ximd

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML DOCTYPE declaration when comparing.

false

(Default) Take XML DOCTYPE declaration into account when comparing.

 

--xml-ignore-markup-processing-instructions, --ximpi

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML processing instructions when comparing.

false

(Default) Take XML processing instructions into account when comparing.

 

--xml-ignore-markup-xml, --ximx

This option is applicable when comparing XML files. Valid values:

 

true

Ignore XML declarations when comparing.

false

(Default) Take XML declarations into account when comparing.

 

--xml-ignore-namespace, --xins

This option is applicable when comparing XML files. When set to true, XML namespaces will be ignored. By default, this option is false.

 

--xml-ignore-prefixes, --xip

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.

 

<left:table>
  <left:tr>
    <left:td>Name</left:td>
  </left:tr>
</left:table>

<right:table>
  <right:tr>
    <right:td>Name</right:td>
  </right:tr>
</right:table>

 

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.

 

--xml-ignore-text, --xit

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. By default, this option is false.

 

--xml-order-by-attributes, --xoba

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:

 

<book author="Franz Kafka" title="The Metamorphosis"/>

<book title="The Metamorphosis" author="Franz Kafka"/>

 

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.

 

--xml-order-by-elements, --xobe

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:

 

<book>
  <author>Franz Kafka</author>
  <title>The Metamorphosis</title>  
</book>

<book>  
  <title>The Metamorphosis</title>
  <author>Franz Kafka</author>
</book>

 

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.

 

--xml-order-by-attribute-list, --xobl

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:

 

<data>
  <phone type="work" ext="111"/>
  <phone type="work" ext="222"/>
  <phone type="work" ext="333"/>
</data>

<data>
  <phone type="work" ext="333"/>
  <phone type="work" ext="111"/>
  <phone type="work" ext="222"/>
</data>

 

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:

 

;; an example attributes list
[xml.orderby:mylist]
attributes = ext

 

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. To view or create a custom attribute list in DiffDog:

 

1.On the Tools menu, click Comparison Options.

2.Click the XML tab.

3.Select the Ignore order of child nodes check box.

4.Click Specific attributes, and then click the Ellipsis dds_ic_ellipsis button.

 

For more information about creating custom attribute lists with DiffDog, refer to DiffDog documentation (https://www.altova.com/documentation).

 

--xml-order-by-text, --xobt

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:

 

<data>
  <phone type="mobile">111</phone>
  <phone type="mobile">222</phone>  
</data>

<data>
  <phone type="mobile">222</phone>
  <phone type="mobile">111</phone>
</data>

 

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.

 

--xml-resolve-entities, --xre

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.

 

--xml-whitespace-mode, --xws

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.

 

asis

(Default) Treat whitespace characters as is (that is, do not apply normalization or stripping). This means that whitespace characters are always relevant for comparison.

normalize

Text A is equal to Text B if, after normalization, characters in Text A correspond to those in Text B. “Normalization” means that multiple consecutive occurrences of whitespace characters are replaced by a single space character. In addition, the leading and trailing whitespace characters are trimmed for each line of text.

strip

Text A is considered equal to Text B if, after stripping whitespace characters, characters in Text A correspond to those in Text B. In other words, any whitespace characters are stripped from the text and considered not relevant for comparison.

 

--zip-as-dir, --zd

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

See Running Comparisons.

© 2016-2022 Altova GmbH