ripgrep — Administrator & Developer Guide

ripgrep (rg) is a line-oriented search tool that recursively searches directories for regex patterns while respecting ignore files. Written in Rust by Andrew Gallant, it combines the usability of grep -r with the speed of a purpose-built search engine. This guide covers architecture, configuration, deployment, performance tuning, security considerations, and developer internals for administrators, packagers, and contributors.

Version covered: ripgrep 15.1.0 | License: MIT OR Unlicense (dual) | MSRV: Rust 1.85.0 | Edition: 2024

For everyday usage, flag examples, and workflow recipes, see the User Guide.

1. Architecture Overview

1.1 Workspace Structure

ripgrep is a Rust workspace containing one binary crate and eight library crates. Each library crate is independently versioned and publishable to crates.io.

ripgrep (binary)                    crates/core/     v15.1.0
├── grep (facade)                   crates/grep/     v0.4.1
│   ├── grep-cli                    crates/cli/      v0.1.12
│   ├── grep-matcher                crates/matcher/  v0.1.8
│   ├── grep-regex                  crates/regex/    v0.1.14
│   ├── grep-pcre2                  crates/pcre2/    v0.1.9
│   ├── grep-searcher               crates/searcher/ v0.1.16
│   └── grep-printer                crates/printer/  v0.3.1
├── globset                         crates/globset/  v0.4.18
└── ignore                          crates/ignore/   v0.4.25

1.2 Execution Flow

main()
  └─ run(flags::parse())
       ├─ flags::parse()
       │    ├─ Read RIPGREP_CONFIG_PATH → config args
       │    ├─ Merge config args + CLI args
       │    ├─ Parse into LowArgs (raw flag values)
       │    └─ Convert LowArgs → HiArgs (validated, resolved)
       │
       └─ match Mode:
            ├─ Search(single-threaded)
            │    ├─ Build: haystack_builder → walk_builder → matcher → searcher → printer
            │    ├─ Construct SearchWorker
            │    └─ Iterate haystacks sequentially
            │
            ├─ Search(multi-threaded)
            │    ├─ Same builder pipeline
            │    └─ Use WalkParallel (crossbeam-deque work stealing)
            │
            ├─ Files — list matching files only
            ├─ Types — list supported file types
            └─ Generate — emit completions or man page

1.3 Two-Phase Flag Parsing

Flag parsing uses a deliberate two-phase design (no clap or structopt dependency):

1. LowArgs (crates/core/flags/lowargs.rs): Raw representation of every flag value exactly as parsed from the command line. Uses lexopt for lightweight argument tokenization. All ~85 flags are defined as unit structs implementing the Flag trait in defs.rs.

2. HiArgs (crates/core/flags/hiargs.rs): Validated, resolved representation. Cross-flag validation happens here (e.g., --sort disables parallelism, --count switches printer mode). This is the struct that the search pipeline actually consumes.

The Flag trait per flag defines: name_long, name_short, name_negated, doc_short, doc_long, doc_category, doc_variable, and update(). The FLAGS array in defs.rs orders flags for documentation generation.

Note

Shell completions and man pages are generated at runtime via rg --generate complete-{bash,zsh,fish,powershell} and rg --generate man, not at build time. This ensures they always match the compiled binary exactly.

1.4 Search Pipeline

The search pipeline is a layered composition:

Pattern(s)
  → PatternMatcher (grep-regex or grep-pcre2)
    → Searcher (grep-searcher, manages line buffering + binary detection)
      → Sink (grep-printer: Standard | Summary | JSON)
        → Output (stdout, optionally colored via termcolor)

SearchWorker (crates/core/search.rs) owns one instance of each layer and processes haystacks (files or stdin) one at a time. In multi-threaded mode, each thread gets its own SearchWorker clone.

1.5 Parallel Directory Traversal

The ignore crate's WalkParallel provides parallel directory traversal using crossbeam-deque work-stealing queues. Each worker thread:

1. Pops a directory entry from its local deque
2. If its deque is empty, steals from another thread's deque
3. Applies ignore rules (gitignore, rgignore, overrides) during traversal
4. Feeds matching paths to SearchWorker

Important

When --sort is specified, ripgrep automatically falls back to single-threaded mode. Sorted output is incompatible with parallel traversal because results must be emitted in deterministic order.

1.6 Ignore File Precedence

Ignore rules are evaluated in a strict precedence order (lowest to highest priority):

1.7 Dependency Map

Runtime dependencies:

Dev dependencies: serde 1.0.77, serde_derive 1.0.77.

2. System Requirements

2.1 Supported Platforms

ripgrep targets all major platforms via cross-compilation. Pre-built binaries are published for:

2.2 Build Requirements

2.3 Optional Runtime Dependencies

ripgrep itself is a static binary with zero runtime library dependencies (when using musl). However, some features require external tools at runtime:

Tip

For --search-zip, ripgrep shells out to external decompression utilities via grep-cli's DecompressionReader. Supported formats: gz, bz2, xz, lzma, lz4, zst (zstandard), br (brotli), Z (compress). The decompressor binary must be in PATH.

3. Configuration Reference

3.1 Configuration File

ripgrep reads a configuration file at startup if the RIPGREP_CONFIG_PATH environment variable is set.

# Set in shell profile
export RIPGREP_CONFIG_PATH="$HOME/.ripgreprc"

Config file format:

• One flag per line (long or short form)
• Lines starting with # are comments
• Blank lines are ignored
• Flags that take values use = or a separate line for the value
• No shell expansion or quoting

Example ~/.ripgreprc:

# Search hidden files by default
--hidden

# Use smart case
--smart-case

# Set max columns
--max-columns=150
--max-columns-preview

# Custom type definitions
--type-add=web:*.{html,css,js,ts}

Warning

Config file flags are prepended to CLI args, so CLI flags always override config file flags via last-wins semantics. Negated flags (e.g., --no-hidden) can explicitly reverse a config file setting.

3.2 Environment Variables

3.3 Exit Codes

On Unix, a broken pipe causes graceful exit with code 0 (standard Unix convention).

3.4 Complete Flag Reference

All flags are defined in crates/core/flags/defs.rs. Flags follow last-wins semantics: if a flag is specified multiple times, the last occurrence takes effect. Most boolean flags have a --no- negated form.

3.4.1 Search Behavior

3.4.2 File & Directory Selection

3.4.3 Output Formatting

3.4.4 File Listing Modes

3.4.5 Encoding & Input

3.4.6 Concurrency

3.4.7 Logging & Debugging

3.4.8 Meta / Output Generation

4. Deployment & Scaling

4.1 Building from Source

# Standard release build
git clone https://github.com/BurntSushi/ripgrep
cd ripgrep
cargo build --release
# Binary at: target/release/rg

# Optimized release with LTO (smaller, faster, slower to compile)
cargo build --profile release-lto
# Binary at: target/release-lto/rg

# With PCRE2 support
cargo build --release --features pcre2

# Debian package (requires cargo-deb)
cargo install cargo-deb
cargo deb --profile deb

4.2 Build Profiles

4.3 Feature Flags

4.4 Allocator Selection

The allocator is selected at compile time via build.rs:

Note

jemalloc is used on musl+64-bit targets because musl's built-in allocator has known performance regressions with allocation-heavy workloads. On glibc targets, the system allocator is generally competitive with jemalloc.

4.5 Cross-Compilation

ripgrep supports cross-compilation via standard Rust toolchains:

# Example: build for aarch64 Linux from x86_64
rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

# Using cross (recommended for cross-compilation with C dependencies like PCRE2)
cargo install cross
cross build --release --target aarch64-unknown-linux-musl

4.6 Package Distribution

Shell completions (generate and install):

# Bash
rg --generate complete-bash > /usr/share/bash-completion/completions/rg

# Zsh
rg --generate complete-zsh > /usr/local/share/zsh/site-functions/_rg

# Fish
rg --generate complete-fish > /usr/share/fish/vendor_completions.d/rg.fish

# PowerShell
rg --generate complete-powershell | Out-File -Encoding utf8 -FilePath "$env:USERPROFILE\Documents\PowerShell\Completions\rg.ps1"

Man page:

rg --generate man > /usr/local/share/man/man1/rg.1

4.7 Static Binary Builds

For fully static, zero-dependency binaries:

# Build static musl binary (Linux)
cargo build --release --target x86_64-unknown-linux-musl
# Result: standalone ~6MB binary, no shared library dependencies

This is the recommended approach for containerized deployments:

# Multi-stage build for minimal image
FROM rust:1.85-slim AS builder
RUN apt-get update && apt-get install -y pkg-config musl-tools
WORKDIR /build
COPY . .
RUN rustup target add x86_64-unknown-linux-musl
RUN cargo build --profile release-lto --target x86_64-unknown-linux-musl

FROM scratch
COPY --from=builder /build/target/x86_64-unknown-linux-musl/release-lto/rg /rg
ENTRYPOINT ["/rg"]

5. Operations

5.1 Debugging and Diagnostics

Debug output shows which files are searched, which are skipped, and why:

# Show debug messages
rg --debug PATTERN

# Show trace-level detail (very verbose — shows every ignore rule evaluation)
rg --trace PATTERN

Debug output goes to stderr, so it can be captured separately:

rg --debug PATTERN 2>debug.log

Common debug output patterns:

Statistics provide aggregate search metrics:

rg --stats PATTERN
# Output includes: files searched, files matched, lines matched,
# matches found, bytes searched, time elapsed

5.2 Search Modes

5.3 JSON Output Format

The --json flag outputs structured JSON lines, one per event. Event types:

# Pipe JSON output to jq for processing
rg --json PATTERN | jq 'select(.type == "match") | .data.submatches'

Tip

JSON output is stable and machine-parseable. It is the recommended format for programmatic consumption of ripgrep results. Each line is a self-contained JSON object, making it compatible with streaming JSON processors like jq.

5.4 Binary File Handling

ripgrep uses a NUL-byte heuristic to detect binary files:

5.5 Memory-Mapped I/O

ripgrep can use memory-mapped I/O for reading files. The decision is made heuristically by default, but can be overridden:

# Force memory-mapped I/O
rg --mmap PATTERN

# Disable memory-mapped I/O
rg --no-mmap PATTERN

Caution

Memory-mapped I/O can cause SIGBUS on Unix systems if a file is truncated while being read. ripgrep installs a SIGBUS handler to deal with this gracefully, but --no-mmap avoids the issue entirely. Additionally, memory-mapped I/O is generally slower when searching many small files due to page fault overhead.

5.6 Handling Large-Scale Searches

For searching very large codebases or directory trees:

# Limit thread count to reduce memory pressure
rg -j4 PATTERN /large/tree

# Skip large files (e.g., vendored bundles, generated code)
rg --max-filesize 1M PATTERN

# Limit traversal depth
rg --max-depth 5 PATTERN

# Stay on one filesystem (avoid NFS, tmpfs, etc.)
rg --one-file-system PATTERN

# Suppress permission errors to reduce noise
rg --no-messages PATTERN /

6. Performance

6.1 Performance Architecture

ripgrep's speed comes from several architectural decisions working together:

1. Regex engine selection: Uses regex-automata which compiles patterns to DFA or NFA state machines. For literal patterns, it extracts literals and uses memchr or aho-corasick for fast scanning before engaging the full regex engine.

2. Parallel traversal: The ignore crate's WalkParallel uses crossbeam-deque work-stealing for efficient parallel directory traversal. Each thread has its own search stack.

3. Ignore-during-walk: .gitignore rules are evaluated during directory traversal, not after. Entire directory trees can be pruned without reading their contents.

4. Line-oriented searching: grep-searcher reads in large chunks (default 64KB buffer) and scans for line terminators and matches simultaneously, minimizing passes over the data.

5. Allocation minimization: The bstr crate and careful buffer reuse minimize allocations in the hot path.

6.2 Thread Tuning

# Use exactly 4 threads
rg -j4 PATTERN

# Use 1 thread (single-threaded mode, deterministic output order)
rg -j1 PATTERN

# Use all available cores (default)
rg -j0 PATTERN

The default (-j0) detects available CPU cores via std::thread::available_parallelism(). For I/O-bound searches (network filesystems, spinning disks), reducing thread count may improve throughput by reducing seek contention.

6.3 Performance-Impacting Flags

6.4 Benchmarking

ripgrep includes a benchmark suite at benchsuite/benchsuite (Python script):

cd benchsuite
python benchsuite --help

The benchmark suite compares ripgrep against:

• grep (GNU)
• git grep
• ag (The Silver Searcher)
• ugrep

Tip

For accurate benchmarks, drop filesystem caches before each run: sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches' on Linux. Run each benchmark multiple times to account for variance. The benchsuite uses a corpus of real-world data (Linux kernel source, subtitles, etc.) for representative measurements.

7. Security

7.1 Security Model

ripgrep is a local tool that reads files and writes to stdout. Its security surface:

7.2 Regex Engine Safety

The default Rust regex engine provides guaranteed linear-time matching:

• No catastrophic backtracking
• No ReDoS vulnerability
• Bounded memory usage proportional to pattern size
• No backreferences (by design)

Warning

The PCRE2 engine (--pcre2 / -P) does NOT guarantee linear time. Patterns with backreferences or complex lookaround can exhibit exponential time complexity. Do not use --pcre2 with untrusted patterns in security-sensitive contexts.

7.3 Safe Usage with Untrusted Input

# Safe: treat user input as literal string
rg --fixed-strings -- "$USER_INPUT" /path

# Safe: read patterns from file, treated as literals
rg --fixed-strings -f patterns.txt /path

# Unsafe: user input interpreted as regex
rg "$USER_INPUT" /path  # DO NOT do this with untrusted input

# Note: use -- to prevent patterns starting with - from being parsed as flags
rg --fixed-strings -- "$USER_INPUT" /path

7.4 File System Safety

• ripgrep does not follow symlinks unless --follow is explicitly passed
• The --one-file-system flag prevents crossing mount boundaries (useful in containers or to avoid NFS mounts)
• --max-depth limits traversal depth, preventing runaway searches in deep directory trees
• --max-filesize limits per-file read size, preventing memory exhaustion on large files

Caution

When running ripgrep in environments where the file tree is partially controlled by untrusted users (e.g., shared hosting, CI with untrusted repos), be aware that maliciously crafted .gitignore or .rgignore files can influence which files are skipped. Use --no-ignore to disable all ignore file processing in such environments.

8. Developer Internals

8.1 Source Layout

crates/
  core/                    Binary crate (rg)
    main.rs                Entry point: main() → run()
    search.rs              SearchWorker: owns matcher + searcher + printer
    haystack.rs            Haystack construction and filtering
    logger.rs              Log initialization (env_logger-style)
    flags/
      mod.rs               Flag trait, Category enum, FlagValue
      defs.rs              ~85 flag definitions (unit structs implementing Flag)
      parse.rs             CLI argument parser → LowArgs
      lowargs.rs           LowArgs struct (raw flag values)
      hiargs.rs            HiArgs struct (validated, resolved)
      config.rs            Config file parser (RIPGREP_CONFIG_PATH)
      complete/            Shell completion generators
        bash.rs            Bash completion script
        zsh.rs             Zsh completion script
        fish.rs            Fish completion script
        powershell.rs      PowerShell completion script
      doc/
        help.rs            Help text generation (short + long)
        man.rs             Man page (roff) generation
  grep/                    Facade crate (re-exports grep-*)
  cli/                     CLI utilities
    decompress.rs          DecompressionReader (external decompressor process)
    escape.rs              Byte string escaping
    pattern.rs             Pattern I/O (read from file, stdin)
    wtr.rs                 StandardStream (TTY-aware writer)
  matcher/                 Matcher trait
    interpolate.rs         Capture group interpolation ($1, $name)
  regex/                   Rust regex adapter
    ast.rs                 AST analysis for optimization
    config.rs              RegexMatcherBuilder config
    error.rs               Error types
    literal.rs             Literal extraction for acceleration
    non_matching.rs        Non-matching byte detection
    strip.rs               Pattern stripping utilities
    word.rs                Word boundary handling
  pcre2/                   PCRE2 adapter (optional feature)
    error.rs               PCRE2 error types
    matcher.rs             PCRE2 Matcher implementation
  searcher/                Core search engine
    searcher/
      core.rs              Searcher implementation
      glue.rs              Searcher-to-Matcher glue logic
    line_buffer.rs         Line-oriented buffered reading (64KB default)
    sink.rs                Sink trait and implementations
  printer/                 Output printers
    standard.rs            Standard human-readable output (grep-like)
    summary.rs             Summary output (counts, file lists)
    json.rs                JSON lines output format
    hyperlink.rs           OSC 8 hyperlink generation
    color.rs               Color specification parsing
    stats.rs               Search statistics accumulation
    util.rs                Shared printer utilities
  globset/                 Glob matching library
    glob.rs                Glob parsing and compilation to regex
    fnmatch.rs             fnmatch-style matching
    pathutil.rs            Path normalization utilities
    serde_impl.rs          Serde Serialize/Deserialize for Glob
  ignore/                  Ignore + directory walking
    walk.rs                Walk (sequential) and WalkParallel (crossbeam-deque)
    dir.rs                 Per-directory ignore rule management
    gitignore.rs           .gitignore file parser
    overrides.rs           CLI --glob override rules
    types.rs               Built-in file type definitions and matching
    pathutil.rs            Path utilities (is_hidden, strip_prefix, etc.)

tests/
  tests.rs                 Integration test entry point (imports all test modules)
  binary.rs                Binary file handling tests
  feature.rs               Feature-specific tests (types, globs, etc.)
  json.rs                  JSON output format tests
  misc.rs                  Miscellaneous tests
  multiline.rs             Multiline matching tests
  regression.rs            Regression tests (linked to GitHub issues)
  hay.rs                   Test haystack helpers (create temp dirs with test data)
  util.rs                  Test utilities (run rg binary, assert output)
  macros.rs                Test assertion macros
  data/                    Test data (sherlock.txt in various compressed formats)

benchsuite/
  benchsuite               Python benchmark runner script

fuzz/
  fuzz_targets/
    fuzz_glob.rs           Fuzz target for globset glob parsing

ci/
  sha256-releases          Generate SHA256 checksums for release artifacts
  test-complete            Validate generated shell completions
  ubuntu-install-packages  Install build dependencies on Ubuntu
  utils.sh                 Shared CI utility functions

8.2 Adding a New Flag

Each flag is a unit struct implementing the Flag trait in crates/core/flags/defs.rs. To add a new flag:

1. Define the struct and implement Flag:

/// --my-new-flag
#[derive(Debug)]
struct FlagMyNewFlag;

impl Flag for FlagMyNewFlag {
    fn is_switch(&self) -> bool { true }
    fn name_long(&self) -> &'static str { "my-new-flag" }
    fn name_short(&self) -> Option<u8> { None }
    fn name_negated(&self) -> Option<&'static str> { Some("no-my-new-flag") }
    fn doc_category(&self) -> Category { Category::Search }
    fn doc_short(&self) -> &'static str { "Short description." }
    fn doc_long(&self) -> &'static str { "Long description..." }
    fn update(&self, v: FlagValue, args: &mut LowArgs) -> anyhow::Result<()> {
        args.my_new_flag = v.unwrap_switch();
        Ok(())
    }
}

2. Add the field to LowArgs in lowargs.rs.
3. Add the flag to the FLAGS array in defs.rs, maintaining alphabetical order.
4. Wire it into HiArgs in hiargs.rs for validation and resolution.
5. Use it in the search pipeline (e.g., search.rs, haystack.rs).
6. Add tests: inline #[test] functions in the flag definition, plus integration tests in tests/.

8.3 The Matcher Trait

The grep-matcher crate defines the abstract Matcher trait that makes ripgrep engine-agnostic:

pub trait Matcher {
    type Captures: Captures;
    type Error: std::fmt::Display;

    fn find_at(
        &self, haystack: &[u8], at: usize,
    ) -> Result<Option<Match>, Self::Error>;

    fn new_captures(
        &self,
    ) -> Result<Self::Captures, Self::Error>;

    fn captures_at(
        &self, haystack: &[u8], at: usize, caps: &mut Self::Captures,
    ) -> Result<bool, Self::Error>;

    // Additional methods with default implementations:
    // find(), find_iter(), captures(), captures_iter(),
    // replace(), replace_with_captures(), etc.
}

Both grep-regex::RegexMatcher and grep-pcre2::RegexMatcher implement this trait. Custom regex engines can be integrated by providing a Matcher implementation.

The Match type is a simple (start, end) byte offset pair. LineTerminator controls what constitutes a line boundary. ByteSet is a bitset over byte values used for fast character class membership tests.

8.4 The Sink Trait

The grep-searcher crate's Sink trait is the output callback interface:

pub trait Sink {
    type Error;

    fn matched(
        &mut self, searcher: &Searcher, mat: &SinkMatch<'_>,
    ) -> Result<bool, Self::Error>;

    // Optional methods with defaults:
    fn context(
        &mut self, _: &Searcher, _: &SinkContext<'_>,
    ) -> Result<bool, Self::Error> { Ok(true) }

    fn begin(
        &mut self, _: &Searcher,
    ) -> Result<bool, Self::Error> { Ok(true) }

    fn finish(
        &mut self, _: &Searcher, _: &SinkFinish,
    ) -> Result<(), Self::Error> { Ok(()) }
}

The grep-printer crate provides three Sink implementations:

The return value of matched() and context() controls whether searching continues (true) or stops early (false), enabling features like --max-count.

8.5 The Ignore Crate — Reusable Library

The ignore crate is one of ripgrep's most widely reused components. It is used by many other tools (fd, tokei, etc.) for fast, gitignore-aware directory traversal.

WalkBuilder: Configures directory traversal with ignore rules, file type filters, and parallelism.

use ignore::WalkBuilder;

// Sequential walk
for entry in WalkBuilder::new("./src").build() {
    let entry = entry.unwrap();
    println!("{}", entry.path().display());
}

// Parallel walk
WalkBuilder::new("./src")
    .hidden(false)        // search hidden files
    .git_ignore(true)     // respect .gitignore
    .follow_links(false)  // don't follow symlinks
    .threads(4)           // parallel walk threads
    .build_parallel()
    .run(|| {
        Box::new(|entry| {
            // Process entry in worker thread
            ignore::WalkState::Continue
        })
    });

Gitignore: Parses and evaluates .gitignore rules. Can be used standalone without directory traversal.

Types: File type matching based on glob patterns. Includes ~150 built-in file type definitions.

8.6 The Globset Crate — Reusable Library

globset is a standalone crate for high-performance glob matching. Its key feature is GlobSet, which compiles multiple globs into a single regex for simultaneous matching in one pass:

use globset::{Glob, GlobSetBuilder};

let mut builder = GlobSetBuilder::new();
builder.add(Glob::new("*.rs")?);
builder.add(Glob::new("*.toml")?);
let set = builder.build()?;

// Returns indices of all matching globs
let matches: Vec<usize> = set.matches("src/main.rs");
assert!(set.is_match("src/main.rs"));

Glob syntax supported:

• * — matches any sequence of non-path-separator characters
• ** — matches any sequence of characters, including path separators
• ? — matches any single non-path-separator character
• [abc] — character class
• [!abc] / [^abc] — negated character class
• {a,b,c} — alternation

8.7 Error Handling

• The binary crate uses anyhow for error propagation with context
• Library crates define their own error types (no anyhow dependency in libraries)
• The err_message! macro in the binary crate prints non-fatal errors to stderr and sets the exit code to 2
• Broken pipe errors (std::io::ErrorKind::BrokenPipe) are caught and cause a graceful exit with code 0
• The HiArgs conversion phase (LowArgs -> HiArgs) performs cross-flag validation and reports conflicts as errors

8.8 Testing

Unit tests: Each flag in defs.rs has inline #[test] functions testing parsing behavior for positive, negative, and edge cases.

Integration tests (tests/): End-to-end tests that invoke rg as a subprocess and assert on stdout/stderr content:

# Run all tests
cargo test

# Run only integration tests
cargo test --test tests

# Run a specific test module
cargo test --test tests -- regression

# Run tests with PCRE2
cargo test --features pcre2

Test infrastructure (tests/util.rs): Provides a Dir builder that creates temporary directories with test files, runs rg against them, and asserts on output. The rgtest! macro (in macros.rs) simplifies test definitions.

Fuzz testing: The fuzz/ directory contains a fuzzing target for globset glob parsing:

cargo install cargo-fuzz
cargo fuzz run fuzz_glob

8.9 CI Pipeline

The ci/ directory contains CI support scripts:

8.10 build.rs

The build.rs script reads two environment variables set by Cargo:

The build script emits cargo:rustc-cfg directives that control conditional compilation in main.rs (e.g., jemalloc usage on musl).

9. Integration Points

9.1 As a Library

ripgrep's library crates are published to crates.io independently. The grep facade crate provides a single dependency that re-exports all grep-* crates:

[dependencies]
grep = "0.4"

For selective usage (smaller dependency tree):

[dependencies]
grep-searcher = "0.1"
grep-regex = "0.1"
grep-printer = "0.3"

The ignore and globset crates are particularly popular as standalone libraries:

[dependencies]
ignore = "0.4"    # gitignore-aware directory walking
globset = "0.4"   # high-performance glob matching

9.2 Editor Integration

ripgrep is widely integrated into code editors:

The --vimgrep flag produces output compatible with vim's errorformat:

file.rs:10:5:matched text here

9.3 Shell Integration

Pipe-friendly defaults: When stdout is not a TTY, ripgrep automatically:

• Disables colors
• Disables headings
• Enables line numbers

xargs integration:

# NUL-separated output for safe filename handling
rg --files --null | xargs -0 wc -l
rg -l --null PATTERN | xargs -0 sed -i 's/old/new/g'

fzf integration:

# Interactive ripgrep with fzf preview
rg --line-number --color=always PATTERN | \
  fzf --ansi --preview 'bat --color=always {1} --highlight-line {2}'

9.4 JSON Output for Tooling

The --json output format enables programmatic integration:

# Count matches per file using jq
rg --json PATTERN | \
  jq -r 'select(.type == "end") | "\(.data.path.text): \(.data.stats.matches)"'

# Extract matched text only
rg --json PATTERN | \
  jq -r 'select(.type == "match") | .data.submatches[].match.text'

# Get file paths with matches
rg --json PATTERN | \
  jq -r 'select(.type == "begin") | .data.path.text'

9.5 Preprocessor Integration

The --pre flag enables arbitrary file preprocessing:

# Search inside PDF files using pdftotext
rg --pre pdftotext --pre-glob '*.pdf' PATTERN

# Search inside Word documents
rg --pre 'pandoc --to=plain' --pre-glob '*.docx' PATTERN

# Search inside SQLite databases
rg --pre 'sqlite3 -csv' --pre-glob '*.db' PATTERN

Important

The --pre command receives the file path as its first argument and must write the searchable text to stdout. It runs once per file, so this is significantly slower than direct file searching. Always use --pre-glob to limit preprocessing to specific file types.

9.6 Compressed File Search

ripgrep delegates decompression to external utilities via grep-cli's DecompressionReader:

# Search all compressed files in a directory
rg -z PATTERN /var/log/

Note

Compressed file format detection uses file extensions, not content sniffing (see GitHub issue #3342). Files with incorrect or missing extensions will not be decompressed. Use --pre with a content-aware tool for extension-independent detection.

9.7 Known Issues and Workarounds

Sourced from the project's GitHub issue tracker: