This document provides a high-level introduction to ripgrep, its purpose, key features, and architectural organization. It serves as an entry point for understanding the codebase structure and design philosophy.
For installation instructions, see Installation. For basic usage examples, see Basic Usage. For detailed architectural analysis of individual subsystems, see Architecture.
ripgrep (rg) is a line-oriented search tool that recursively searches directories for regex patterns while respecting ignore rules and automatically filtering out unwanted files. It is designed to be fast, correct, and user-friendly, combining features from tools like grep, ag (The Silver Searcher), and ack while delivering superior performance through Rust's regex engine and careful optimization.
Sources: Cargo.toml5-9 README.md3-9
ripgrep is implemented as a Rust workspace containing a main binary (rg) and multiple supporting library crates. The tool recursively searches the current directory for a regex pattern, automatically respecting .gitignore rules, skipping hidden files and binary files by default. This automatic filtering can be disabled with the -uuu flag for unrestricted search.
The binary is distributed as a standalone executable with first-class support for Windows, macOS, and Linux platforms. The minimum supported Rust version is 1.85.
Sources: Cargo.toml1-28 README.md1-9
This diagram bridges the natural language concepts of ripgrep's features to the specific code entities and crates that implement them.
Sources: Cargo.toml39-62 Cargo.lock161-172 Cargo.lock229-241
ripgrep implements a sophisticated multi-level filtering system that automatically excludes files based on various rules. As of version 15, it also supports a subset of Jujutsu (jj) repositories.
| Filter Type | Description | Override Flag |
|---|---|---|
.gitignore | VCS ignore rules | --no-ignore |
.ignore | General ignore file | --no-ignore |
.rgignore | ripgrep-specific rules | --no-ignore |
.jj | Jujutsu ignore rules | --no-ignore |
| Hidden files | Files starting with . | --hidden |
| Binary files | Non-text file detection | --text |
| File types | Predefined file extensions | -t TYPE / -T TYPE |
Sources: README.md4-6 README.md122-127 CHANGELOG.md42-43
ripgrep supports two regex engines through a pluggable architecture:
grep-regex): Uses Rust's regex-automata crate with finite automata and SIMD acceleration.grep-pcre2): Optional engine supporting lookaround assertions and backreferences, enabled via --pcre2 flag.Sources: README.md136-141 Cargo.toml72 Cargo.lock195-201 Cargo.lock218-226
ripgrep is organized as a Rust workspace where the main binary coordinates several specialized sub-crates.
Sources: Cargo.toml39-50 Cargo.lock161-172 Cargo.lock244-257
The codebase is organized into 9 primary member crates:
| Crate | Path | Purpose |
|---|---|---|
ripgrep | crates/core/ | Main binary entry point |
grep | crates/grep | Facade coordinating sub-crates |
grep-matcher | crates/matcher | Trait abstraction for matchers |
grep-regex | crates/regex | Default regex implementation |
grep-pcre2 | crates/pcre2 | Optional PCRE2 backend |
grep-searcher | crates/searcher | File searching logic |
grep-printer | crates/printer | Output formatting |
ignore | crates/ignore | Directory walking & filtering |
globset | crates/globset | Glob pattern matching |
For details, see Workspace and Crate Structure.
Sources: Cargo.toml39-50
ripgrep achieves high performance through multiple techniques:
memchr crate for fast byte searching Cargo.lock294-297memmap2 for single large files Cargo.lock300-306crossbeam Cargo.lock59-90grep-regex CHANGELOG.md143-144Sources: README.md188-209 Cargo.lock294-306
ripgrep provides native builds for multiple platforms. Recent versions (v15+) have added aarch64 support for Windows while removing powerpc64 due to CI limitations.
| Platform | Architectures |
|---|---|
| Linux | x86_64, aarch64, arm, riscv64, s390x |
| macOS | x86_64, aarch64 |
| Windows | x86_64, i686, aarch64 |
Sources: README.md7-8 CHANGELOG.md48-52
ripgrep uses a build.rs script for build-time code generation, such as generating man pages and shell completions. The release process is optimized using LTO (Link Time Optimization) for performance and smaller binary sizes.
Sources: Cargo.toml25 Cargo.toml77-87 CHANGELOG.md53-55