Documentation / getting started
From a file
to a verified archive.
Start with a self-contained archive. Add shared dictionaries only when your workflow needs them.
Your first archive
Use a published build when available, or follow the source build instructions. These commands use no pattern database or remote service:
pizd compress access.log --standalone -o access.pizd pizd decompress access.pizd --offline -o restored.log cmp access.log restored.log
Keep the original until you have checked restoration. --verbose shows the selected archive mode, pattern statistics and byte-entropy diagnostic.
pizd compress access.log --standalone --offline --thin --verbose -o access.pizd
Choose a profile
| Profile | Command | Purpose |
|---|---|---|
| Default | pizd compress input.log --standalone | Automatic structured-data handling |
| Fast | pizd compress input.log --standalone --fast | Favor compression speed |
| Thin | pizd compress input.log --standalone --thin | Spend more effort on archive size |
These are objectives, not guarantees: a fast profile can lose on a particular source. The benchmark explorer keeps all three profiles separate. Use --dry-run for a sampled assessment; it is an estimate, not a full-file prediction.
Native or Hybrid
Native is the default engine. It uses PIZD’s Rust matching and entropy-coding pipeline. Hybrid uses Zstandard as a compression backend. Specify the engine explicitly when comparing results:
pizd compress input.log --standalone --engine native --thin -o native.pizd pizd compress input.log --standalone --engine hybrid --thin -o hybrid.pizd
Hybrid requires no separate zstd executable: the backend is linked through the Rust dependency. Native does not mean that every dependency in the distributed CLI is removed. Check each engine’s size, encode time and verified decode time.
Standalone first. Sharing when useful.
Standalone: the archive includes the patterns needed for restoration. This is the easiest option for exchange and long-term storage.
Local dictionary: --pattern-db patterns.pz uses a local pattern store. Shared-signature archives can require that exact store or another source containing the matching patterns. Back it up with the archives.
pizd compress input.log --offline --pattern-db patterns.pz -o shared.pizd pizd decompress shared.pizd --offline --pattern-db patterns.pz -o restored.log
Remote service: --server-url configures pattern-server access. Retrieval depends on the archive’s mode and available local or remote patterns. Remote access does not remove the need to retain required dictionary content.
Two files, two roles
| Extension | Role |
|---|---|
.pizd | A compressed archive: payload, format metadata and integrity check |
.pz | A local pattern dictionary, when used |
A shorter printed signature in a diagnostic dump is a display choice; it does not imply the stored cryptographic identifier is shortened. Use pizd --help and the subcommand help for the options in your build.
Verify contents and origin separately
Archive integrity verification detects a mismatch in restored data. Comparing the original file with its restoration is an independent round-trip check. Release checksums and GitHub attestations instead concern the downloaded software artifact. These checks answer different questions.
pizd bench input.log pizd --version pizd compress --help pizd decompress --help
For comparative claims, record the binary version, source identity, command options, corpus, archive size and both execution times. Read the methodology and limitations.
Keep experimental workflows explicit
rANS4 is an optional native entropy-coding route; it is not the default for every archive and does not automatically improve size or speed.
Radin is an explicitly lossy summary workflow. Its summaries are not equivalent to lossless compression of the original log, and its results must not be mixed with the lossless tables.
See the research archive for experiments, rejected ideas and historical measurements. A project experiment is not evidence of independent scientific validation.