# Contributor handoff — BurntSushi/ripgrep

> Canonical page: https://codevetter.com/unpack/ripgrep/agent-handoff

# Contributor handoff — BurntSushi/ripgrep

Scanned commit 3fce3b5bb0236da2df6d99672afb8a719642eca7 (2026-08-04). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [AI_POLICY.md#L1-L25](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/AI_POLICY.md#L1-L25) [CONTRIBUTING.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/CONTRIBUTING.md)
- 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`). — [crates/core/main.rs](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/main.rs) [crates/core/flags/mod.rs](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/mod.rs) [crates/core/flags/hiargs.rs](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/hiargs.rs) [crates/core/search.rs](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/search.rs)
- 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. — [crates/core/README.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/README.md)
- Formatting convention is strict and narrow: `max_width = 79`, `use_small_heuristics = "max"`, `edition = "2024"`; the `rustfmt` CI job runs `cargo fmt --all --check`. — [rustfmt.toml](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/rustfmt.toml) [.github/workflows/ci.yml#L215-L225](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/.github/workflows/ci.yml#L215-L225)
- 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`. — [crates/core/flags/mod.rs#L72-L177](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/mod.rs#L72-L177) [crates/core/flags/defs.rs#L38-L90](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/defs.rs#L38-L90) [crates/core/flags/lowargs.rs#L33-L60](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/lowargs.rs#L33-L60)
- 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. — [crates/core/flags/parse.rs#L128-L140](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/parse.rs#L128-L140)
- 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. — [crates/core/flags/mod.rs#L152-L177](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/mod.rs#L152-L177)
- 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. — [README.md#L507-L517](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/README.md#L507-L517) [.github/workflows/ci.yml#L155-L187](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/.github/workflows/ci.yml#L155-L187) [ci/test-complete](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/ci/test-complete)
- 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. — [tests/util.rs#L45-L110](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/tests/util.rs#L45-L110)
- 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. — [crates/core/flags/defs.rs#L8026-L8100](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/defs.rs#L8026-L8100) [crates/core/flags/mod.rs#L76-L96](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/mod.rs#L76-L96)
- 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. — [crates/core/flags/hiargs.rs#L178-L184](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/hiargs.rs#L178-L184) [crates/core/flags/hiargs.rs#L918-L926](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/hiargs.rs#L918-L926)
- 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. — [crates/core/flags/hiargs.rs#L644-L660](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/flags/hiargs.rs#L644-L660) [crates/core/main.rs#L176-L200](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/core/main.rs#L176-L200)
- 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. — [crates/ignore/src/lib.rs#L46-L48](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/ignore/src/lib.rs#L46-L48) [crates/printer/src/lib.rs#L60-L62](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/crates/printer/src/lib.rs#L60-L62) [Cargo.toml#L59-L70](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/Cargo.toml#L59-L70)
- 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`. — [RELEASE-CHECKLIST.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/RELEASE-CHECKLIST.md) [Cargo.toml#L3](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/Cargo.toml#L3) [.github/workflows/release.yml#L30-L36](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/.github/workflows/release.yml#L30-L36)
- 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. — [GUIDE.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/GUIDE.md) [FAQ.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/FAQ.md) [CHANGELOG.md](https://github.com/BurntSushi/ripgrep/blob/3fce3b5bb0236da2df6d99672afb8a719642eca7/CHANGELOG.md)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)