Repository and Crate Map
This repository is a Cargo workspace that packages ripgrep’s command-line application together with reusable libraries for matching, searching, filtering, and printing. The root package builds the rg binary from crates/core/main.rs and declares ten supporting workspace crates.
The split exists so the command-line program can compose specialized components while downstream users can depend on library crates directly. The grep crate is explicitly described as a fast line-oriented regex-searching library, while the root package supplies the CLI application.
Sources: crates/grep/Cargo.toml:1-23, Cargo.toml:1-15
Core concepts
Workspace
A workspace is the set of Cargo packages developed and built together; this one contains the root application and ten supporting crates.
The supporting packages are named globset, grep, grep-cli, grep-index, grep-matcher, grep-pcre2, grep-printer, grep-regex, grep-searcher, and ignore.
Sources: Cargo.toml:39-51, crates/globset/Cargo.toml:1-3, crates/grep/Cargo.toml:1-3, crates/cli/Cargo.toml:1-3, crates/index/Cargo.toml:1-4, crates/pcre2/Cargo.toml:1-3, crates/printer/Cargo.toml:1-3, crates/regex/Cargo.toml:1-3, crates/searcher/Cargo.toml:1-3, crates/ignore/Cargo.toml:1-3
Facade
A facade is a library that gathers lower-level components behind one dependency surface; grep depends on grep-cli, grep-matcher, optional grep-pcre2, grep-printer, grep-regex, and grep-searcher.
Sources: crates/grep/Cargo.toml:17-23
Matcher
A matcher is the abstraction that describes regular-expression behavior for line-oriented search; grep-matcher provides that trait-oriented package.
grep-regex uses Rust’s regex library with the grep crate and declares a dependency on grep-matcher. grep-pcre2 uses PCRE2 with the grep crate and also declares a dependency on grep-matcher.
Sources: crates/matcher/Cargo.toml:1-8, crates/regex/Cargo.toml:5-7, crates/regex/Cargo.toml:17-21, crates/pcre2/Cargo.toml:5-7, crates/pcre2/Cargo.toml:17-20
Searcher
A searcher consumes bytes from a source, applies a matcher, and reports the results to a sink; grep-searcher provides this reusable line-oriented search implementation.
Sources: crates/searcher/src/lib.rs:7-15, crates/searcher/Cargo.toml:1-9
Sink and printer
A sink receives search events, while a printer is a sink implementation that turns those events into output; grep-printer provides standard grep-like printing.
Sources: crates/searcher/src/lib.rs:25-33, crates/printer/Cargo.toml:5-8
How the workspace divides search responsibilities
The crates separate the main responsibilities of a search so the CLI does not own every implementation detail. The table below maps each package to the responsibility established by its manifest.
| Crate | Responsibility | Evidence from its package |
|---|---|---|
grep-matcher | Defines the regex-oriented matcher abstraction. | Its description calls it a trait for regular expressions focused on line-oriented search. |
grep-regex | Connects Rust’s regex implementation to the grep library. | Its description says it uses Rust’s regex library with the grep crate. |
grep-pcre2 | Connects PCRE2 to the grep library. | Its description says it uses PCRE2 with the grep crate. |
grep-searcher | Provides reusable line-oriented searching. | Its description identifies it as a line-oriented regex-searching library. |
grep-printer | Implements the grep crate’s result sink. | Its description identifies it as a Sink implementation that provides grep-like output. |
ignore | Matches ignore files against file paths. | Its description names .gitignore-style ignore-file matching. |
globset | Matches one or more glob patterns against a path. | Its description defines simultaneous glob-set matching. |
grep-cli | Supplies utilities for search-oriented command-line applications. | Its package description identifies that purpose. |
grep-index | Supplies experimental indexed searching. | Its description is “Grep, but with an index,” and the package is unpublished. |
This architecture is summarized by the following dependency map; the arrows reflect dependency declarations shown in the workspace manifests.
Evidence
- ripgrep-rootCargo.toml:1
- ripgrep-rootCargo.toml:30
- grep-facadecrates/grep/Cargo.toml:1
- matchercrates/matcher/Cargo.toml:1
- rust-regexcrates/regex/Cargo.toml:1
- pcre2-enginecrates/pcre2/Cargo.toml:1
- searchercrates/searcher/Cargo.toml:1
- printercrates/printer/Cargo.toml:1
- cli-utilscrates/cli/Cargo.toml:1
- globsetcrates/globset/Cargo.toml:1
Sources: Cargo.toml:39-51, crates/matcher/Cargo.toml:1-8, crates/regex/Cargo.toml:1-7, crates/pcre2/Cargo.toml:1-7, crates/searcher/Cargo.toml:1-9, crates/printer/Cargo.toml:1-15, crates/ignore/Cargo.toml:1-14, crates/globset/Cargo.toml:1-14, crates/cli/Cargo.toml:1-12, crates/index/Cargo.toml:1-13, Cargo.toml:57-62, crates/grep/Cargo.toml:17-23, crates/cli/Cargo.toml:17-21
How the grep facade wires a search
The facade’s dependency list is the clearest wiring contract: grep directly names grep-cli, grep-matcher, optional grep-pcre2, grep-printer, grep-regex, and grep-searcher.
At the search boundary, grep-searcher consumes bytes from a source, applies a Matcher, and reports matching or contextual lines to a Sink; this keeps matching, input consumption, and output handling separate.
Execution uses a push model: the searcher drives the operation and calls the supplied sink instead of having the caller pull results from the searcher.
The root application adds a higher-level worker around those pieces. The core search module describes that worker as managing interaction between the matcher, searcher, and printer, including preprocessing and decompression.
The selected engine is represented by PatternMatcher, whose shown variants are grep::regex::RegexMatcher and, when enabled, grep::pcre2::RegexMatcher. The high-level arguments choose the matcher through matcher(), which returns an error if building the selected matcher fails.
Sources: crates/grep/Cargo.toml:17-23, crates/searcher/src/lib.rs:7-15, crates/searcher/src/lib.rs:25-33, crates/searcher/src/sink.rs:64-75, crates/core/search.rs:1-8, crates/core/search.rs:191-197, crates/core/flags/hiargs.rs:374-380
How the CLI extends the library stack
The root package is the CLI-facing composition layer: its binary is named rg, and its entry point is run.
grep-cli provides utilities for search-oriented command-line applications and depends on globset. The root package separately declares a dependency on ignore, whose package describes matching .gitignore-style files against paths.
The root package owns application-level feature choices. The pcre2 feature enables grep/pcre2, while unstable-index optionally enables grep-index. PCRE2 is therefore an opt-in path in the root package and an optional dependency of grep.
The experimental index is separate from the ordinary search stack: grep-index is marked publish = false, and the root package makes it optional behind unstable-index.
Sources: Cargo.toml:30-33, crates/core/main.rs:69-78, crates/cli/Cargo.toml:1-8, crates/cli/Cargo.toml:17-21, Cargo.toml:57-63, crates/ignore/Cargo.toml:5-9, Cargo.toml:77-81, crates/grep/Cargo.toml:17-23, crates/index/Cargo.toml:1-4, Cargo.toml:60-62
How it connects
For the overall purpose and shape of the repository, continue to Project Overview.
For argument parsing and the transition from raw CLI input to higher-level configuration, see CLI Entry and Flag Parsing.
For runtime interaction between matcher, searcher, printer, preprocessing, and decompression, see Search Worker and I/O.
For the reusable matcher contract and Rust-regex implementation, see The Matcher Trait and Internal Iteration and The Default Rust Regex Matcher.
For the search engine’s byte consumption and sink protocol, see The Searcher Core.
For ignore filtering, glob matching, and optional indexing, see Gitignore and Override Matching, The Globset Matching Engine, and Index Integration and Feature Gating.
Sources: crates/core/main.rs:69-78, crates/core/search.rs:1-8, crates/matcher/Cargo.toml:1-8, crates/regex/Cargo.toml:1-7, crates/searcher/src/lib.rs:7-15, crates/searcher/src/sink.rs:64-75, crates/ignore/Cargo.toml:5-9, Cargo.toml:77-81
Key takeaways
- The Cargo workspace separates the CLI application from ten reusable supporting crates.
grepis the facade that wires together matchers, searcher, printer, and CLI utilities.grep-searcherperforms byte-oriented searching, while aSinkreceives its results.- Depend on
grepfor the assembled line-oriented search library, or on narrower crates such asgrep-searcherandgrep-matcherfor lower-level control. - PCRE2 and indexing are optional feature paths in the root package.
Sources: crates/grep/Cargo.toml:17-23, crates/searcher/src/lib.rs:7-15, crates/searcher/src/sink.rs:64-75, crates/grep/Cargo.toml:1-23, crates/searcher/Cargo.toml:1-9, crates/matcher/Cargo.toml:1-8, Cargo.toml:77-81