The ldif-diff Command-Line Tool

Compare the contents of two files containing LDIF entries. The output will be an LDIF file containing the add, delete, and modify change records needed to convert the data in the source LDIF file into the data in the target LDIF file.

This tool works best with small LDIF files because it reads the entire contents of the source and target LDIF files into memory so they can be quickly compared. If you encounter an out of memory error while running the tool, you may need to increase the amount of memory available to the JVM used to invoke it.

The amount of memory available to the JVM may be customized by invoking the JVM with the '-Xms' and '-Xmx' arguments (which specify the initial and maximum amounts of memory that it may use, respectively). These arguments should be immediately followed (without any intervening space) by an integer and a unit to specify the amount of memory that may be used. The unit may be either 'm' to indicate that the size is in megabytes, or 'g' to indicate that it is in gigabytes. For example, '-Xms512m' indicates that the JVM should be given an initial heap size of 512 megabytes, while '-Xmx2g' indicates that it should be given a maximum heap size of two gigabytes.

When invoking the ldif-diff tool with the shell script or batch file included as part of the LDAP SDK, you may use the 'JAVA_ARGS' environment variable to specify the arguments to use when invoking the JVM.

Usage

ldif-diff {arguments}

Source LDIF Arguments

• -s {path} / --sourceLDIF {path} — The path to the LDIF file containing the entries to use as the source data set. This argument must be specified, and the source LDIF file must exist. The LDIF file may optionally be gzip-compressed and/or passphrase-encrypted.
  The specified path must refer to a file that exists.
  
  
• --sourceEncryptionPassphraseFile {path} — The path to the file containing the passphrase used to encrypt the contents of the source LDIF file. If this argument is provided, the file must exist and must contain exactly one line that contains only the encryption passphrase. If the source LDIF file is encrypted but this argument is not provided, then the tool will interactively prompt for the passphrase.
  The specified path must refer to a file that exists.
  
  

Target LDIF Arguments

• -t {path} / --targetLDIF {path} — The path to the LDIF file containing the entries to use as the target data set. This argument must be specified, and the target LDIF file must exist. The LDIF file may optionally be gzip-compressed and/or passphrase-encrypted.
  The specified path must refer to a file that exists.
  
  
• --targetEncryptionPassphraseFile {path} — The path to the file containing the passphrase used to encrypt the contents of the target LDIF file. If this argument is provided, the file must exist and must contain exactly one line that contains only the encryption passphrase. If the target LDIF file is encrypted but this argument is not provided, then the tool will interactively prompt for the passphrase.
  The specified path must refer to a file that exists.
  
  

Output LDIF Arguments

• -o {path} / --outputLDIF {path} — The path to the LDIF file to which the resulting LDIF add, delete, and modify change records will be written. If this file already exists, then the new LDIF records will be appended to it unless the '--overwriteExisting' argument is provided. If this file does not exist, then the parent directory must exist. If this argument is not provided, then the changes will be written to standard output.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --compressOutput — GZIP-compress the data as it is written to the output file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --encryptOutput — Encrypt the data as it is written to the output file. If the '--outputEncryptionPassphraseFile' argument is provided, then the passphrase contained in that file will be used to encrypt the output. Otherwise, the tool will interactively prompt for the passphrase.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --outputEncryptionPassphraseFile {path} — The path to a file containing the passphrase to use to encrypt the contents of the output file. If this argument is provided, then the file must exist, and it must contain exactly one line comprised entirely of the encryption passphrase.
  The specified path must refer to a file that exists.
  
  
• -O / --overwriteExistingOutputLDIF — Overwrite the output file if it already exists, rather than appending to it. This argument must be provided if the output file already exists and either of the '--compressOutput' or '--encryptOutput' arguments is provided.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Content Arguments

• --changeType {add|delete|modify} — The type of change to include in the output. Allowed values are 'add' (to indicate that the output should include LDIF add change records for all entries that are present in the target LDIF but not in the source), 'delete' (to indicate that the output should include LDIF delete change records for all entries that are present in the source LDIF but not in the target), and 'modify' (to indicate that the output should include LDIF modify change records for all entries that are present in both the source and target LDIF files but that differ between the two versions). This argument may be provided multiple times to specify multiple change types. By default, all change types will be included.
  A provided value should be one of the following: 'add', 'modify', 'delete'.
  
  
• --includeFilter {filter} — Only include changes to entries that match the given filter (either before or after the change). This argument may be provided multiple times to specify multiple include filters (in which case an entry will only be included if it matches at least one of the provided filters).
  A provided value must be able to be parsed as an LDAP search filter as described in RFC 4515.
  
  
• --excludeFilter {filter} — Exclude changes to entries that match the given filter (either before or after the change). This argument may be provided multiple times to specify multiple exclude filters (in which case an entry will be excluded if it matches any of the provided filters).
  A provided value must be able to be parsed as an LDAP search filter as described in RFC 4515.
  
  
• --includeAttribute {attributeName} — Only include the specified attribute in the change records that are written. Changes that do not affect the specified attribute will be omitted from the results. This argument may be provided multiple times to specify multiple include attributes.
  
  
• --excludeAttribute {attributeName} — Exclude the specified attribute from the change records that are written. Changes that affect only the specified attribute will be omitted from the results. This argument may be provided multiple times to specify multiple exclude attributes.
  
  
• -i / --includeOperationalAttributes — Include operational attributes in the output file, in both add and modify change records. By default, only user attributes will be included.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -e / --excludeNoUserModificationAttributes — Exclude operational attributes declared with the NO-USER-MODIFICATION constraint. This argument is only applicable if the '--includeOperationalAttributes' argument is provided.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --nonReversibleModifications — Generate modify change records in non-reversible form, in which attribute differences are written with the 'replace' modification type. By default, modifications will be generated in reversible form, with delete modifications to remove existing values that are no longer included and add modifications to insert new values. Using reversible form is generally considered safer, as attempts to apply the modifications are more likely to fail if the entry has been updated. Modifications generated in non-reversible form are more likely to succeed when applied, but at a greater risk of losing changes that have been processed since the LDIF files were generated.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --stripTrailingSpaces — Strip off any illegal trailing spaces identified in LDIF entries rather than rejecting those entries.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Additional Arguments

• -S / --singleValueChanges — Generate a separate modify change record for each attribute value that is to be removed from or added to the target entry. By default, all modifications to an entry will be provided in a single modify change record. If a separate modify change record is generated for each attribute value, it may be easier to apply changes if the data set has changed since the LDIF files were generated (by instructing the tool that is applying changes to ignore failures).
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --schemaPath {path} — The path to an LDIF file (or a directory containing multiple LDIF files) with the schema definitions to use during processing. This argument may be used multiple times to specify multiple schema paths. If this argument is ot provided, the LDAP SDK's default standard schema will be used.
  The specified path must refer to a file that exists.
  
  
• --byteForByte — Use byte-for-byte comparisons when identifying differences between entries. By default, the tool will use schema-aware comparison, and some types of differences (e.g., differences in capitalization in the values of attributes with case-ignore matching) may be ignored. With byte-for-byte comparison, any difference at all will be considered significant.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --interactive — Launch the tool in interactive mode.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -H / --help — Display usage information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --help-debug — Display usage information for debug logging.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --enable-debug-logging — Enables debug logging for the tool.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-level {level} — The debug log level to use for the tool. Allowed values include 'off', 'severe', 'warning', 'info', 'fine', 'finer', and 'finest'. If this is not specified, a default level of 'severe' will be used.
  
  
• --debug-log-category {category} — The message categories to include in the debug log output. Allowed values include 'asn1', 'connect', 'exception', 'ldap', 'connectionpool', 'ldif', 'monitor', 'codingerror', and 'other'. This argument may be provided multiple times to indicate that multiple categories should be included. If this is not specified, then all categories will be included.
  
  
• --include-debug-stack-traces — Indicates that debug log messages should include a stack trace with the code location from which each debug message originated.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --use-multi-line-debug-messages — Indicates that debug log messages (which will be JSON objects) should be written as multi-line strings rather than single-line strings.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-file {path} — The path to the debug log file to be written. If this is not specified, a default path of 'ldif-diff.debug' will be used.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• -V / --version — Display version information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --propertiesFilePath {path} — The path to a properties file used to specify default values for arguments not supplied on the command line.
  The specified path must refer to a file that exists.
  
  
• --generatePropertiesFile {path} — Write an empty properties file that may be used to specify default values for arguments.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --noPropertiesFile — Do not obtain any argument values from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressPropertiesFileComment — Suppress output listing the arguments obtained from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Dependent Argument Sets

• If the --compressOutput argument is provided, then the --outputLDIF argument must also be provided.
• If the --encryptOutput argument is provided, then the --outputLDIF argument must also be provided.
• If the --outputEncryptionPassphraseFile argument is provided, then the --outputLDIF argument must also be provided.
• If the --overwriteExistingOutputLDIF argument is provided, then the --outputLDIF argument must also be provided.
• If the --outputEncryptionPassphraseFile argument is provided, then the --encryptOutput argument must also be provided.
• If the --excludeNoUserModificationAttributes argument is provided, then the --includeOperationalAttributes argument must also be provided.

Exclusive Argument Sets

• The following arguments cannot be used together: --includeAttribute, --excludeAttribute
• The following arguments cannot be used together: --includeAttribute, --includeOperationalAttributes
• The following arguments cannot be used together: --includeFilter, --excludeFilter
• The following arguments cannot be used together: --nonReversibleModifications, --singleValueChanges
• The following arguments cannot be used together: --schemaPath, --byteForByte
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

Examples

• Identify the changes needed to transform the set of entries contained in the 'actual.ldif' file into the set of entries contained in the 'desired.ldif' file. Operational attributes will be ignored, and modifications will be presented in reversible form.

    ldif-diff --sourceLDIF actual.ldif --targetLDIF desired.ldif \
         --outputLDIF diff.ldif

• Identify the changes needed to transform the set of entries contained in the 'actual.ldif' file into the set of entries contained in the 'desired.ldif' file. Operational attributes not declared with the NO-USER-MODIFICATION will be included, and modifications will be presented in non-reversible form.

    ldif-diff --sourceLDIF actual.ldif --targetLDIF desired.ldif \
         --outputLDIF diff.ldif --includeOperationalAttributes \
         --excludeNoUserModificationAttributes --nonReversibleModifications