CodeVetter · Repo Unpack · Contributor handoff
BurntSushi/ripgrep
Read `crates/core/main.rs`, `crates/core/flags/mod.rs` and `crates/core/flags/hiargs.rs` first — they define the whole control flow and the low→high argument split that every other decision hangs off. Formatting is enforced (`rustfmt.toml`: `max_width = 79`, `use_small_heuristics = "max"`, edition 2024) and CI fails on `cargo fmt --all --check`, so run rustfmt before proposing a diff. Most changes that touch the CLI require edits in three coordinated places: the `Flag` impl, the `FLAGS` slice, and the corresponding `LowArgs`/`HiArgs` fields. Note the repository's `AI_POLICY.md`: autonomous agents are explicitly barred from contributing upstream, and AI-written comments to maintainers may be hidden — treat this repo as read/analyze-friendly but do not open PRs or issues on it autonomously.
- `AI_POLICY.md` states "Autonomous agents are not allowed to be used for contributing to this project" and that PRs appearing in violation will be closed, possibly without notice; `CONTRIBUTING.md` says contributions not following it will be closed.
- Read first, in order: `crates/core/main.rs` (dispatch), `crates/core/flags/mod.rs` (the `Flag` trait and `Category`), `crates/core/flags/hiargs.rs` (`from_low_args` and every builder accessor), `crates/core/search.rs` (`SearchWorker`).
- The core crate's own README warns it is not a library and is "glue code that brings the grep-matcher, grep-regex, grep-searcher and grep-printer crates together" — behavior changes usually belong in a `crates/*` library, not in core.
- Formatting convention is strict and narrow: `max_width = 79`, `use_small_heuristics = "max"`, `edition = "2024"`; the `rustfmt` CI job runs `cargo fmt --all --check`.
- Adding a flag requires: a unit struct implementing `Flag` (with `doc_long` in mdoc format), an entry in `FLAGS` at the right position for doc ordering, a field in `LowArgs`, and usually a matching field/accessor in `HiArgs`.
- Per-flag tests use `parse_low_raw([...])`, a `#[cfg(test)]`-only helper that runs the parser once with no logging and no config file — the right tool for asserting flag parsing without touching the environment.
- By convention `Flag::update` must only validate, never act: the trait docs use `--hostname-bin` as the example of work that must be deferred so it happens once, later.
- Tests to run: `cargo test --all` for the full suite, `cargo test --features pcre2` to double-run integration tests under PCRE2, `cargo test --workspace --features unstable-index` for index tests, and `ci/test-complete` for zsh completions.
- Integration tests create real files in a temp dir and run the built `rg` binary — they are not hermetic against the host, and `cmd_exists` gating means missing `gzip`/`xz` silently reduces coverage rather than failing.
- Trap: `Flag::name_long` must be ≥2 ASCII alphanumeric/`-` characters and short flags must be unique ASCII alphanumeric or `.`; violating either fails `longs_all_ascii_alphanumeric`/`shorts_no_duplicates` rather than failing to compile.
- Trap: changing thread-count derivation can trip `assert_eq!(1, self.threads, "sorting implies single threaded")` in `walk_builder`, because `--sort` and parallelism are mutually exclusive by construction.
- Trap: in parallel mode the printer must not own the file separator — `printer_standard` only calls `separator_search` when `self.threads == 1`, because the `BufferWriter` owns separator logic otherwise.
- Safe edit boundary: the `ignore`, `globset`, `grep-cli`, `grep-matcher`, `grep-printer`, `grep-regex` and `grep-searcher` crates are published to crates.io with independent versions and `#![deny(missing_docs)]`, so any new public item needs a doc comment or `cargo doc -D warnings` fails.
- Release hygiene: `RELEASE-CHECKLIST.md` and the `#:version` marker comments next to each crate version are the mechanism for coordinated version bumps; the release workflow hard-fails if the git tag doesn't match `Cargo.toml`.
- User-facing documentation that needs updating alongside behavior changes lives in `GUIDE.md` (usage guide), `FAQ.md` and `CHANGELOG.md` (90KB, maintained per release), not in generated help alone.