Command reference
snapdir creates content-addressable directory snapshots. The 1.10.0 CLI has a
small universal output surface, plus command-specific option families: flags are
accepted only by the commands that use them. Put flags after the subcommand, as
shown in the examples on each command page.
snapdir [OPTIONS] <COMMAND>Commands
Universal options
These output-control flags are accepted by every subcommand.
Command-specific options
These flags are attached only to the commands that use them. Passing an inapplicable flag now fails with a clear clap error instead of being ignored.
Linked views and exact mirrors
checkout and pull are additive by default: they materialize the snapshot but
leave unrelated files already present in the destination. Add --delete to make
the destination an exact mirror of the snapshot. The mirror pass prunes entries
that are absent from the manifest, honors repeatable --exclude <PATTERN>
protections, supports --dryrun, refuses dangerous destinations such as /,
$HOME, the cache directory, and store paths, and unlinks extraneous symlinks
rather than following them.
--linked is the read-only local materialization mode for checkout and
pull: destination files are symlinks into local content-addressed objects
hardened to mode 0444. It is zero-copy and useful for local read-only views,
but it requires local objects; a remote object store is a hard error with
--linked. The flag may appear in the shared transfer option group for other
commands, but those commands do not create linked checkouts.
Catalog behavior
The default catalog is enabled when --catalog is unset. stage, push, and
manifest can record locations there, and locations, revisions, and
ancestors read from it. Pass --catalog none to disable catalog writes or
queries explicitly; query commands then report that the catalog is disabled.
Environment variables
The full set of SNAPDIR_* variables commonly used by the CLI:
Run snapdir defaults to print the effective settings,
including each resolved value and whether it came from a flag, env var, or
default.
Retries & backoff
On transient failures — HTTP 429/503, S3 SlowDown, GCS RESOURCE_EXHAUSTED,
and network timeouts — snapdir retries the request with full-jitter exponential
backoff (--max-retries / --retry-base-ms / --retry-max-ms). When the server
sends a Retry-After header, snapdir honors it as a floor: it never retries sooner
than the server asked, but may wait longer if the jittered backoff is larger.
Non-transient errors — 404, 403, missing objects, or bad credentials — fail fast
without retrying. The storage SDKs' own retry logic is disabled, so this is the single
retry policy for every backend. The per-backend request and bandwidth caps,
--max-requests, and --limit-rate are covered in the
Stores guide.
Stores
The --store URI selects a backend by scheme. Four schemes are served by
built-in, in-process adapters; any other scheme dispatches to a
snapdir-<scheme>-store shim on PATH — ssh:// and sftp:// ship as two
such first-party shims (cargo install snapdir-ssh-store provides both):
See Stores and cache and the Stores guide for details.