Add information to the spec on including binary file changes in diffs.

Review Request #14369 — Created March 17, 2025 and updated

Information

DiffX
master

Reviewers

The specification now clearly documents how to support binary diffs
using three methods:

  • VCDIFFs (recommended)
  • Git Delta diffs
  • Git Literal diffs

VCDIFFs (RFC 3284) are a standardized binary format for representing
patches to binary files. It includes instructions for adding a sequence
of new bytes, adding a single byte N times, and copying bytes from a
source to a target. The format allows for future extensibility.

Git Delta diffs are similar to VCDIFFs in concept, but more limited.
They contain instructions for adding a sequence of new bytes and for
copying bytes from a source to a target. They do not include any
run-length encoding instructions, and are not built to be extended for
new instructions in the future, but its structure is overall more
compact than VCDIFFs.

Git Literal diffs simply contain the full contents of the patched file.

In all three cases, diffs are expected to contain a forward patch and a
reverse patch. The binary contents of each represent the payloads of the
above formats, compressed using zlib, Base85-encoded, and then split
across lines with encoded length indicators.

The specification includes instructions for encoding and decoding each
format (deferring to RFC 3284 for VCDIFF, and documenting the formats
for Git Deltas and Literals).

Built the spec. Checked for spelling errors, grammatical errors, and
bad links.

Code samples came from test code used to validate the encoding/decoding
logic. Those code samples are not included at this time, as they need
further cleanup.

Summary ID
Add information to the spec on including binary file changes in diffs.
The specification now clearly documents how to support binary diffs using three methods: * VCDIFFs (recommended) * Git Delta diffs * Git Literal diffs VCDIFFs (RFC 3284) are a standardized binary format for representing patches to binary files. It includes instructions for adding a sequence of new bytes, adding a single byte N times, and copying bytes from a source to a target. The format allows for future extensibility. Git Delta diffs are similar to VCDIFFs in concept, but more limited. They contain instructions for adding a sequence of new bytes and for copying bytes from a source to a target. They do not include any run-length encoding instructions, and are not built to be extended for new instructions in the future, but its structure is overall more compact than VCDIFFs. Git Literal diffs simply contain the full contents of the patched file. In all three cases, diffs are expected to contain a forward patch and a reverse patch. The binary contents of each represent the payloads of the above formats, compressed using zlib, Base85-encoded, and then split across lines with encoded length indicators. The specification includes instructions for encoding and decoding each format (deferring to RFC 3284 for VCDIFF, and documenting the formats for Git Deltas and Literals).
4f9873047fe28a352aeff4ca9e56d438ca34ff10
Checks run (2 succeeded)
flake8 passed.
JSHint passed.
Loading...