Project Overview

ripgrep is a command-line tool for recursively searching files for regular-expression patterns. Its executable is named rg, and a normal search respects ignore rules while skipping hidden and binary files by default.

The project exists to provide a fast, code-oriented alternative to tools such as grep, The Silver Searcher, and ack, while retaining broad search features, Unicode support, filtering, and optional PCRE2 syntax. Its speed comes from the Rust regex engine, literal optimizations, SIMD, automatic choice between memory maps and buffered reads, simultaneous ignore-pattern matching, and parallel directory traversal.

Sources: README.md:1-9

Core concepts

Recursive code search

Recursive code search means searching the current directory and its contents when no explicit path is supplied. rg foo is equivalent to rg foo./, while specifying a directory narrows the search to that directory, as in the example that searches src instead of both src and termcolor.

Sources: GUIDE.md:117-123, GUIDE.md:153-169

Automatic filtering

Automatic filtering means ripgrep excludes ignored paths, hidden files and directories, binary files, and symbolic links during recursive directory searches unless flags change that behavior.

Sources: GUIDE.md:174-209

Regex engine

A regex engine turns a pattern into the matching behavior used against file contents. ripgrep normally uses Rust’s regex engine and can optionally use PCRE2 for features such as look-around and backreferences.

Sources: README.md:136-141, README.md:188-197

Search worker

A search worker is the high-level coordinator between the matcher, the searcher, and the printer; it is also where preprocessing and decompression happen.

Sources: crates/core/search.rs:1-8

Cargo workspace

A Cargo workspace is the collection of crates that build the binary and its reusable search libraries. The workspace includes crates for the CLI, glob matching, the grep facade, indexing, matching, PCRE2, printing, Rust regex integration, searching, and ignore rules.

The main pieces are:

Sources: Cargo.toml:39-51, crates/cli/Cargo.toml:1-8, crates/grep/Cargo.toml:1-8, crates/matcher/Cargo.toml:1-8, crates/regex/Cargo.toml:1-8, crates/pcre2/Cargo.toml:1-8, crates/searcher/Cargo.toml:1-8, crates/printer/Cargo.toml:1-8, crates/ignore/Cargo.toml:1-8, crates/globset/Cargo.toml:1-8

How the binary is shaped

The binary is declared as rg and points at crates/core/main.rs; the root package depends on the grep, ignore, and optional grep-index crates. The CLI module owns flag and positional-argument parsing, configuration-file reading, validation, help and completion generation, and the connections between flags and supporting libraries.

The important boundary is that the CLI does not itself define all search behavior: it connects user-facing flags to supporting libraries, while the search worker coordinates matching, reading, and output.

Sources: Cargo.toml:30-33, Cargo.toml:57-67, crates/core/flags/mod.rs:1-10, crates/core/search.rs:1-8

How a root search gets started

When you run rg pattern without a path, the user-facing behavior first supplies the current directory as the search target. The internal Paths representation guarantees at least one path and records whether that path was implicit, which affects path formatting.

The pattern is also resolved during high-level argument construction: if no -e/--regexp or -f/--file pattern was supplied, the first positional argument becomes the pattern when ripgrep is operating in search mode. The root package then passes the resulting ParseResult<HiArgs> into run, whose documentation identifies it as the main entry point for ripgrep’s ordinary behavior.

This is the precise starting point visible in the supplied code: command input is converted into high-level arguments, including a pattern and at least one path, and those arguments reach run. The excerpts do not expose the later traversal call, so the page does not assign a more specific search-start function.

Sources: GUIDE.md:153-155, crates/core/flags/hiargs.rs:1087-1102, crates/core/flags/hiargs.rs:1019-1031, crates/core/main.rs:69-78

Why searches are fast

The default matcher is fast because Rust’s regex engine uses finite automata, SIMD, and literal optimizations, while integrating UTF-8 decoding into its deterministic finite automaton. ripgrep also chooses between memory maps and incremental buffered searching: memory maps suit single files, while buffered reads suit large directories.

Directory filtering is similarly optimized: ignore patterns can be matched against a path simultaneously, and recursive traversal uses a lock-free parallel iterator provided by crossbeam and ignore. The globset crate describes the corresponding abstraction as matching one or more glob patterns against one candidate path and returning all matching globs.

These optimizations preserve ripgrep’s default code-search behavior: recursive search, ignore-aware filtering, hidden-file exclusion, and binary-file exclusion. Binary detection is based on a NUL byte, and recursive searches normally stop treating such files as ordinary text unless the relevant flags change that behavior.

Sources: README.md:188-197, README.md:198-201, README.md:202-208, crates/globset/Cargo.toml:1-8, README.md:122-127, crates/core/flags/defs.rs:524-552

How it connects

For the workspace split and the grep facade’s wiring, continue with Repository and Crate Map. For parsing raw arguments and configuration input, see CLI Entry and Flag Parsing. For the matcher/searcher/printer hand-off, see Search Worker and I/O and The Searcher Core.

The matching implementations are detailed in The Matcher Trait and Internal Iteration, The Default Rust Regex Matcher, and The PCRE2 Matcher. Filtering and traversal continue in Gitignore and Override Matching, The Globset Matching Engine, and Parallel Directory Traversal. Output behavior is covered by Output Printers and Printer Color, Hyperlinks, and Stats.

Key takeaways

• ripgrep is the rg binary for fast recursive regex search with filtering enabled by default.
• The Cargo workspace separates CLI handling, matching, searching, printing, glob matching, and ignore processing into reusable crates.
• rg pattern supplies an implicit current-directory path and resolves pattern before entering run.
• Speed comes from regex optimizations, adaptive file reading, simultaneous glob matching, and parallel traversal.

Sources: README.md:1-9, Cargo.toml:39-51, GUIDE.md:153-155, crates/core/main.rs:69-78, README.md:188-208