ripgrep

Active contributors: Andrew Gallant (BurntSushi), dana

Purpose

ripgrep (rg) is a line-oriented search tool that recursively walks a directory and reports lines that match a regex. By default it respects .gitignore, .ignore, and .rgignore files, skips hidden files and binary files, and uses Rust's regex crate for matching. It is written in Rust and ships as a single static binary on Windows, macOS, and Linux.

ripgrep is the public face of a workspace of nine library crates that handle directory walking, glob/gitignore matching, regex compilation, line-oriented search, and grep-style output. Most of the code in the repository is in those library crates; the rg binary itself is a relatively thin layer that parses CLI flags and wires the libraries together.

Quick links

• Architecture — how the binary, library crates, and external dependencies fit together
• Getting started — installing, building, running tests
• Glossary — domain terms used throughout the codebase
• How to contribute — development workflow, testing, debugging
• Packages — guided tour of the nine library crates
• Features — gitignore handling, file typing, decompression, PCRE2, CLI flags
• By the numbers — codebase statistics
• Lore — release timeline and historical eras

What ripgrep does

A typical invocation:

$ rg 'fn main' --type rust
crates/core/main.rs
44:fn main() -> ExitCode {

The work behind that command:

1. Parse the command line. crates/core/flags/parse.rs parses arguments using lexopt, builds a LowArgs, then converts it into a higher-level HiArgs (crates/core/flags/hiargs.rs) that carries everything the rest of ripgrep needs.
2. Build a directory walker. HiArgs constructs a WalkBuilder from the ignore crate, which respects .gitignore, .ignore, .rgignore, hidden-file rules, file-type filters, and --glob overrides.
3. Compile a matcher. crates/regex (Rust's regex engine) or crates/pcre2 (optional PCRE2) wrap a regex behind the Matcher trait from crates/matcher.
4. Search each haystack. crates/searcher reads the file (memory-mapped or buffered), applies the matcher line-by-line, and pushes matches to a Sink.
5. Print the results. crates/printer provides three sinks: Standard for human-readable colored output, JSON for machine-readable JSON Lines, and Summary for aggregate counts.

Repository layout

ripgrep/
├── Cargo.toml                 # Workspace + the rg binary package
├── crates/
│   ├── core/                  # The rg binary itself (main.rs, flags/, search.rs)
│   ├── grep/                  # Re-export facade over the other crates
│   ├── matcher/               # Generic Matcher trait
│   ├── regex/                 # Matcher impl using Rust's regex crate
│   ├── pcre2/                 # Matcher impl using PCRE2 (optional)
│   ├── searcher/              # Line-oriented search engine
│   ├── printer/               # Standard/JSON/Summary output formatters
│   ├── cli/                   # CLI utilities (decompress, escape, hostname...)
│   ├── ignore/                # Recursive walker that respects ignore rules
│   └── globset/               # Single glob + glob set matching
├── tests/                     # Integration tests against the rg binary
├── ci/                        # Release-binary build helpers
├── pkg/                       # Distribution packaging (Homebrew, etc.)
├── benchsuite/                # External benchmark harness
├── GUIDE.md                   # User-facing usage guide
├── FAQ.md                     # User-facing FAQ
├── CHANGELOG.md               # Release notes (the canonical history)
└── README.md                  # Installation + quick benchmarks

Distribution and platforms

ripgrep is distributed both as source on crates.io and as precompiled archives for Windows, macOS, and Linux on each GitHub release. Linux release binaries are statically linked against musl and use tikv-jemallocator to avoid musl's allocator. The pkg/brew directory holds the Homebrew formula. The package.metadata.deb section in Cargo.toml builds Debian packages with PCRE2 and shell completions bundled.

The minimum supported Rust version is 1.85 (declared by rust-version = "1.85" in Cargo.toml).