--- name: "xdelta3" section: "1" platform: "linux" package: "xdelta3" version: "3.2.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/xdelta3" --- # xdelta3(1) VCDIFF (RFC 3284) binary delta tool ## 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. ## SEE ALSO [**bzip2**(1)](/bzip2/1.md), [**gzip**(1)](/gzip/1.md), [**xz**(1)](/xz/1.md) Project documentation: Xdelta website ⟨https://jmacd.github.io/xdelta/⟩ Source and issue tracker: Xdelta source repository ⟨https://github.com/jmacd/xdelta⟩ ## 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.