xpatch

A high-performance delta compression library with automatic algorithm selection.

Features

• Automatic Algorithm Selection: Analyzes changes and chooses the best compression strategy
• Excellent Compression: 99.4-99.8% average space savings on real-world code changes
• Fast Performance: 40-55 GB/s throughput for typical changes, <1 µs decoding
• Optional zstd Compression: Additional compression layer for complex changes
• Metadata Support: Embed version tags with zero overhead for values 0-15
• Multi-language: Also available for Python and Node.js

Installation

[dependencies]
xpatch = "0.3.0"

Requirements:

• Rust edition 2024 or later (Rust 1.92.0+)

Quick Start

use xpatch::delta;

fn main() {
    let base = b"Hello, World!";
    let new = b"Hello, Rust!";

    // Create delta
    let delta = delta::encode(0, base, new, true);

    // Apply delta
    let reconstructed = delta::decode(base, &delta).unwrap();
    assert_eq!(reconstructed, new);

    // Extract tag
    let tag = delta::get_tag(&delta).unwrap();
    println!("Compressed {} → {} bytes", new.len(), delta.len());
}

API

encode

pub fn encode(tag: usize, base_data: &[u8], new_data: &[u8], enable_zstd: bool) -> Vec<u8>

Creates a delta that transforms base_data into new_data.

• tag: User-defined metadata value (tags 0-15 use zero overhead)
• base_data: The original data
• new_data: The target data
• enable_zstd: Enable zstd compression for complex changes (slower but better compression)

Returns: Compact delta as bytes

decode

pub fn decode(base_data: &[u8], delta: &[u8]) -> Result<Vec<u8>, &'static str>

Applies a delta to reconstruct the new data.

• base_data: The original data the delta was created from
• delta: The encoded delta

Returns: Reconstructed data or error

get_tag

pub fn get_tag(delta: &[u8]) -> Result<usize, &'static str>

Extracts the tag value from a delta without decoding it.

Returns: Tag value or error

CLI Tool

Install the CLI tool with:

cargo install xpatch --features cli

Usage:

# Create a delta
xpatch encode base.txt new.txt -o patch.xp

# Apply a delta
xpatch decode base.txt patch.xp -o restored.txt

# Show delta info
xpatch info patch.xp

Performance

Tested on 1.2+ million real-world git changes:

• Code repositories: 2 bytes median (99.8% space saved)
• Documentation: 23 bytes median (99.4% space saved)
• Encoding: 10-208 µs depending on optimization mode
• Decoding: <1 µs (effectively instant)

How It Works

xpatch analyzes the change pattern and automatically selects the most efficient algorithm:

1. Change Analysis: Detects whether the change is a simple insertion, removal, or complex modification
2. Pattern Detection: Identifies repetitive patterns that can be compressed efficiently
3. Algorithm Selection: Tests multiple specialized algorithms and chooses the smallest output
4. Encoding: Creates a compact delta with algorithm metadata in the header

For complex changes, xpatch uses gdelta, a general-purpose delta compression algorithm, with optional zstd compression.

Examples

See the examples directory:

• basic.rs - Basic usage
• tags.rs - Using tags for version optimization

Run examples with:

cargo run --example basic
cargo run --example tags

Benchmarks

Run the comprehensive benchmark suite:

# Quick stress tests
cargo bench --bench stress

# Real-world git repository benchmarks
XPATCH_PRESET=tokio cargo bench --bench git_real_world

Related Projects

• xpatch repository - Multi-language bindings and documentation
• gdelta - General-purpose delta compression
• xpatch Demo Editor - Live demo

License

Dual-licensed under AGPL-3.0-or-later or commercial license. See LICENSE-AGPL.txt and LICENSE-COMMERCIAL.txt.

For commercial licensing inquiries: xpatch-commercial@alias.oseifert.ch