Enum Command

Source

pub enum Command {
    Pack {
        paths: Vec<String>,
        output: Option<String>,
        format: Option<String>,
        level: Option<i32>,
        force: bool,
        no_sync: bool,
        allow_weak_encoder: bool,
        threads: Option<usize>,
        turbo: bool,
        memory_limit: Option<String>,
        strict_fidelity: bool,
    },
    Unpack {
        input: String,
        patterns: Vec<String>,
        index: Vec<usize>,
        directory: Option<String>,
        strict_fidelity: bool,
        output: Option<String>,
        force: bool,
        format: Option<String>,
        max_ratio: Option<u64>,
        no_sync: bool,
        memory_limit: Option<String>,
    },
    Convert {Show 13 fields
        input: String,
        output_pos: Option<String>,
        output: Option<String>,
        format: Option<String>,
        level: Option<i32>,
        threads: Option<usize>,
        turbo: bool,
        allow_weak_encoder: bool,
        force: bool,
        strict_fidelity: bool,
        max_ratio: Option<u64>,
        memory_limit: Option<String>,
        no_sync: bool,
    },
    Cat {
        input: String,
        patterns: Vec<String>,
        index: Vec<usize>,
        format: Option<String>,
        max_ratio: Option<u64>,
        memory_limit: Option<String>,
    },
    Info {
        input: String,
        json: bool,
        memory_limit: Option<String>,
    },
    Formats,
    InstallLinks {
        dir: PathBuf,
        names: Vec<String>,
        force: bool,
        remove: bool,
        dry_run: bool,
    },
    List {
        input: String,
        json: bool,
        max_ratio: Option<u64>,
        memory_limit: Option<String>,
        strict_fidelity: bool,
    },
    Test {
        input: String,
        max_ratio: Option<u64>,
        memory_limit: Option<String>,
        strict_fidelity: bool,
    },
    Salvage {
        input: String,
        list: bool,
        directory: Option<String>,
        output: Option<String>,
        index: Vec<usize>,
        partial: Option<String>,
        max_entry: Option<String>,
        strict: bool,
        format: Option<String>,
    },
}

Variants§

§

Pack

Compress a file, or collect several into an archive.

Fields

§paths: Vec<String>

Input paths, or - for stdin.

More than one path needs an output that names a CONTAINER (-o bundle.tar, or --format tar): a codec compresses one stream and has nowhere to put a second.

§output: Option<String>

Output path. Defaults to INPUT plus the format’s extension.

§format: Option<String>

Use this format instead of inferring one from the output name.

§level: Option<i32>

Compression level. gzip accepts 0-9.

§force: bool

Overwrite an existing output.

§no_sync: bool

Skip the fsync that makes the output durable before it is published.

§allow_weak_encoder: bool

Use a weak fallback encoder that this build ships in place of the format’s real one. Worse ratio, and buffers the whole input.

§threads: Option<usize>

Encode with N worker threads. 0 means auto-detect.

OMITTING this flag is not the same as passing 0: without it, stuffr encodes single-threaded, so the same input always produces the same bytes on any machine. Multi-threaded xz and zstd split the input per worker, so their output depends on the worker count.

§turbo: bool

Use the full detected CPU budget, uncapped.

Lifts the CPU cap only — --memory-limit still binds. Turbo means “use my cores”, not “ignore the OOM killer”.

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

On encode this bounds the worker count. Defaults to 25% of available RAM, honouring cgroup limits.

§strict_fidelity: bool

Fail (exit 4) if anything was approximated or lost.

On the pack side that means something the walk met and could not store — a socket, an undecodable name, an unreadable directory — or an entry shape this container has none of, such as a directory or a symlink in an ar.

§

Unpack

Decompress a file, or extract an archive’s entries.

Fields

§input: String

Input path, or - for stdin.

§patterns: Vec<String>

Entries to extract; every entry when none are given.

An exact entry name, or a directory selecting everything beneath it. Needs -C, which is what asks for entry-aware extraction.

§index: Vec<usize>

Extract the entry at this position instead of naming it. Repeatable.

0-BASED, counting in archive order — the same number stuffr list prints in its first column. This is how you reach an entry whose name you cannot type: Makefile and makefile from a case-sensitive filesystem on a case-insensitive one. Needs -C, like PATTERNS, and cannot be combined with them — they are two ways of saying the same thing.

It does NOT reach a record a zip’s own index shadows: unpack counts the entries the index enumerates, so a record a later one hides is not at any index here — it has no number at all. stuffr salvage --list finds those, and salvage --index N selects them by SCAN position, which is a different numbering.

§directory: Option<String>

Extract the archive’s entries into this directory.

Absolute entry paths, .. traversal and symlinks escaping this directory are refused (exit 7), never silently sanitised.

§strict_fidelity: bool

Fail (exit 4) if anything was approximated or lost.

On extraction that means an entry whose mode or mtime could not be restored, or one skipped for having no shape on disk.

§output: Option<String>

Output path. Defaults to INPUT with its extension removed.

§force: bool

Overwrite an existing output.

§format: Option<String>

Use this format instead of detecting one. Required for formats with no magic bytes and no extension.

§max_ratio: Option<u64>

Refuse a decode expanding by more than this ratio.

§no_sync: bool

Skip the fsync that makes the output durable before it is published.

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Defaults to 25% of available RAM, honouring cgroup limits.

§

Convert

Change a file’s compression or its archive format, without unpacking it to disk.

Codec mode — the container is kept (.tar.gz -> .tar.zst, .gz -> .xz, .tar.xz -> .tar): the container, or the plain stream, is copied byte for byte and only the codec around it changes.

Entry mode — the container changes (.tgz -> .zip, .zip -> .tar.xz): every entry is read from the source and written into the target under pack’s rules, and what the target cannot hold (a directory or symlink in an ar, a device anywhere) is skipped with a fidelity warning. A hard link stays a link into tar and is written as a copy of its target elsewhere, or skipped, named, when no copy is available.

The input’s chain is detected by content, never by its name; the target’s comes from OUT’s name or –format.

Fields

§input: String

Input path, or - for stdin.

§output_pos: Option<String>

Output path; the same as -o. Give one or the other, not both.

§output: Option<String>

Output path, or - for stdout (which needs –format).

§format: Option<String>

Use this target format instead of inferring one from the output name. A codec or a container; one the name contradicts is refused.

§level: Option<i32>

Compression level for the target codec. gzip accepts 0-9.

Also what makes converting a file to the chain it already has (.tar.gz -> .tar.gz) a re-encode rather than “nothing to convert”.

§threads: Option<usize>

Encode with N worker threads. 0 means auto-detect.

OMITTING this flag is not the same as passing 0: without it, stuffr encodes single-threaded, so the same input always produces the same bytes on any machine. Multi-threaded xz and zstd split the input per worker, so their output depends on the worker count.

§turbo: bool

Use the full detected CPU budget, uncapped.

Lifts the CPU cap only — --memory-limit still binds. Turbo means “use my cores”, not “ignore the OOM killer”.

§allow_weak_encoder: bool

Use a weak fallback encoder that this build ships in place of the format’s real one. Worse ratio, and buffers the whole input.

§force: bool

Overwrite an existing output.

§strict_fidelity: bool

Fail (exit 4) if anything was approximated or lost.

In codec mode the container is copied byte for byte and nothing is lost. In entry mode every skipped entry or missing field is a warning, and this turns any of them into exit 4 — with the output still written, as with pack.

§max_ratio: Option<u64>

Refuse a decode expanding by more than this ratio.

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Bounds every source codec layer’s decoder and the encoder’s worker count. Defaults to 25% of available RAM, honouring cgroup limits.

§no_sync: bool

Skip the fsync that makes the output durable before it is published.

§

Cat

Decompress a file, or stream an archive’s entries, to stdout.

Fields

§input: String

Input path, or - for stdin.

§patterns: Vec<String>

Entries whose bytes to stream, in archive order.

An exact entry name, or a directory selecting everything beneath it. Naming one is what asks for entry-aware streaming; without any, cat decodes the input as a single stream.

§index: Vec<usize>

Stream the entry at this position instead of naming it. Repeatable.

0-BASED, counting in archive order — the same number stuffr list prints in its first column. stuffr cat a.zip --index 6 > out.sh is how you pull out an entry whose name is ambiguous or untypeable. Like PATTERNS, naming one asks for entry-aware streaming; the two cannot be combined.

§format: Option<String>

Use this format instead of detecting one. Required for formats with no magic bytes and no extension.

§max_ratio: Option<u64>

Refuse a decode expanding by more than this ratio.

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Defaults to 25% of available RAM, honouring cgroup limits.

§

Info

Identify a stream without decoding it.

Fields

§input: String

Input path, or - for stdin.

§json: bool

Emit machine-readable JSON instead of the human-readable report.

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Defaults to 25% of available RAM, honouring cgroup limits.

§

Formats

List the formats this build contains.

§

InstallLinks

Create compatibility symlinks (bzip2, bunzip2, bzcat, bzip2recover) to this binary in a directory. Opt-in, never automatic.

Fields

§dir: PathBuf

Directory to put the links in. It must already exist.

§names: Vec<String>

Only these names, comma-separated or repeated. Default: all.

§force: bool

Replace an existing file or foreign link of the same name.

§remove: bool

Remove stuffr’s links instead of creating them.

§dry_run: bool

Say what would change, and change nothing.

§

List

List an archive’s entries without extracting.

The first column is the entry’s 0-based position in archive order, which is what cat --index and unpack --index select by.

Fields

§input: String

Archive path, or - for stdin.

§json: bool

Emit machine-readable JSON instead of one entry per line.

§max_ratio: Option<u64>

Refuse a codec layer beneath the container expanding by more than this ratio (e.g. a .tar.gz bomb).

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Bounds the codec layer beneath the container, which --max-ratio cannot see: a pure xz/lzma/lzip decoder sizes its dictionary from a value the file declares in its own header, before producing any output. Defaults to 25% of available RAM, honouring cgroup limits.

§strict_fidelity: bool

Fail (exit 4) if the read approximated or lost anything.

A listing can be incomplete — a zip whose index shadows records enumerates fewer entries than the archive declares — so list gates on fidelity for the same reason test and unpack -C do.

§

Test

Verify every entry’s integrity without extracting.

Fields

§input: String

Archive path, or - for stdin.

§max_ratio: Option<u64>

Refuse a codec layer beneath the container expanding by more than this ratio (e.g. a .tar.gz bomb).

§memory_limit: Option<String>

Cap the memory stuffr will ask for, e.g. 512M or 2G.

Bounds the codec layer beneath the container, which --max-ratio cannot see: a pure xz/lzma/lzip decoder sizes its dictionary from a value the file declares in its own header, before producing any output. Defaults to 25% of available RAM, honouring cgroup limits.

§strict_fidelity: bool

Fail (exit 4) if the read approximated or lost anything.

§

Salvage

Recover what a damaged zip’s scan can prove, even where its central directory alone would show less — or would wrongly unify two records that happen to share a name.

The one recovery-biased verb in this tool. list, cat, unpack and test all stay exactly as uncompromising as they already are, and it is salvage’s willingness to accept less-than-proven content that buys them that freedom.

Fields

§input: String

Input path.

Salvage scans back and forth over the archive, which needs real random access — unlike every other verb here, this one does not accept - for stdin.

§list: bool

Print every record the scan found, including ones this build never writes (a shadow, a skipped partial, an unverified entry).

A record that repeats an earlier record’s name is marked one of two ways, and they mean different things. [shadowed: dup of #N] is a MEASUREMENT: name, declared length and checksum all agree with record N, so nothing is lost by not writing this one. [name collision: #N uses this name too] is the weaker fact: the name repeats but the content was not proven identical, so both records are worth having and -C writes the second one as name.salvaged-N, never over the first. It is the marker stuffr list’s own “repeat a name … and are shadowed” fidelity warning corresponds to.

stuffr list on the same archive can print FEWER rows than this: a record a later one shadows is invisible to list, which only ever sees what the central directory’s own name index kept. Works with no destination at all (neither -C nor -o) — listing is not recovering, and this is the diagnostic half of the feature: seeing what an archive holds without extracting anything.

§directory: Option<String>

Recover entries into this directory.

One of -C, -o or --list is required. Mutually exclusive with -o: a directory tree and one named file are two different destinations.

A damaged archive can hold two records under one name. The second one recovered lands as name.salvaged-N, where N is its scan position, rather than over the first — both records exist, both are worth having, and the run exits 4 so a script knows a name had to be changed.

§output: Option<String>

Recover exactly one entry’s bytes to this file, naming it with exactly one --index N.

A Partial entry still lands under FILE.partial, never FILE itself — the same rule -C follows, for the same reason: a truncated file under the name you asked for would be indistinguishable from a whole one. Refused (exit 2) with more than one --index, or together with -C.

§index: Vec<usize>

Recover only the record at this SCAN position instead of every one found. Repeatable with -C; -o takes exactly one.

A scan position is 0-based and counts every record the scan found, shadowed ones included — a DIFFERENT numbering from stuffr list’s own index, which never counts a shadowed record at all. On an archive where a name is duplicated, list --index 6 and salvage --index 6 can name different entries, or list’s may not exist at all. Always a scan position, never a list index.

§partial: Option<String>

What to do with an entry whose payload could not be fully proven: keep (default) writes it as name.partial, never under its real name; skip recovers nothing for it; ask has no terminal to ask from at this layer and is read conservatively as skip.

§max_entry: Option<String>

Raise the structural ceiling on a single entry’s declared length, e.g. 8G. A declaration over the ceiling is refused before anything is allocated on its say-so, either way.

§strict: bool

Demand proof: skip every partial entry regardless of --partial, and every unattested one (a format with no checksum and no header self-check, whose entries are otherwise written under their real names). The strict path every other verb in this tool already stands on, applied here on request instead of by default.

§format: Option<String>

Use this format instead of detecting one.

Selects among the formats this build’s salvage can attempt to scan — zip, tar, ar, cpio, arc, zoo, lha, arj — not merely accepted or rejected as in an earlier stage. Naming one this build has no salvage scanner for is refused at exit 3, exactly as an undetected archive of that same format would be. ar’s scanner walks members in order and cannot cross a damaged header; it says on stderr where it stopped.

Scanners exist for: zip, arc, zoo, lha, arj, tar, cpio, ar.