Xdelta3w - Custom App for Xdelta3 Patching

[BLACKFIRE69]

xdelta3w v0.2
Custom Console App for Xdelta3 Patching
Windows x86 (runs on x64) · single exe + wrapper DLL · by BLACKFIRE69

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━

▌ OVERVIEW
xdelta3w is a Windows console wrapper for xdelta3_wrapper.dll that exposes xdelta3 encode and decode operations through a clean command-line interface. Two operating modes:

• Single-file mode — encode or decode one file at a time, with a full real-time progress bar showing speed and ETA.
• Multi-file (batch) mode — encode or decode an entire directory tree in one pass, with an overall batch progress bar spanning all files and a summary report on completion.

▌ TECHNICAL SPECIFICATIONS

• Tool version — v0.2
• Author — BLACKFIRE69
• xdelta3 version — v3.0.11 / v3.1.0 (both supported via wrapper DLL)
• DLL — xdelta3_wrapper.dll
• Platform — Windows x86 (32-bit exe, runs on 64-bit Windows)

▌ CLI REFERENCE

; Single-file
xdelta3w -e -s MODIFIED [-f] [-q] [-1..-9] [-B KB] [-W KB] [-E KB]
            [-S TYPE] [-SD] [-SI] [-SA] [-n] [-N] [-G] [-I SIZE] [-P SIZE] ORIGINAL PATCH
xdelta3w -d -s MODIFIED [-f] [-q] [-B KB] [-W KB] [-E KB] [-n] PATCH OUTPUT
xdelta3w -V | -h

; Multi-file  (-s points to a directory)
xdelta3w -e -s MOD_DIR [-m PATTERN] [-r] [-x EXT] [-f] [-q] [-1..-9]
            [-B KB] [-W KB] [-E KB] [-S TYPE] [-SD] [-SI] [-SA] [-n] [-N]
            [-G] [-I SIZE] [-P SIZE] ORIG_DIR PATCH_DIR
xdelta3w -d -s MOD_DIR [-m PATTERN] [-r] [-x EXT] [-f] [-q] [-B KB]
            [-W KB] [-E KB] [-n] PATCH_DIR OUTPUT_DIR

▌ OPTIONS

Modes
  -e          Encode: create delta patch  (MODIFIED + ORIGINAL -> PATCH)
  -d          Decode: apply delta patch   (MODIFIED + PATCH    -> OUTPUT)
  -V          Print DLL version and exit
  -h          Print help and exit

Required
  -s PATH     Modified file or directory (the "bad" / changed version).
              In decode, the same modified file used during encode.

Common
  -f          Force overwrite existing output file(s)
  -q          Quiet: suppress progress bar output
  -n          Disable checksum verification (decode only)

Encode Quality
  -1 .. -9    Compression level (default: 3)
  -B SIZE     Source block size in KB (default: 8192 = 8 MB)
  -W SIZE     Encoder input window size in KB (default: 65536 = 64 MB)
  -E SIZE     Source window max size in KB (default: same as -B)
  -S TYPE     Secondary compression: none (default), djw, fgk, lzma
  -SD         Disable secondary compression of data section
  -SI         Disable secondary compression of inst section
  -SA         Disable secondary compression of addr section
  -N          Disable ordinary data compression (source-only matching)
  -G          Use greedy matching (faster, larger patches)
  -I SIZE     Instruction optimization buffer size (default: 32768)
  -P SIZE     Small string matching prev size

Multi-file (directory mode only)
  -m PATTERN  Source-scan match pattern: wildcards (*.bin), regex
              ($"^file.*\.bin$"), exact names, pipe-separated lists. Default: *
  -r          Recursive subdirectory search (off by default)
  -x EXT      Patch file extension (default: .xd3); leading dot optional

▌ KEY FEATURES

✦ Real-Time Progress Bar (Single-File)
Shows a progress bar, percent complete, current speed, and ETA.

✦ Overall Batch Progress Bar (Multi-File)
One progress bar spanning the entire batch. Speed is calculated over cumulative bytes across all files.

✦ Batch Summary Report
Printed after every multi-file run.

✦ Skip Logic in Batch Mode
Files with no matching original are silently skipped (not a failure). Files with existing output are skipped when -f is not given.

✦ Auto-Create Output Subdirectories
Output directories are created as needed — no pre-setup required.

✦ Custom Patch File Extension
The default patch extension is .xd3, but any extension can be used with -x EXT. Decode scans only for the specified extension and strips it to derive the original filename. Useful when patches were created by other tools using .vcdiff, .xdelta, .patch, etc.
Code colors: program · mode · -s · flag in focus · input · output

Encode:  xdelta3w -e -s mod\ orig\ patches\ -x .vcdiff
Decode:  xdelta3w -d -s mod\ patches\ output\ -x .vcdiff

✦ Flexible File Pattern Matching (-m)
The -m pattern controls which files in the source (modified) directory are processed during encode. In decode, it filters the rebuilt filenames after extension stripping. Supports wildcards, regex, and pipe lists.

-m "*.bin"                wildcard
-m $"^data_.*\.bin$"      regex
-m "a.bin|b.bin|c.bin"    pipe-separated exact names

▌ DISTRIBUTION FILES

Core

• xdelta3w.exe — main executable
• xdelta3_wrapper.dll — xdelta3 wrapper DLL (required at runtime)

Helper Scripts

• 0.Help.bat — runs xdelta3w -V then xdelta3w -h
• 1.Generate_TestData.bat — creates test input files in TestData\
• 2.Run_tests.bat — runs the full 38-test automated test suite
• 3.Encode.bat — CLI / interactive encode helper
• 4.Decode.bat — CLI / interactive decode helper

Test Data (auto-generated by 1.Generate_TestData.bat)

TestData\
 ├── original.bin       256 KB zeros
 ├── modified.bin       256 KB, first 4 KB = 0xFF
 ├── identical.bin      256 KB zeros (same as original)
 ├── Multi\Original\    a.bin, b.bin, sub\d.bin, medium.bin 10 MB, large\big.bin 100 MB
 └── Multi\Modified\    modified versions of the above

Licensing

• THIRD_PARTY_LICENSES.txt — third-party attribution (xdelta3, XZ Utils)
• licenses\Apache-2.0.txt — Apache License 2.0 (xdelta3 v3.1.0)
• licenses\GPL-2.0.txt — GNU GPL v2 (xdelta3 v3.0.11)
• licenses\0BSD.txt — BSD Zero Clause (XZ Utils)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━

Feedback, bug reports, and edge cases are all welcome.