HDiffPatchw - Custom App for HDiffPatch Patching

[BLACKFIRE69]

hdiffpatchw v0.2
Custom Console App for HDiffPatch Diff/Patch
Windows x86 (runs on x64) · exe + 2 wrapper DLLs · by BLACKFIRE69

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

▌ OVERVIEW
hdiffpatchw is a Windows console wrapper for HDiffPatch that exposes diff (create patch) and patch (apply patch) operations through a clean command-line interface. It is backed by two wrapper DLLs, one per engine side: hdiffz_wrapper.dll (diff / "encode" side) and hpatchz_wrapper.dll (patch / "decode" side). Three operating modes:

• Single-file mode — diff or patch one file at a time, with a full real-time progress bar showing speed and ETA.
• Folder (batch) mode — diff or patch an entire directory tree in one pass (one patch per file), with an overall batch progress bar spanning all files and a summary report on completion.
• Full engine passthrough — the hdiffz / hpatchz verbs forward arguments verbatim to the HDiffPatch engine, exposing EVERY upstream option and default — native single-pass directory diff, window/bsdiff/VCDIFF formats, all checksums, and multi-threaded patching.

▌ TECHNICAL SPECIFICATIONS

• Tool version — v0.2
• Author — BLACKFIRE69
• HDiffPatch version — 5.0.1
• DLLs — hdiffz_wrapper.dll (diff), hpatchz_wrapper.dll (patch)
• Platform — Windows x86 (32-bit exe, runs on 64-bit Windows)

▌ CLI REFERENCE

; Single-file
hdiffpatchw -e -s MODIFIED [-c TYPE] [-1..-9] [-D MB] [-b SIZE]
                  [-p N] [-f] [-q] ORIGINAL PATCH
hdiffpatchw -d -s MODIFIED [-p N] [-f] [-q] PATCH OUTPUT
hdiffpatchw -V | -h

; Folder usage  (-s points to a directory -> recursive batch, one patch per file)
hdiffpatchw -e -s MOD_DIR [-c TYPE] [-1..-9] [-D MB] [-m PAT] [-r]
                  [-x EXT] [-f] [-q] ORIG_DIR PATCH_DIR
hdiffpatchw -d -s MOD_DIR [-m PAT] [-r] [-x EXT] [-f] [-q]
                  PATCH_DIR OUTPUT_DIR

; Full engine access  (passthrough - every upstream flag + default)
hdiffpatchw hdiffz  [hdiffz args ...]  old new outDiff
hdiffpatchw hpatchz [hpatchz args ...] old diff outNew

▌ OPTIONS

Modes
  -e          Create patch from  old + new  -> diff
  -d          Apply patch  from  old + diff -> new
  hdiffz      Full engine access — create patch
  hpatchz     Full engine access — apply patch
  -V          Print DLL version and exit
  -h          Print help and exit

Required
  -s PATH     Modified file or directory (the "new" / changed version).

Convenience Options
  -c TYPE     Compressor (diff only): none zlib zstd lzma lzma2 bzip2 (default: zstd)
  -1 .. -9    Compression level (diff only; default = compressor's own)
  -D MB       Dictionary size in MB for lzma/lzma2 (diff only; 0 = default)
  -b SIZE     Match block size in bytes (diff only; 0 = default 64)
  -p N        Worker thread count (1 = single-threaded; default 1)
  -f          Force overwrite existing output file(s)
  -q          Quiet: suppress progress bar output

Folder Options (directory mode only)
  -m PATTERN  File match pattern for the source directory scan (default: *)
              wildcard · exact name · pipe-list · mask file (@list.txt) · regex
  -r          Recursive subdirectory search (off by default)
  -x EXT      Patch file extension (default: .hdiff)

▌ FULL ENGINE REFERENCE (PASSTHROUGH)
The convenience -e / -d verbs cover everyday use. For complete control, the hdiffz / hpatchz passthrough verbs forward every argument straight to HDiffPatch — every flag and default is the upstream default.

hdiffz (diff)  hdiffpatchw hdiffz <opts> old new outdiff
  -m[-score]   memory mode, best size (DEFAULT -m-4)
  -s[-block]   stream mode, fast, bounded memory (DEFAULT -s-64)
  -SD[-step]   single-compressed HDIFFSF20 — RECOMMENDED; step + multi-thread patching
  -w[-win]     window mode, optimizes old-data reads
  -WD[-step]   window diffData HDIFFW26 (advanced; prefer -SD)
  -BSD         bsdiff4-compatible patch
  -VCD[-lvl]   VCDIFF-compatible (xdelta3 / open-vcdiff)
  -c-TYPE[-level[-dict/bits]]   no | zlib | ldef | bzip2 | pbzip2 | lzma | lzma2 | zstd
  -C-TYPE      checksum: no|crc32|fadler64|md5|xxh3|xxh128
  -p-N  -p-search-N   parallel threads / search threads
  -D           force dir diff
  -g#path#...  ignore list
  -n-N         max open files (dir diff)
  -M#file      manifest
  -neq -d -t -f -info -v -h

hpatchz (patch)  hdiffpatchw hpatchz <opts> old diff outnew
  -s[-cache]   old loaded as stream (DEFAULT -s-8m)
  -m           load old fully into memory
  -p-N         parallel threads 1..5 (DEFAULT ******; -SD diffs only)
  -C-sets      checksum: no|new|diff|old|copy|all (DEFAULT -C-new-copy)
  -n-N         max simultaneously open files, dir patch (DEFAULT -n-24)
  -f -info -v -h

▌ KEY FEATURES

✦ Real-Time Progress Bar (Single-File)
Byte-accurate progress bar, percent complete, current speed, and ETA on both the diff and patch paths.

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

✦ Batch Summary Report
Printed after every folder run (processed / skipped / failed counts).

✦ Skip Logic in Batch Mode
Files with no matching old file 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 .hdiff, but any extension can be used with -x EXT. Patch mode scans only for the specified extension and strips it to derive the original filename.

✦ Full Engine Passthrough
hdiffz / hpatchz verbs expose every upstream option and default — native single-pass directory diff, window/bsdiff/VCDIFF formats, all checksums (crc32/fadler64/md5/xxh3/xxh128), and multi-threaded patching.

✦ Bundled Compressors
zstd (default), zlib, lzma, lzma2, and bzip2 are all built in — no external DLLs required.

✦ Flexible File Pattern Matching (-m)
The -m pattern controls which files in the new (source) directory are processed during diff. In patch, it filters the rebuilt filenames after extension stripping. Supports wildcards, exact names, pipe lists, mask files (@list.txt), and regex.

-m "*.bin"                     wildcard
-m "a.bin|b.bin|c.bin"        pipe-separated exact names
-m @list.txt                  mask file — use this for regex patterns

Note: the command line strips the "" around a regex, so put regex patterns in a mask file and pass them as -m @list.txt

▌ EXAMPLES

; Convenience diff/patch
hdiffpatchw diff  -c zstd -9 old.bin new.bin patch.hdiff
hdiffpatchw diff  -c lzma2 -9 -D 16 old.bin new.bin patch.hdiff
hdiffpatchw patch old.bin patch.hdiff rebuilt.bin
hdiffpatchw diff  -m *.bin -r -f old_dir\ new_dir\ patch_dir\
hdiffpatchw patch -r old_dir\ patch_dir\ out_dir\

; Advanced (full engine via passthrough)
; single-compressed step format: step + multi-thread patching
hdiffpatchw hdiffz  -SD-64k -c-zstd-20 ****** old.bin new.bin patch.hdiff
hdiffpatchw hpatchz ****** old.bin patch.hdiff out.bin

; directory diff: xxh128 checksum, ignore .git* and *.tmp
hdiffpatchw hdiffz -SD -C-xxh128 -g#.git*#*.tmp old_dir new_dir dir.hdiff

; VCDIFF (xdelta3-compatible) and bsdiff4-compatible patches
hdiffpatchw hdiffz -VCD-7 old.bin new.bin patch.vcdiff
hdiffpatchw hdiffz -BSD   old.bin new.bin patch.bsdiff4

; inspect a diff file
hdiffpatchw hdiffz -info patch.hdiff

▌ DISTRIBUTION FILES

Core

• hdiffpatchw.exe — main executable
• hdiffz_wrapper.dll — diff (encode) wrapper DLL (required)
• hpatchz_wrapper.dll — patch (decode) wrapper DLL (required)

Helper Scripts

• 0.Help.bat — prints version then full help
• 1.Generate_TestData.bat — creates test input files in TestData\
• 2.Run_tests.bat — runs the full 36-test automated test suite
• 3.Diff.bat — CLI / interactive diff helper
• 4.Patch.bat — CLI / interactive patch helper

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

TestData\
 ├── old.bin            256 KB zeros
 ├── new.bin            256 KB zeros, first 4 KB = 0xFF
 ├── identical.bin      256 KB zeros (same as old)
 ├── Folder\Old\        a.bin, b.bin, sub\c.bin, large\medium.bin 10 MB, large\big.bin 100 MB
 └── Folder\New\        modified versions of the above

Alternate Builds

• _hdiffpatch_dll\ — the two wrapper DLLs from each toolchain
  • build_gcc\ — MinGW gcc
  • build_clang\ — MinGW clang
  • build_msvc\ — MSVC (cl/link)
  • build_clang_msvc\ — clang targeting the MSVC runtime

Licensing

• THIRD_PARTY_LICENSES.txt — third-party attribution (HDiffPatch + deps)
• licenses\HDiffPatch.txt — MIT (HDiffPatch + libdivsufsort)
• licenses\zstd.txt — BSD 3-Clause (Zstandard)
• licenses\zlib.txt — zlib License
• licenses\LZMA-SDK.txt — Public domain (LZMA SDK)
• licenses\bzip2.txt — bzip2 License (BSD-style)
• licenses\libdeflate.txt — MIT (libdeflate)
• licenses\xxHash.txt — BSD 2-Clause (xxHash)
• licenses\libmd5.txt — zlib-style Aladdin license (libmd5)

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

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