jmacd/xdelta 3.2.2: VCDIFF delta compression for C applications and command-line users

Why jmacd/xdelta targets update transport rather than general archiving

Xdelta solves a specific transport problem: producing a delta between a known source file and a changed target, then applying that delta later to reconstruct the target. This model can reduce the amount of data sent when the destination already has an exact copy of the source. The intended audience includes engineers embedding delta handling in an application and operators using the command-line tool on systems where both the original file and generated delta can be managed correctly.

The repository also contains the historical Xdelta 1 implementation, but its role is separate from the current 3.2.x line. The README identifies Xdelta 1 as version 1.2.1 and gives it its own CMake build and installation documentation. Xdelta 3 is therefore the relevant choice when the required format is VCDIFF/RFC 3284 and the current library-oriented implementation is wanted. The presence of two maintained code trees adds a versioning decision for integrators because they must avoid building the wrong series for an existing data format or deployment.

Delta compression is not equivalent to making each file independently small. The documented workflow depends on using the delta with its corresponding source. Keeping that source synchronized across clients, servers, backup stores, or replicas becomes part of the application design. Xdelta does not remove the need to verify that the expected source is present and correct before applying an update.

Xdelta 3 VCDIFF data flow and repository architecture

Xdelta 3 is implemented as both a C library and a command-line tool. Its central interchange format is VCDIFF, identified in the README as RFC 3284. In a delta-based update workflow, the source and target roles matter: one file serves as the base, the delta describes the difference needed to reach the target, and the applying side combines the delta with an exact matching base.

The repository is divided into concrete areas. Current development is under `xdelta3/`, historical Xdelta 1 code is under `xdelta1/`, full documentation sources are under `site/`, and release automation is under `.github/workflows/`. The `site/` directory is a MkDocs and Material project that builds the published command-line reference, armor-mode documentation, and programming guide. This separation makes the library, historical implementation, documentation, and release machinery individually identifiable.

The README also links to documentation for armor mode. Release binaries for Xdelta 3 statically link liblzma, also identified as xz, and BLAKE3. The README does not state which compression options are compiled into a source build, so integrators should consult `xdelta3/README.md` before assuming that every packaged binary feature is available locally.

Building Xdelta 3 from source and running its tests

The repository provides a documented CMake build for Xdelta 3. This route is appropriate for engineers who need source inspection, platform integration, or a locally selected build type. The README says that static and shared library instructions, liblzma options, and regression testing details are in `xdelta3/README.md`.

Enter the current source directory, configure a Release build, compile it, and run the configured test suite with these exact commands:

cd xdelta3
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build

The configure command creates the `build` directory with the `Release` build type. The next command builds the configured targets, and `ctest --test-dir build` invokes the tests registered in that build tree. A successful command exit confirms that the respective operation completed, but the README excerpt does not provide the expected individual test names or output, so those details should not be inferred.

This is the first reproducible use documented by the repository: building the tool and running its tests. The excerpt links to the published command-line documentation for encoding and decoding operations but does not include those commands. It therefore would be unsafe to invent a file path, input flag, output flag, or source-selection argument here. The documentation at `https://jmacd.github.io/xdelta/commandline/` is the authoritative place to verify the exact operation for a particular delta workflow.

Release binaries, maintenance signals, and upgrade work

The repository is not archived, and its last push was on 2026-10-13. Recent releases include Xdelta 3.2.2 on 2026-10-09, Xdelta 3.2.1 on 2026-09-28, and Xdelta 1.2.1 on 2026-09-28. These are maintenance facts, not evidence that every upgrade is compatible.

Xdelta 3 releases include prebuilt binaries for Linux, macOS, and Windows across x86, x86-64, and ARM64, as stated in the README. Xdelta 1 offers Windows x86 and x86-64 packages. GitHub Release pages also carry source tarballs. The packaged Xdelta 3 binaries statically link liblzma and BLAKE3, which removes separate runtime library lookup for those bundled components in those binaries, but it does not remove architecture selection or format compatibility work.

Upgrades can involve both Xdelta 3 and Xdelta 1 because both lines have recent tagged releases. Integrators should pin the intended series rather than treating `main`, the 3.2.x release line, and the 1.2.1 tree as interchangeable. Release tags such as `vMAJOR.MINOR.PATCH` trigger the corresponding workflow, while branch naming uses conventions described in `RELEASING.md`. The README excerpt does not provide migration notes for patch releases, so it cannot confirm whether existing delta streams or API calls remain compatible across every update.

Apache 2.0 scope and the separate GPL implementation

The repository states that `main` and the 3.2.x series under `release3_2_apl` use Apache 2.0. It also lists older Xdelta 3 branches that were relicensed by the original author, including `release3_0_apl` and `release3_1_apl`. That licensing detail matters when an organization selects a source branch, because the branch choice can change which license text applies.

A separate original GPL-licensed implementation is located at `http://github.com/jmacd/xdelta-gpl`. This is a genuine alternative with a different stated licensing model. For software distribution decisions, the practical distinction is explicit in the README: the current Xdelta repository identifies Apache 2.0 coverage for its current lines, while it points GPL Xdelta to a separate repository. This comparison does not establish which code is faster or more suitable because the repository does not provide such a comparison.

The source distribution also needs closer inspection before adoption. The repository metadata labels the overall license as unknown, but the README clearly identifies Apache 2.0 for the current branches. Engineers should verify the exact branch, release archive, bundled library notices, and file-level headers that will be shipped. This is a licensing due-diligence point, not legal advice.

Delta compression limits and the full-copy alternative

The central limitation follows from the source-dependent design. A generated delta is meaningful only when the applying system has the matching source. If that base has been renamed, rebuilt, transformed, or replaced with a different version, applying the update can fail or cannot be considered valid without an explicit identity check in the surrounding system. Xdelta's documentation identifies the library and command-line roles, but the README excerpt does not document an automatic source-discovery, verification, or rollback mechanism.

The practical alternative is to transmit and store a complete compressed copy instead of a delta. A full copy does not depend on a synchronized base, while the delta approach does. Neither choice can be selected from the repository excerpt alone because it contains no size measurements, target-file profiles, or guidance for choosing between them. For files with little useful overlap, for recipients without the correct base, or for workflows requiring independent artifacts, the full copy remains the more direct option.

Another boundary is feature interpretation. The repository provides prebuilt Xdelta 3 binaries and source builds, but the excerpt does not document package-manager installation, distro-specific commands, rollback behavior, or a compatibility matrix for older deltas. Those omissions should be checked in `xdelta3/README.md`, the command-line documentation, and `RELEASING.md` before the tool becomes part of a distribution pipeline.

Editorial conclusion

Adopt Xdelta 3 when an application already has the exact source file to which a VCDIFF delta should be applied and can work within the C library or command-line interface. Do not choose it solely as a replacement for an unspecified general-purpose archive format without first verifying the target file identity, encoding options, application workflow, and Apache 2.0 licensing requirements. For jmacd/xdelta, checking that the selected executable or library matches the intended 3.2.x release is the first concrete decision.

Frequently asked questions

Official sources

1. Issues
2. jmacd/xdelta on GitHub
3. README
4. Releases