Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Wire compression codecs

-compress keeps its LZ4 behavior and its version-5 handshake. -compress.codec names a codec, lz4, deflate or zstd, and implies -compress. -compress-codec is the same option, the spelling the first zstd change used. Naming two different codecs with the two spellings is refused. The codec applies to payloads over ssh://, rcp:// and rcps://, including delta literals and streamed reads. Choosing between them is covered below (Pick zstd when…).

zstd is in every build: this crate carries its own encoder and decoder, so no library and no feature is needed. cargo build --features system-zstd swaps in the system libzstd as the backend instead. Install the development/link library first (for example libzstd-dev on Debian); the feature adds a small binding to its stable one-shot C API, with no new Cargo packages, build script or downloads. The two backends make and read the same frames, so a build with the feature and one without it compress to each other in both directions. The test suite checks this. Cargo still needs registry metadata for the optional rustls dependency to resolve the lockfile offline.

The handshake. Raw and LZ4 use protocol 5, byte for byte as before. Any other codec uses protocol 6, naming itself with a tag in HELLO: zstd is 2, deflate 3 (plus its level). The serve must answer with the same tag. A serve that does not speak 6 refuses it by version before it reads the target or creates a directory. A v6 tag it does not answer is refused too. There is no silent downgrade, so use -compress for LZ4 with an older peer. A payload’s tag is never sent unless HELLO agreed to it.

The same prefix probe, 10% saving threshold and incompressible-block pause apply to every codec. Unprofitable blocks go raw. Compressed payloads carry the original length and a CRC-32 of the original bytes, and a claimed length beyond what the codec can produce is refused before anything is allocated. The same codec also reads and writes .tar.zst through tar://; see Archives.