XDELTA3(1)

📦
version 3.2.2 · 4 versions
, in arch rolling

💅 xdelta3(1) — the VCDIFF baddie we deserve

okay bestie, buckle up, because this is xdelta3, section 1 of your manual, and she is a VCDIFF (RFC 3284) binary delta tool — literally the icon of "I only need to ship what changed." ✨

🦋 NAME

xdelta3 — VCDIFF (RFC 3284) binary delta tool. that's it, that's the vibe. 🎀

🌸 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

so, xdelta3 encodes and decodes binary differences using the VCDIFF format described by RFC 3284. give her a source file and a target file and encoding gives you back a compact delta. decoding takes that delta, slaps it onto the source, and reconstructs the target. no cap. 🫶

the default command is encode. the decode and encode commands are equivalent to -d and -e, respectively. unless you supply an output operand, xdelta3 writes to standard output. unless you supply an input operand, it reads standard input. the source is specified separately with -s. and heads up: standard input cannot be both the source and the input. pick a lane, babe. 💀

with no arguments, xdelta3 prints help when standard input is a terminal. when standard input is redirected, it remains an encoding filter. main character energy either way. 👑

⭐ COMMANDS

  • encode — encode the differences between the source and input (target) as a VCDIFF delta. this is the default command. her natural state. 💅
  • 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. the "what am I made of" command. 🪞
  • 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. full lore dump.
  • 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. glow-up of a delta, honestly.
  • 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
🚨 important vibe check: the VCDIFF inspection, recode, and merge commands are present only in builds compiled with VCDIFF tools. if she's not in the building, she's not in the building.

🧚 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. iykyk. 🍓
  • 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. she said "stdout" and she meant it.
  • -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. respect the boundaries until you're told otherwise. 🫶

✨ 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. (so like, two different knobs, bestie. don't mix them up.)
  • -c — write output to standard output, even if an output filename is also given. overrides everything. diva behaviour. 💅
  • -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. available only when external compression support is compiled in.
  • -h — print version and usage information. the command exits unsuccessfully after displaying this help, which is rude but that's literally what it does. 😭
  • -q — suppress non-error informational output. this resets any previous -v setting. quiet queen.
  • -v — increase verbosity. repeat for progressively more encoder statistics and diagnostics. this clears -q. the more -v, the more she talks. 💀
  • -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. type the whole number, bestie, no shortcuts. 🙈

  • -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. big windows, big feelings.
  • -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. no ceiling, no rules. 🌈

🔥 Compression and format options

  • -s source — use source as the file from which source-copy instructions are made. specify this option at most once. one source, one truth. 💜
  • -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. all the work, none of the mess. 🧚
  • -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. seven numbers, no notes. count them. 💀

🛡️ 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. no shortcuts, no skimming. 🫶

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. she looked at you and said "you're already that girl." 💅

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. important distinction, don't forget it. ✨

🗜️ 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. thoughtful queen. 🎀

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. also: external compression is unavailable on Windows. sad but true. 😭

🌈 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. slay. ✨
  • 1 — an error occurred, or help was displayed. (yes, help counts as 1. she's dramatic.)
  • 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

look at her go. 🦋

📜 STANDARDS

the delta format is VCDIFF as specified by RFC 3284. periodt. 🌸

🌈 SEE ALSO ✨

okay so if you're done here and you still want more reading (iconic behaviour honestly), go check these besties out:

and for the full lore:

  • Project documentation: the Xdelta website 🎀
  • Source and issue tracker: the Xdelta source repository 🦋

like, the source repo is right there, bestie — if you find a bug you can literally go tell them about it, no cap 💅

👑 AUTHOR 🌸

xdelta3 was written by Joshua MacDonald. absolute main character energy, we love to see it 🫶

the original manual page was written by Leo 'costela' Antunes for the Debian project, and it may be used by others — so yeah, that page is out here serving communal library realness 😌📚

and that's the whole page, bestie!! you made it to the end, i'm literally so proud of you 😭💖 go compress something iconic. periodt. ✨

Xdelta 3.2.2 🎀 October 7, 2026 🌈 — that's the version and the date this whole thing was stamped with, mwah 💋

📦 where this page comes from