stuffr_cli/cli.rs
1//! The `stuffr` command's argument surface.
2//!
3//! Pulled out of `main.rs` and re-exported from `lib.rs` so an integration
4//! test can ask clap itself — via [`clap::CommandFactory`] — what flags and
5//! subcommands exist, rather than keeping a second, hand-maintained list that
6//! the examples page could silently drift out of sync with. `main.rs` still
7//! owns everything that isn't the argument shape: parsing, dispatch, and the
8//! examples text itself.
9
10use clap::{Args, Parser, Subcommand};
11
12#[derive(Parser)]
13#[command(
14 name = "stuffr",
15 version,
16 about = "Universal compression and archive toolkit"
17)]
18pub struct Cli {
19 #[command(subcommand)]
20 pub command: Option<Command>,
21 /// Print detailed usage examples covering every feature, then exit.
22 #[arg(long)]
23 pub examples: bool,
24}
25
26#[derive(Subcommand)]
27pub enum Command {
28 /// Compress a file, or collect several into an archive.
29 Pack {
30 /// Input paths, or `-` for stdin.
31 ///
32 /// More than one path needs an output that names a CONTAINER (`-o
33 /// bundle.tar`, or `--format tar`): a codec compresses one stream and
34 /// has nowhere to put a second.
35 #[arg(required = true, num_args = 1.., value_name = "PATHS")]
36 paths: Vec<String>,
37 /// Output path. Defaults to INPUT plus the format's extension.
38 #[arg(short, long)]
39 output: Option<String>,
40 /// Use this format instead of inferring one from the output name.
41 #[arg(long)]
42 format: Option<String>,
43 /// Compression level. gzip accepts 0-9.
44 #[arg(long)]
45 level: Option<i32>,
46 /// Overwrite an existing output.
47 #[arg(long)]
48 force: bool,
49 /// Skip the fsync that makes the output durable before it is published.
50 #[arg(long)]
51 no_sync: bool,
52 /// Use a weak fallback encoder that this build ships in place of the
53 /// format's real one. Worse ratio, and buffers the whole input.
54 #[arg(long)]
55 allow_weak_encoder: bool,
56 /// Encode with N worker threads. 0 means auto-detect.
57 ///
58 /// OMITTING this flag is not the same as passing 0: without it, stuffr
59 /// encodes single-threaded, so the same input always produces the same
60 /// bytes on any machine. Multi-threaded xz and zstd split the input
61 /// per worker, so their output depends on the worker count.
62 #[arg(long)]
63 threads: Option<usize>,
64 /// Use the full detected CPU budget, uncapped.
65 ///
66 /// Lifts the CPU cap only — `--memory-limit` still binds. Turbo means
67 /// "use my cores", not "ignore the OOM killer".
68 #[arg(long)]
69 turbo: bool,
70 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
71 ///
72 /// On encode this bounds the worker count. Defaults to 25% of
73 /// available RAM, honouring cgroup limits.
74 #[arg(long, value_name = "SIZE")]
75 memory_limit: Option<String>,
76 /// Fail (exit 4) if anything was approximated or lost.
77 ///
78 /// On the pack side that means something the walk met and could not
79 /// store — a socket, an undecodable name, an unreadable directory —
80 /// or an entry shape this container has none of, such as a directory
81 /// or a symlink in an `ar`.
82 #[arg(long)]
83 strict_fidelity: bool,
84 },
85 /// Decompress a file, or extract an archive's entries.
86 Unpack {
87 /// Input path, or `-` for stdin.
88 input: String,
89 /// Entries to extract; every entry when none are given.
90 ///
91 /// An exact entry name, or a directory selecting everything beneath
92 /// it. Needs -C, which is what asks for entry-aware extraction.
93 #[arg(value_name = "PATTERNS")]
94 patterns: Vec<String>,
95 /// Extract the entry at this position instead of naming it. Repeatable.
96 ///
97 /// 0-BASED, counting in archive order — the same number `stuffr list`
98 /// prints in its first column. This is how you reach an entry whose
99 /// name you cannot type: `Makefile` and `makefile` from a
100 /// case-sensitive filesystem on a case-insensitive one. Needs -C,
101 /// like PATTERNS, and cannot be combined with them — they are two
102 /// ways of saying the same thing.
103 ///
104 /// It does NOT reach a record a zip's own index shadows: `unpack`
105 /// counts the entries the index enumerates, so a record a later one
106 /// hides is not at any index here — it has no number at all. `stuffr
107 /// salvage --list` finds those, and `salvage --index N` selects them
108 /// by SCAN position, which is a different numbering.
109 #[arg(long, value_name = "N")]
110 index: Vec<usize>,
111 /// Extract the archive's entries into this directory.
112 ///
113 /// Absolute entry paths, `..` traversal and symlinks escaping this
114 /// directory are refused (exit 7), never silently sanitised.
115 #[arg(short = 'C', long, value_name = "DIR")]
116 directory: Option<String>,
117 /// Fail (exit 4) if anything was approximated or lost.
118 ///
119 /// On extraction that means an entry whose mode or mtime could not be
120 /// restored, or one skipped for having no shape on disk.
121 #[arg(long)]
122 strict_fidelity: bool,
123 /// Output path. Defaults to INPUT with its extension removed.
124 #[arg(short, long)]
125 output: Option<String>,
126 /// Overwrite an existing output.
127 #[arg(long)]
128 force: bool,
129 /// Use this format instead of detecting one. Required for formats with
130 /// no magic bytes and no extension.
131 #[arg(long)]
132 format: Option<String>,
133 /// Refuse a decode expanding by more than this ratio.
134 #[arg(long)]
135 max_ratio: Option<u64>,
136 /// Skip the fsync that makes the output durable before it is published.
137 #[arg(long)]
138 no_sync: bool,
139 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
140 ///
141 /// Defaults to 25% of available RAM, honouring cgroup limits.
142 #[arg(long, value_name = "SIZE")]
143 memory_limit: Option<String>,
144 },
145 /// Change a file's compression or its archive format, without unpacking
146 /// it to disk.
147 ///
148 /// Codec mode — the container is kept (`.tar.gz` -> `.tar.zst`, `.gz` ->
149 /// `.xz`, `.tar.xz` -> `.tar`): the container, or the plain stream, is
150 /// copied byte for byte and only the codec around it changes.
151 ///
152 /// Entry mode — the container changes (`.tgz` -> `.zip`, `.zip` ->
153 /// `.tar.xz`): every entry is read from the source and written into the
154 /// target under pack's rules, and what the target cannot hold (a
155 /// directory or symlink in an ar, a device anywhere) is skipped with a
156 /// fidelity warning. A hard link stays a link into tar and is written
157 /// as a copy of its target elsewhere, or skipped, named, when no copy
158 /// is available.
159 ///
160 /// The input's chain is detected by content, never by its name; the
161 /// target's comes from OUT's name or --format.
162 Convert {
163 /// Input path, or `-` for stdin.
164 input: String,
165 /// Output path; the same as -o. Give one or the other, not both.
166 #[arg(value_name = "OUT")]
167 output_pos: Option<String>,
168 /// Output path, or `-` for stdout (which needs --format).
169 #[arg(short, long)]
170 output: Option<String>,
171 /// Use this target format instead of inferring one from the output
172 /// name. A codec or a container; one the name contradicts is refused.
173 #[arg(long)]
174 format: Option<String>,
175 /// Compression level for the target codec. gzip accepts 0-9.
176 ///
177 /// Also what makes converting a file to the chain it already has
178 /// (`.tar.gz` -> `.tar.gz`) a re-encode rather than "nothing to
179 /// convert".
180 #[arg(long)]
181 level: Option<i32>,
182 /// Encode with N worker threads. 0 means auto-detect.
183 ///
184 /// OMITTING this flag is not the same as passing 0: without it, stuffr
185 /// encodes single-threaded, so the same input always produces the same
186 /// bytes on any machine. Multi-threaded xz and zstd split the input
187 /// per worker, so their output depends on the worker count.
188 #[arg(long)]
189 threads: Option<usize>,
190 /// Use the full detected CPU budget, uncapped.
191 ///
192 /// Lifts the CPU cap only — `--memory-limit` still binds. Turbo means
193 /// "use my cores", not "ignore the OOM killer".
194 #[arg(long)]
195 turbo: bool,
196 /// Use a weak fallback encoder that this build ships in place of the
197 /// format's real one. Worse ratio, and buffers the whole input.
198 #[arg(long)]
199 allow_weak_encoder: bool,
200 /// Overwrite an existing output.
201 #[arg(long)]
202 force: bool,
203 /// Fail (exit 4) if anything was approximated or lost.
204 ///
205 /// In codec mode the container is copied byte for byte and nothing
206 /// is lost. In entry mode every skipped entry or missing field is a
207 /// warning, and this turns any of them into exit 4 — with the output
208 /// still written, as with pack.
209 #[arg(long)]
210 strict_fidelity: bool,
211 /// Refuse a decode expanding by more than this ratio.
212 #[arg(long)]
213 max_ratio: Option<u64>,
214 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
215 ///
216 /// Bounds every source codec layer's decoder and the encoder's worker
217 /// count. Defaults to 25% of available RAM, honouring cgroup limits.
218 #[arg(long, value_name = "SIZE")]
219 memory_limit: Option<String>,
220 /// Skip the fsync that makes the output durable before it is published.
221 #[arg(long)]
222 no_sync: bool,
223 },
224 /// Decompress a file, or stream an archive's entries, to stdout.
225 Cat {
226 /// Input path, or `-` for stdin.
227 input: String,
228 /// Entries whose bytes to stream, in archive order.
229 ///
230 /// An exact entry name, or a directory selecting everything beneath
231 /// it. Naming one is what asks for entry-aware streaming; without
232 /// any, `cat` decodes the input as a single stream.
233 #[arg(value_name = "PATTERNS")]
234 patterns: Vec<String>,
235 /// Stream the entry at this position instead of naming it. Repeatable.
236 ///
237 /// 0-BASED, counting in archive order — the same number `stuffr list`
238 /// prints in its first column. `stuffr cat a.zip --index 6 > out.sh`
239 /// is how you pull out an entry whose name is ambiguous or
240 /// untypeable. Like PATTERNS, naming one asks for entry-aware
241 /// streaming; the two cannot be combined.
242 #[arg(long, value_name = "N")]
243 index: Vec<usize>,
244 /// Use this format instead of detecting one. Required for formats with
245 /// no magic bytes and no extension.
246 #[arg(long)]
247 format: Option<String>,
248 /// Refuse a decode expanding by more than this ratio.
249 #[arg(long)]
250 max_ratio: Option<u64>,
251 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
252 ///
253 /// Defaults to 25% of available RAM, honouring cgroup limits.
254 #[arg(long, value_name = "SIZE")]
255 memory_limit: Option<String>,
256 },
257 /// Identify a stream without decoding it.
258 Info {
259 /// Input path, or `-` for stdin.
260 input: String,
261 /// Emit machine-readable JSON instead of the human-readable report.
262 #[arg(long)]
263 json: bool,
264 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
265 ///
266 /// Defaults to 25% of available RAM, honouring cgroup limits.
267 #[arg(long, value_name = "SIZE")]
268 memory_limit: Option<String>,
269 },
270 /// List the formats this build contains.
271 Formats,
272 /// Compare compression formats on your own files: size, ratio, and
273 /// compress and decompress time for each one.
274 ///
275 /// Every format runs under the same conditions: the same input (all in
276 /// memory, or all streamed from disk when it is over half of
277 /// --memory-limit), the same thread setting, and one untimed warm-up
278 /// read first. Only codec work is timed, except the temp file's writes
279 /// for a codec whose worst-case output is too large for memory; such a
280 /// row is marked. A format that fails is a row
281 /// marked failed, not an exit code. Timings need a release build.
282 Bench(BenchArgs),
283 /// Create compatibility symlinks (`bzip2`, `bunzip2`, `bzcat`,
284 /// `bzip2recover`) to this binary in a directory. Opt-in, never automatic.
285 InstallLinks {
286 /// Directory to put the links in. It must already exist.
287 #[arg(long, value_name = "DIR")]
288 dir: std::path::PathBuf,
289 /// Only these names, comma-separated or repeated. Default: all.
290 #[arg(long, value_name = "NAME", value_delimiter = ',')]
291 names: Vec<String>,
292 /// Replace an existing file or foreign link of the same name.
293 #[arg(long)]
294 force: bool,
295 /// Remove stuffr's links instead of creating them.
296 #[arg(long)]
297 remove: bool,
298 /// Say what would change, and change nothing.
299 #[arg(long)]
300 dry_run: bool,
301 },
302 /// List an archive's entries without extracting.
303 ///
304 /// The first column is the entry's 0-based position in archive order,
305 /// which is what `cat --index` and `unpack --index` select by.
306 #[command(alias = "ls")]
307 List {
308 /// Archive path, or `-` for stdin.
309 input: String,
310 /// Emit machine-readable JSON instead of one entry per line.
311 #[arg(long)]
312 json: bool,
313 /// Refuse a codec layer beneath the container expanding by more
314 /// than this ratio (e.g. a `.tar.gz` bomb).
315 #[arg(long)]
316 max_ratio: Option<u64>,
317 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
318 ///
319 /// Bounds the codec layer beneath the container, which `--max-ratio`
320 /// cannot see: a pure xz/lzma/lzip decoder sizes its dictionary from
321 /// a value the file declares in its own header, before producing any
322 /// output. Defaults to 25% of available RAM, honouring cgroup limits.
323 #[arg(long, value_name = "SIZE")]
324 memory_limit: Option<String>,
325 /// Fail (exit 4) if the read approximated or lost anything.
326 ///
327 /// A listing can be incomplete — a zip whose index shadows records
328 /// enumerates fewer entries than the archive declares — so `list`
329 /// gates on fidelity for the same reason `test` and `unpack -C` do.
330 #[arg(long)]
331 strict_fidelity: bool,
332 },
333 /// Verify every entry's integrity without extracting.
334 Test {
335 /// Archive path, or `-` for stdin.
336 input: String,
337 /// Refuse a codec layer beneath the container expanding by more
338 /// than this ratio (e.g. a `.tar.gz` bomb).
339 #[arg(long)]
340 max_ratio: Option<u64>,
341 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
342 ///
343 /// Bounds the codec layer beneath the container, which `--max-ratio`
344 /// cannot see: a pure xz/lzma/lzip decoder sizes its dictionary from
345 /// a value the file declares in its own header, before producing any
346 /// output. Defaults to 25% of available RAM, honouring cgroup limits.
347 #[arg(long, value_name = "SIZE")]
348 memory_limit: Option<String>,
349 /// Fail (exit 4) if the read approximated or lost anything.
350 #[arg(long)]
351 strict_fidelity: bool,
352 },
353 /// Recover what a damaged zip's scan can prove, even where its central
354 /// directory alone would show less — or would wrongly unify two records
355 /// that happen to share a name.
356 ///
357 /// The one recovery-biased verb in this tool. `list`, `cat`, `unpack` and
358 /// `test` all stay exactly as uncompromising as they already are, and it
359 /// is salvage's willingness to accept less-than-proven content that buys
360 /// them that freedom.
361 Salvage {
362 /// Input path.
363 ///
364 /// Salvage scans back and forth over the archive, which needs real
365 /// random access — unlike every other verb here, this one does not
366 /// accept `-` for stdin.
367 input: String,
368 /// Print every record the scan found, including ones this build
369 /// never writes (a shadow, a skipped partial, an unverified entry).
370 ///
371 /// A record that repeats an earlier record's name is marked one of
372 /// two ways, and they mean different things. `[shadowed: dup of #N]`
373 /// is a MEASUREMENT: name, declared length and checksum all agree
374 /// with record N, so nothing is lost by not writing this one.
375 /// `[name collision: #N uses this name too]` is the weaker fact:
376 /// the name repeats but the content was not proven identical, so
377 /// both records are worth having and `-C` writes the second one as
378 /// `name.salvaged-N`, never over the first. It is the marker
379 /// `stuffr list`'s own "repeat a name … and are shadowed" fidelity
380 /// warning corresponds to.
381 ///
382 /// `stuffr list` on the same archive can print FEWER rows than this:
383 /// a record a later one shadows is invisible to `list`, which only
384 /// ever sees what the central directory's own name index kept. Works
385 /// with no destination at all (neither `-C` nor `-o`) — listing is
386 /// not recovering, and this is the diagnostic half of the feature:
387 /// seeing what an archive holds without extracting anything.
388 #[arg(long)]
389 list: bool,
390 /// Recover entries into this directory.
391 ///
392 /// One of `-C`, `-o` or `--list` is required. Mutually exclusive
393 /// with `-o`: a directory tree and one named file are two different
394 /// destinations.
395 ///
396 /// A damaged archive can hold two records under one name. The
397 /// second one recovered lands as `name.salvaged-N`, where N is its
398 /// scan position, rather than over the first — both records exist,
399 /// both are worth having, and the run exits 4 so a script knows a
400 /// name had to be changed.
401 #[arg(short = 'C', long, value_name = "DIR")]
402 directory: Option<String>,
403 /// Recover exactly one entry's bytes to this file, naming it with
404 /// exactly one `--index N`.
405 ///
406 /// A `Partial` entry still lands under `FILE.partial`, never `FILE`
407 /// itself — the same rule `-C` follows, for the same reason: a
408 /// truncated file under the name you asked for would be
409 /// indistinguishable from a whole one. Refused (exit 2) with more
410 /// than one `--index`, or together with `-C`.
411 #[arg(short = 'o', long, value_name = "FILE")]
412 output: Option<String>,
413 /// Recover only the record at this SCAN position instead of every
414 /// one found. Repeatable with `-C`; `-o` takes exactly one.
415 ///
416 /// A scan position is 0-based and counts every record the scan
417 /// found, shadowed ones included — a DIFFERENT numbering from
418 /// `stuffr list`'s own index, which never counts a shadowed record at
419 /// all. On an archive where a name is duplicated, `list --index 6`
420 /// and `salvage --index 6` can name different entries, or `list`'s
421 /// may not exist at all. Always a scan position, never a list index.
422 #[arg(long, value_name = "N")]
423 index: Vec<usize>,
424 /// What to do with an entry whose payload could not be fully proven:
425 /// `keep` (default) writes it as `name.partial`, never under its
426 /// real name; `skip` recovers nothing for it; `ask` has no terminal
427 /// to ask from at this layer and is read conservatively as `skip`.
428 #[arg(long, value_name = "POLICY")]
429 partial: Option<String>,
430 /// Raise the structural ceiling on a single entry's declared length,
431 /// e.g. 8G. A declaration over the ceiling is refused before
432 /// anything is allocated on its say-so, either way.
433 #[arg(long, value_name = "SIZE")]
434 max_entry: Option<String>,
435 /// Demand proof: skip every partial entry regardless of `--partial`,
436 /// and every unattested one (a format with no checksum and no header
437 /// self-check, whose entries are otherwise written under their real
438 /// names). The strict path every other verb in this tool already
439 /// stands on, applied here on request instead of by default.
440 #[arg(long)]
441 strict: bool,
442 /// Use this format instead of detecting one.
443 ///
444 /// Selects among the formats this build's salvage can attempt to
445 /// scan — `zip`, `tar`, `ar`, `cpio`, `arc`, `zoo`, `lha`, `arj` — not
446 /// merely accepted or rejected as in an earlier stage. Naming one
447 /// this build has no salvage scanner for is refused at exit 3,
448 /// exactly as an undetected archive of that same format would be.
449 /// `ar`'s scanner walks members in order and cannot cross a damaged
450 /// header; it says on stderr where it stopped.
451 ///
452 /// Scanners exist for: zip, arc, zoo, lha, arj, tar, cpio, ar.
453 #[arg(long)]
454 format: Option<String>,
455 },
456}
457
458/// The arguments of `stuffr bench`.
459#[derive(Args, Debug)]
460pub struct BenchArgs {
461 /// Files to benchmark, or quoted glob patterns (`'logs/*.log'`).
462 ///
463 /// A path that exists is used as is; one that does not and contains
464 /// `*`, `?` or `[` is expanded, its matches sorted. A directory is
465 /// refused: name its files instead. So is a pipe or device: bench needs
466 /// each file's size, so write a pipe to a file first. A file it cannot
467 /// open, a dangling symlink or an unreadable directory on the way is
468 /// refused too, naming the path.
469 #[arg(required = true, num_args = 1.., value_name = "INPUTS")]
470 pub inputs: Vec<String>,
471 /// Only these formats, comma-separated or repeated. Default: every codec
472 /// this build can write with its real encoder.
473 #[arg(long, value_name = "FORMAT", value_delimiter = ',')]
474 pub formats: Vec<String>,
475 /// Run every level of each format instead of its default level only.
476 #[arg(long)]
477 pub levels: bool,
478 /// Compress each file as its own stream instead of all of them as one.
479 #[arg(long)]
480 pub per_file: bool,
481 /// Compress with N worker threads. 0 means auto-detect.
482 ///
483 /// Threads apply to compression only: decompression is always timed
484 /// single-threaded. OMITTING this flag is not the same as passing 0:
485 /// without it, stuffr compresses single-threaded, so the same input
486 /// always produces the same bytes on any machine. Multi-threaded xz and
487 /// zstd split the input per worker, so their output depends on the
488 /// worker count. bench ignores STUFFR_THREADS: threads come only from
489 /// this flag.
490 #[arg(long)]
491 pub threads: Option<usize>,
492 /// Cap the memory stuffr will ask for, e.g. 512M or 2G.
493 ///
494 /// Input over half of it is streamed from disk rather than held in
495 /// memory. Each codec gets the output destination its own worst case
496 /// allows: a codec whose worst-case output is too large for the rest
497 /// writes to a temp file, whose writes then count in its compress time,
498 /// and its row is marked (`*`; `output: disk`). Defaults to 25%
499 /// of available RAM, honouring cgroup limits.
500 #[arg(long, value_name = "SIZE")]
501 pub memory_limit: Option<String>,
502 /// Time each row N times and report the medians.
503 #[arg(long, value_name = "N", default_value_t = 1,
504 value_parser = clap::value_parser!(u32).range(1..))]
505 pub repeat: u32,
506 /// Emit one machine-readable JSON object instead of the table.
507 #[arg(long, conflicts_with = "csv")]
508 pub json: bool,
509 /// Emit CSV, one line per row, instead of the table.
510 #[arg(long)]
511 pub csv: bool,
512 /// Print the table alone: no input line, no winners, no progress.
513 #[arg(short = 'q', long, conflicts_with_all = ["json", "csv"])]
514 pub table_only: bool,
515}