1use std::ffi::OsString;
5use std::path::PathBuf;
6
7use crate::{print, search};
8
9pub const HELP: &str = "\
10trg — search inside compressed log archives
11(.tgz, .tar.zst, .tar.xz, .tar.bz2, .tar.lz4, .tar.Z, .zip)
12
13USAGE:
14 trg [OPTIONS] PATTERN PATH...
15 trg [OPTIONS] -e PATTERN... PATH...
16 trg [OPTIONS] -T PATH...
17
18At least one PATH is required. trg never searches the current directory by
19default: a silent walk of $PWD is not a safe guess for a tool whose exit 1
20is a claim that the logs are clean.
21
22MATCHING (same meaning as ripgrep):
23 -e, --regexp PAT add a pattern; repeatable
24 -i, --ignore-case case-insensitive
25 -S, --smart-case case-insensitive unless the pattern has uppercase
26 -w, --word-regexp match whole words only
27 -F, --fixed-strings treat patterns as literals
28 -v, --invert-match show non-matching lines
29 -a, --text search members that look binary
30 -m, --max-count NUM stop after NUM matches per member
31 --crlf treat CRLF as the line terminator
32
33OUTPUT (same meaning as ripgrep):
34 -n, --line-number show line numbers (default)
35 -N, --no-line-number hide line numbers
36 -A, --after NUM lines of trailing context
37 -B, --before NUM lines of leading context
38 -C, --context NUM lines of context on both sides
39 -o, --only-matching print only the matching part
40 -c, --count print a count per member
41 -l, --files-with-matches
42 print member paths only
43 -q, --quiet print nothing; exit code only
44 --json JSON Lines output
45 --color WHEN auto | always | never (auto: only on a tty)
46 --escape WHEN show control bytes from logs and member names as
47 text (\\x1b) instead of sending them to the
48 terminal: auto | always | never (auto: on a tty,
49 per stream; piped output stays byte-exact)
50 If several output modes are given, the most
51 suppressive wins: -q, then -l, then -c, then --json.
52
53ARCHIVES:
54 -g, --glob PAT filter MEMBERS inside archives; repeatable. Without
55 a `/` it also matches the member's file name. A
56 leading ! excludes; the last matching glob wins
57 --archive-glob PAT
58 when walking a directory, search only the archives
59 matching PAT; repeatable. Without a `/` it matches
60 the file name at any depth, with one the path below
61 the directory named. Files named explicitly are
62 always searched. A leading ! excludes, as for -g.
63 Matching nothing is exit 2
64 -T, --list-members list member paths without searching. Takes no
65 PATTERN at all: every positional is a PATH, so
66 `trg -T *.tgz` lists all of them
67 --archive-sep C separator in archive:member:line (default ':')
68 --no-sort allow output in completion order
69
70RESOURCES:
71 -j, --jobs NUM archives searched concurrently (default 1)
72 --turbo -j <ncpus> --nice 0
73 --nice NUM scheduling priority (default 10)
74 --no-nice do not lower priority
75 --no-drop-cache keep archive pages in the page cache
76 --load-limit N run one job at a time while the 1-min load average
77 from other processes exceeds N, and add jobs back
78 as it falls. Rechecked every 5 s
79
80 -h, --help this message
81 -V, --version version
82
83EXIT CODES:
84 0 matches found, everything read
85 1 no matches, everything read
86 2 something went unread — never trust a 1 you did not get
87
88NOTES (documented, and surprising the first time):
89 -T lists every member, including ones a search skips as binary.
90 Two directories symlinking the same file search it once (identity dedup).
91 An intact archive behind a corrupt gzip trailer is a 0; truncation is
92 still caught and is a 2.
93 --turbo's ordered output is not bounded by the spill cap; peak RSS grows
94 with the match volume held in order.
95 On a broken pipe (`| head`) trg stops early and exits 0, leaving later
96 archives unread.
97 Compression is detected from content, never from the filename, so there is
98 no -z flag. gzip, zstd, xz, bzip2 and lz4 are recognised, each unwrapped
99 one level, so a logrotate'd access.log.1.gz, .zst, .xz, .bz2 or .lz4
100 inside the archive is searched as text rather than skipped as binary.
101 .Z (compress) is read too, but only as a whole file: a .Z member
102 inside an archive is reported unread, a 2.
103 A zip's members are searched like a tar's, compressed ones included. A
104 zip or tar inside another archive is searched as bytes, not opened.
105 .Z has no length and no checksum, so a truncated .Z reads as a shorter
106 file with no error. A .Z with no match is still a 1, with a note on
107 stderr that the file could not vouch for its own end.
108 --inflate and --inflate-budget are accepted and ignored since 0.7.0, with
109 a note on stderr: trg always streams.
110";
111
112#[derive(Debug, Clone, Copy, PartialEq, Eq)]
113pub enum ColorArg { Auto, Always, Never }
114
115pub struct Args {
116 pub patterns: Vec<String>,
117 pub paths: Vec<PathBuf>,
118 pub globs: Vec<String>,
119 pub archive_globs: Vec<String>,
120 pub jobs: usize,
121 pub nice: Option<i32>,
122 pub drop_cache: bool,
123 pub deprecated: Vec<&'static str>,
126 pub load_limit: Option<f64>,
127 pub archive_sep: char,
128 pub sort: bool,
129 pub list_members: bool,
130 pub count: bool,
131 pub files_with_matches: bool,
132 pub quiet: bool,
133 pub json: bool,
134 pub color: ColorArg,
135 pub escape: ColorArg,
136 pub search: search::SearchOpts,
137 pub print: print::PrintOpts,
138}
139
140impl Default for Args {
141 fn default() -> Self {
142 Self {
143 patterns: Vec::new(),
144 paths: Vec::new(),
145 globs: Vec::new(),
146 archive_globs: Vec::new(),
147 jobs: 1,
148 nice: Some(10),
149 drop_cache: true,
150 deprecated: Vec::new(),
151 load_limit: None,
152 archive_sep: ':',
153 sort: true,
154 list_members: false,
155 count: false,
156 files_with_matches: false,
157 quiet: false,
158 json: false,
159 color: ColorArg::Auto,
160 escape: ColorArg::Auto,
161 search: search::SearchOpts::default(),
162 print: print::PrintOpts::default(),
163 }
164 }
165}
166
167fn parse_size(s: &str) -> anyhow::Result<u64> {
169 let s = s.trim();
170 let (num, mult) = match s.chars().last() {
171 Some('K') | Some('k') => (&s[..s.len() - 1], 1024),
172 Some('M') | Some('m') => (&s[..s.len() - 1], 1024 * 1024),
173 Some('G') | Some('g') => (&s[..s.len() - 1], 1024 * 1024 * 1024),
174 _ => (s, 1),
175 };
176 let n: u64 = num.parse()?;
177 n.checked_mul(mult)
178 .ok_or_else(|| anyhow::anyhow!("--inflate-budget value too large: {s}"))
179}
180
181fn deprecate(a: &mut Args, flag: &'static str) {
182 if !a.deprecated.contains(&flag) {
183 a.deprecated.push(flag);
184 }
185}
186
187pub fn parse() -> anyhow::Result<Args> {
188 parse_from(std::env::args_os())
189}
190
191pub fn parse_from<I>(argv: I) -> anyhow::Result<Args>
192where
193 I: IntoIterator<Item = OsString>,
194{
195 use lexopt::prelude::*;
196
197 let mut a = Args::default();
198 let mut explicit_jobs = false;
199 let mut explicit_nice = false;
200 let mut ctx_both: Option<usize> = None;
201 let mut positionals: Vec<OsString> = Vec::new();
205 let mut explicit_patterns = false;
206
207 let mut p = lexopt::Parser::from_iter(argv);
208 while let Some(arg) = p.next()? {
209 match arg {
210 Short('e') | Long("regexp") => {
211 a.patterns.push(p.value()?.string()?);
212 explicit_patterns = true;
213 }
214 Short('i') | Long("ignore-case") => a.search.case_insensitive = true,
215 Short('S') | Long("smart-case") => a.search.smart_case = true,
216 Short('w') | Long("word-regexp") => a.search.word = true,
217 Short('F') | Long("fixed-strings") => a.search.fixed = true,
218 Short('v') | Long("invert-match") => a.search.invert = true,
219 Short('a') | Long("text") => a.search.text = true,
220 Short('m') | Long("max-count") => {
221 a.search.max_count = Some(p.value()?.parse()?)
222 }
223 Long("crlf") => a.search.crlf = true,
224
225 Short('n') | Long("line-number") => a.search.line_numbers = true,
226 Short('N') | Long("no-line-number") => a.search.line_numbers = false,
227 Short('A') | Long("after") | Long("after-context") => {
228 a.search.after = p.value()?.parse()?
229 }
230 Short('B') | Long("before") | Long("before-context") => {
231 a.search.before = p.value()?.parse()?
232 }
233 Short('C') | Long("context") => ctx_both = Some(p.value()?.parse()?),
234 Short('o') | Long("only-matching") => a.print.only_matching = true,
235 Short('c') | Long("count") => a.count = true,
236 Short('l') | Long("files-with-matches") => a.files_with_matches = true,
237 Short('q') | Long("quiet") => a.quiet = true,
238 Long("json") => a.json = true,
239 Long("color") => {
240 a.color = match p.value()?.string()?.as_str() {
241 "auto" => ColorArg::Auto,
242 "always" => ColorArg::Always,
243 "never" => ColorArg::Never,
244 other => anyhow::bail!("--color expects auto|always|never, got '{other}'"),
245 }
246 }
247 Long("escape") => {
248 a.escape = match p.value()?.string()?.as_str() {
249 "auto" => ColorArg::Auto,
250 "always" => ColorArg::Always,
251 "never" => ColorArg::Never,
252 other => anyhow::bail!("--escape expects auto|always|never, got '{other}'"),
253 }
254 }
255
256 Short('g') | Long("glob") => a.globs.push(p.value()?.string()?),
257 Long("archive-glob") => a.archive_globs.push(p.value()?.string()?),
258 Short('T') | Long("list-members") => a.list_members = true,
259 Long("archive-sep") => {
260 let v = p.value()?.string()?;
261 let mut it = v.chars();
262 match (it.next(), it.next()) {
263 (Some(c), None) => a.archive_sep = c,
264 _ => anyhow::bail!("--archive-sep expects exactly one character"),
265 }
266 }
267 Long("no-sort") => a.sort = false,
268
269 Short('j') | Long("jobs") => {
270 a.jobs = p.value()?.parse()?;
271 explicit_jobs = true;
272 }
273 Long("turbo") => {
274 if !explicit_jobs { a.jobs = num_cpus::get(); }
275 if !explicit_nice { a.nice = Some(0); }
276 }
277 Long("nice") => {
278 a.nice = Some(p.value()?.parse()?);
279 explicit_nice = true;
280 }
281 Long("no-nice") => {
282 a.nice = None;
283 explicit_nice = true;
284 }
285 Long("no-drop-cache") => a.drop_cache = false,
286 Long("inflate") => {
291 match p.value()?.string()?.as_str() {
292 "auto" | "stream" | "buffer" => {}
293 other => anyhow::bail!("--inflate expects auto|stream|buffer, got '{other}'"),
294 }
295 deprecate(&mut a, "--inflate");
296 }
297 Long("inflate-budget") => {
298 parse_size(&p.value()?.string()?)?;
299 deprecate(&mut a, "--inflate-budget");
300 }
301 Long("load-limit") => a.load_limit = Some(p.value()?.parse()?),
302
303 Short('h') | Long("help") => {
304 print!("{HELP}");
305 std::process::exit(0);
306 }
307 Short('V') | Long("version") => {
308 println!("trg {}", env!("CARGO_PKG_VERSION"));
309 std::process::exit(0);
310 }
311
312 Value(v) => positionals.push(v),
313 other => return Err(other.unexpected().into()),
314 }
315 }
316
317 if let Some(n) = ctx_both {
320 a.search.before = n;
321 a.search.after = n;
322 }
323 a.print.mode = if a.quiet {
328 print::Mode::Quiet
329 } else if a.files_with_matches {
330 print::Mode::FilesWithMatches
331 } else if a.count {
332 print::Mode::Count
333 } else if a.json {
334 print::Mode::Json
335 } else {
336 print::Mode::Standard
337 };
338
339 let mut rest = positionals.into_iter();
353 if !a.list_members
354 && !explicit_patterns
355 && let Some(first) = rest.next()
356 {
357 a.patterns.push(first.string()?);
358 }
359 a.paths.extend(rest.map(PathBuf::from));
360
361 if a.patterns.is_empty() && !a.list_members {
363 anyhow::bail!("no pattern given\n\n{HELP}");
364 }
365 if a.paths.is_empty() {
373 anyhow::bail!("no path given: name at least one archive or directory\n\n{HELP}");
374 }
375 Ok(a)
376}
377
378#[cfg(test)]
379mod tests {
380 use super::*;
381
382 fn p(args: &[&str]) -> Args {
383 let argv: Vec<std::ffi::OsString> =
384 std::iter::once("trg".into()).chain(args.iter().map(|s| s.into())).collect();
385 parse_from(argv).unwrap()
386 }
387
388 #[test]
389 fn defaults_match_the_spec() {
390 let a = p(&["pat", "f.tgz"]);
391 assert_eq!(a.jobs, 1);
392 assert_eq!(a.nice, Some(10));
393 assert!(a.drop_cache);
394 assert!(a.deprecated.is_empty());
395 assert_eq!(a.archive_sep, ':');
396 assert!(a.sort);
397 assert_eq!(a.search.heap_limit, 16 * 1024 * 1024);
398 assert!(a.load_limit.is_none());
399 }
400
401 #[test]
402 fn first_positional_is_the_pattern_rest_are_paths() {
403 let a = p(&["NEEDLE", "a.tgz", "b.tgz"]);
404 assert_eq!(a.patterns, vec!["NEEDLE"]);
405 assert_eq!(a.paths.len(), 2);
406 }
407
408 #[test]
409 fn dash_e_patterns_do_not_consume_the_first_positional() {
410 let a = p(&["-e", "one", "-e", "two", "a.tgz"]);
411 assert_eq!(a.patterns, vec!["one", "two"]);
412 assert_eq!(a.paths.len(), 1);
413 }
414
415 #[test]
416 fn turbo_raises_jobs_and_clears_nice() {
417 let a = p(&["--turbo", "pat", "f.tgz"]);
418 assert_eq!(a.jobs, num_cpus::get());
419 assert_eq!(a.nice, Some(0));
420 assert!(a.drop_cache, "cache dropping stays on under --turbo");
421 }
422
423 #[test]
424 fn explicit_j_after_turbo_wins() {
425 let a = p(&["--turbo", "-j", "2", "pat", "f.tgz"]);
426 assert_eq!(a.jobs, 2);
427 }
428
429 #[test]
430 fn no_nice_disables_priority_lowering() {
431 let a = p(&["--no-nice", "pat", "f.tgz"]);
432 assert_eq!(a.nice, None);
433 }
434
435 #[test]
436 fn context_flags_match_rg_semantics() {
437 let a = p(&["-C", "3", "pat", "f.tgz"]);
438 assert_eq!((a.search.before, a.search.after), (3, 3));
439 let a = p(&["-A", "2", "-B", "1", "pat", "f.tgz"]);
440 assert_eq!((a.search.before, a.search.after), (1, 2));
441 }
442
443 #[test]
444 fn n_capital_disables_line_numbers() {
445 assert!(p(&["pat", "f.tgz"]).search.line_numbers);
446 assert!(!p(&["-N", "pat", "f.tgz"]).search.line_numbers);
447 }
448
449 #[test]
450 fn size_suffixes_parse() {
451 assert_eq!(parse_size("512K").unwrap(), 512 * 1024);
452 assert_eq!(parse_size("2M").unwrap(), 2 * 1024 * 1024);
453 assert_eq!(parse_size("1G").unwrap(), 1024 * 1024 * 1024);
454 assert_eq!(parse_size("1024").unwrap(), 1024);
455 assert_eq!(p(&["--inflate-budget", "1G", "p", "f"]).deprecated, ["--inflate-budget"]);
456 }
457
458 #[test]
459 fn globs_accumulate() {
460 let a = p(&["-g", "*.access.log", "-g", "*.error.log", "pat", "f.tgz"]);
461 assert_eq!(a.globs.len(), 2);
462 }
463
464 #[test]
465 fn archive_sep_is_configurable() {
466 assert_eq!(p(&["--archive-sep", "!", "pat", "f.tgz"]).archive_sep, '!');
467 }
468
469 #[test]
470 fn unknown_flag_is_an_error_not_a_pattern() {
471 let argv: Vec<std::ffi::OsString> =
472 ["trg", "--nonsense", "pat", "f.tgz"].iter().map(|s| s.into()).collect();
473 assert!(parse_from(argv).is_err());
474 }
475
476 #[test]
477 fn inflate_mode_rejects_garbage() {
478 let argv: Vec<std::ffi::OsString> =
479 ["trg", "--inflate", "sideways", "p", "f"].iter().map(|s| s.into()).collect();
480 assert!(parse_from(argv).is_err());
481 }
482
483 #[test]
484 fn crlf_flag_sets_the_search_opt_and_defaults_to_false() {
485 assert!(!p(&["pat", "f.tgz"]).search.crlf);
486 assert!(p(&["--crlf", "pat", "f.tgz"]).search.crlf);
487 }
488
489 #[test]
490 fn inflate_budget_overflow_is_an_error_not_a_wrapped_value() {
491 let argv: Vec<std::ffi::OsString> =
492 ["trg", "--inflate-budget", "18446744073709551615G", "p", "f"]
493 .iter().map(|s| s.into()).collect();
494 assert!(parse_from(argv).is_err());
495 }
496
497 #[test]
498 fn output_mode_precedence_is_most_suppressive_wins() {
499 assert_eq!(p(&["pat", "f"]).print.mode, print::Mode::Standard);
500 assert_eq!(p(&["-c", "pat", "f"]).print.mode, print::Mode::Count);
501 assert_eq!(p(&["-l", "pat", "f"]).print.mode, print::Mode::FilesWithMatches);
502 assert_eq!(p(&["-q", "pat", "f"]).print.mode, print::Mode::Quiet);
503 assert_eq!(p(&["--json", "pat", "f"]).print.mode, print::Mode::Json);
504 assert_eq!(p(&["-c", "-l", "pat", "f"]).print.mode, print::Mode::FilesWithMatches);
505 assert_eq!(p(&["-c", "-l", "-q", "pat", "f"]).print.mode, print::Mode::Quiet);
506 assert_eq!(p(&["--json", "-c", "pat", "f"]).print.mode, print::Mode::Count);
507 }
508
509 #[test]
510 fn color_parses_all_three_and_rejects_the_rest() {
511 assert_eq!(p(&["pat", "f"]).color, ColorArg::Auto);
512 assert_eq!(p(&["--color", "always", "pat", "f"]).color, ColorArg::Always);
513 assert_eq!(p(&["--color", "never", "pat", "f"]).color, ColorArg::Never);
514 let argv: Vec<std::ffi::OsString> =
515 ["trg", "--color", "nonsense", "pat", "f"].iter().map(|s| s.into()).collect();
516 assert!(parse_from(argv).is_err());
517 }
518
519 #[test]
524 fn dash_t_with_one_positional_takes_it_as_a_path_not_a_pattern() {
525 let a = p(&["-T", "archive.tgz"]);
526 assert!(a.patterns.is_empty(), "-T needs no pattern, got {:?}", a.patterns);
527 assert_eq!(a.paths, vec![PathBuf::from("archive.tgz")]);
528 }
529
530 #[test]
534 fn dash_t_takes_every_positional_as_a_path() {
535 let a = p(&["-T", "a.tgz", "b.tgz", "c.tgz"]);
536 assert!(a.patterns.is_empty(), "-T takes no pattern, got {:?}", a.patterns);
537 assert_eq!(
538 a.paths,
539 vec![PathBuf::from("a.tgz"), PathBuf::from("b.tgz"), PathBuf::from("c.tgz")]
540 );
541 }
542
543 #[test]
546 fn dash_t_after_the_positionals_parses_the_same() {
547 let a = p(&["a.tgz", "b.tgz", "-T"]);
548 assert!(a.patterns.is_empty(), "got {:?}", a.patterns);
549 assert_eq!(a.paths, vec![PathBuf::from("a.tgz"), PathBuf::from("b.tgz")]);
550 }
551
552 #[test]
556 fn an_explicit_e_makes_every_positional_a_path_whatever_the_order() {
557 let a = p(&["a.tgz", "-e", "pat", "b.tgz"]);
558 assert_eq!(a.patterns, vec!["pat"]);
559 assert_eq!(a.paths, vec![PathBuf::from("a.tgz"), PathBuf::from("b.tgz")]);
560 }
561
562 #[test]
565 fn dash_t_with_an_explicit_e_pattern_keeps_both() {
566 let a = p(&["-T", "-e", "pat", "archive.tgz"]);
567 assert_eq!(a.patterns, vec!["pat"]);
568 assert_eq!(a.paths, vec![PathBuf::from("archive.tgz")]);
569 }
570
571 fn err(args: &[&str]) -> String {
572 let argv: Vec<std::ffi::OsString> =
573 std::iter::once("trg".into()).chain(args.iter().map(|s| s.into())).collect();
574 match parse_from(argv) {
575 Ok(_) => panic!("expected a usage error, got a parse"),
576 Err(e) => format!("{e:#}"),
577 }
578 }
579
580 #[test]
583 fn a_missing_pattern_is_still_an_error_without_dash_t() {
584 assert!(err(&[]).contains("no pattern given"));
585 assert!(err(&["-e", "pat"]).contains("no path given"), "pattern present, path missing");
586 }
587
588 #[test]
592 fn a_missing_path_is_a_usage_error_not_an_empty_clean_run() {
593 assert!(err(&["needle"]).contains("no path given"), "pattern with no path");
594 assert!(err(&["-T"]).contains("no path given"), "-T with no path");
595 assert!(err(&["-q", "needle"]).contains("no path given"), "-q must not hide it");
596 }
597
598 #[test]
602 fn one_positional_is_the_pattern_and_leaves_no_path() {
603 assert!(err(&["archive.tgz"]).contains("no path given"));
604 }
605
606 #[test]
607 fn inflate_budget_accepts_u64_max_with_no_suffix() {
608 assert_eq!(parse_size(&u64::MAX.to_string()).unwrap(), u64::MAX);
609 }
610
611 #[test]
612 fn inflate_budget_accepts_a_large_value_with_a_suffix_just_under_the_boundary() {
613 let n = u64::MAX / (1024 * 1024 * 1024);
615 assert_eq!(parse_size(&format!("{n}G")).unwrap(), n * 1024 * 1024 * 1024);
616 }
617}