xdelta3(1)

NAME

xdelta3 - VCDIFF (RFC 3284) binary delta tool

SYNOPSIS

xdelta3 [command] [options] [input [output]]

xdelta3 -e -s source target delta

xdelta3 -d -s source delta target

xdelta3 merge -m delta1 [-m delta2 ...] final-delta [output]

DESCRIPTION

xdelta3 encodes and decodes binary differences using the VCDIFF format described by RFC 3284. Given a source file and a target file, encoding produces a compact delta. Decoding applies that delta to the source to reconstruct the target.

The default command is encode. The decode and encode commands are equivalent to -d and -e, respectively. Unless an output operand is supplied, xdelta3 writes to standard output. Unless an input operand is supplied, it reads standard input. The source is specified separately with -s. Standard input cannot be both the source and the input.

With no arguments, xdelta3 prints help when standard input is a terminal. When standard input is redirected, it remains an encoding filter.

COMMANDS

encode: Encode the differences between the source and input (target) as a VCDIFF delta. This is the default command.

decode: Decode a VCDIFF delta, using the source when the delta contains source-copy instructions.

config: Print compile-time feature flags, default buffer sizes, and type sizes.

test: Run the built-in test suite. This command is present only in builds compiled with regression-test support.

printdelta: Print a human-readable description of the file header and every VCDIFF window and instruction.

printhdr: Print information from the VCDIFF file header and first window.

printhdrs: Print the file header and summary information for every VCDIFF window.

recode: Read a VCDIFF delta and write an equivalent delta using the selected application-header and secondary-compression settings. No source file is required.

merge: Collapse a chain of VCDIFF deltas into one delta. Supply every delta except the last with -m, in source-to-target order; the ordinary input operand is the last delta. For example, deltas from version 1 to 2, 2 to 3, and 3 to 4 produce a merged delta from version 1 to 4:

xdelta3 merge -m 1-2.vcdiff -m 2-3.vcdiff 3-4.vcdiff 1-4.vcdiff

The VCDIFF inspection, recode, and merge commands are present only in builds compiled with VCDIFF tools.

OPERANDS AND FILE SELECTION

input: The target while encoding, or the VCDIFF delta while decoding, inspecting, or recoding. A - operand means standard input. If omitted, standard input is used.

output: The VCDIFF delta while encoding or recoding, or the reconstructed target while decoding. If omitted, the application header may provide an output filename; otherwise standard output is used. The -c option always selects standard output and overrides this operand.

-s source: The source file used to encode or decode. During decode, when -s is omitted, xdelta3 may use the source filename stored in the application header.

By default, xdelta3 refuses to replace an existing output file. Use -f to allow replacement.

OPTIONS

Standard options

-0 through -9: Select the encoder's string-matching compression level. -0 disables string matching, -1 is fastest, and -9 uses the most thorough matching and the most memory. The default is -3. These levels are separate from secondary compression selected by -S.

-c: Write output to standard output, even if an output filename is also given.

-d: Decode. Equivalent to the decode command.

-e: Encode. Equivalent to the encode command and the default in encoder-enabled builds.

-f: Force replacement of an existing output file. While decoding, also tolerate trailing data after a valid VCDIFF stream.

-F: Pass the force option to an external compression or decompression subprocess. This option is available only when external compression support is compiled in.

-h: Print version and usage information. The command exits unsuccessfully after displaying help.

-q: Suppress non-error informational output. This resets any previous -v setting.

-v: Increase verbosity. Repeat for progressively more encoder statistics and diagnostics. This clears -q.

-V: Print version and license information and exit.

Memory options

All values are decimal byte or entry counts; suffixes such as K or M are not accepted.

-B bytes: Set the source window size. The default is 64 MiB and the minimum is 16 KiB. Larger values let the encoder find source matches across larger shifts. During decode this controls the source block cache.

-W bytes: Set the input window size. The default is 8 MiB and the minimum is 16 KiB. The build's upper limit is reported by xdelta3 config. Larger windows may improve compression but increase encoder and decoder memory.

-P entries: Set the target duplicate-position table size. The default is 262144 entries. This table finds copies in previously seen target data and is normally no larger than -W.

-I entries: Set the encoder instruction buffer size. The default is 32768 entries. A value of 0 makes the buffer unlimited.

Compression and format options

-s source: Use source as the file from which source-copy instructions are made. Specify this option at most once.

-S type: Select secondary compression. type is lzma, djw, or fgk when that coder was compiled in. LZMA is selected by default when available; otherwise secondary compression is off by default. The djw name may be followed by a tuning level from 0 through 9. Use -S none or -S= to disable secondary compression explicitly. This provides the broadest compatibility because LZMA-compressed deltas require a decoder built with liblzma. Run xdelta3 config to see which coders are present.

-N: Disable small string-matching compression. The encoder then emits literal data and source copies without searching for copies in the target.

-D: Disable automatic external decompression of recognized inputs during encode and decode.

-R: Disable automatic external recompression of decoded output.

-G: Do not record the detected external-compression level in the application header while encoding. This emits a legacy compressor descriptor that older xdelta3 versions can use for recompression.

-n: Do not write target-window Adler-32 checksums while encoding, and do not verify them while decoding.

-a: Disable armor mode. Armor is whole-file BLAKE3 source and target verification and is enabled by default in builds that include it. See ARMOR MODE below.

-A appheader: Store appheader as application-specific data in the VCDIFF file header. With no explicit value, xdelta3 generates an application header containing source and target filenames and any external-compression descriptors. Use -A= to disable the application header.

-J: Check or compute the operation without writing output. Input is still fully processed, including checksum and armor verification.

-m delta: Add delta to the beginning of the merge command's ordered delta chain. Repeat for all but the final input delta.

-C values: Set the encoder's internal soft string-matcher configuration. This advanced, unstable option requires seven nonnegative, comma-separated integer values: large look, large step, small look, small chain, small lazy chain, maximum lazy match, and long-enough match.

ARMOR MODE

When compiled with armor support, xdelta3 enables whole-file verification by default. The encoder stores BLAKE3 digests of the logical source and target content in the application header. It must therefore be able to seek and read both files in full.

The decoder verifies a seekable source before applying the delta and verifies the reconstructed target afterward. If the source is not seekable, xdelta3 warns that it cannot verify it and continues. If the supplied source already matches the recorded target digest, xdelta3 reports already up to date and exits with status 2 without applying the patch.

Use -a to disable armor and restore the legacy application-header format and non-seekable encoding behavior. The merge command verifies an armored chain when every input delta is armored. Digests cover logical content after external decompression, not compressed on-disk bytes.

EXTERNAL COMPRESSION

On supported systems, xdelta3 recognizes common externally compressed inputs, including gzip, bzip2, xz, and compress streams. It invokes the corresponding external decompressor before processing and records a descriptor in the application header so decode can recompress the output.

Recompression is not guaranteed to reproduce byte-identical compressed data because compressor versions and settings differ. Xdelta3 records the bzip2 level exactly and makes a best-effort gzip or xz level guess. Use -D to process compressed bytes directly, -R to leave decoded output uncompressed, or the compressor's environment variable (for example, GZIP=-9) to control recompression. External compression is unavailable on Windows.

ENVIRONMENT

XDELTA

Whitespace-separated arguments prepended to the command line. This is useful when another program invokes xdelta3 as a filter. For example:

XDELTA="-s source-x.y.tar.gz" \
tar --use-compress-program=xdelta3 -cf \
    target-x.z.tar.gz.vcdiff target-x.y/

EXIT STATUS

0: The operation completed successfully.

1: An error occurred, or help was displayed.

2: An armored delta was not applied because the supplied source already matches the recorded target ("already up to date").

EXAMPLES

Create a delta:

xdelta3 -e -s old-file new-file update.vcdiff

Apply it:

xdelta3 -d -s old-file update.vcdiff reconstructed-file

Encode through standard input and output with LZMA secondary compression:

xdelta3 -S lzma -s old-file < new-file > update.vcdiff

Verify that a delta decodes successfully without creating output:

xdelta3 -J -d -s old-file update.vcdiff

Inspect all windows in a delta:

xdelta3 printhdrs update.vcdiff

STANDARDS

The delta format is VCDIFF as specified by RFC 3284.

AUTHOR

xdelta3 was written by Joshua MacDonald.

The original manual page was written by Leo 'costela' Antunes for the Debian project and may be used by others.