ripgrep (rg) CLI Reference

ripgrep is a line-oriented search tool that recursively searches directories for regex patterns. It respects .gitignore rules by default and automatically skips hidden files, directories, and binary files.

Basic Usage

# Search for pattern in current directory (recursive)
rg 'pattern'

# Search specific file
rg 'pattern' file.txt

# Search specific directory
rg 'pattern' src/

# Multiple paths
rg 'pattern' src/ tests/ docs/

Essential Flags

Flag	Short	Description
--ignore-case	-i	Case-insensitive search
--smart-case	-S	Case-insensitive unless pattern has uppercase
--word-regexp	-w	Match whole words only
--fixed-strings	-F	Treat pattern as literal string (no regex)
--count	-c	Show count of matches per file
--files-with-matches	-l	Show only filenames with matches
--files-without-match	-L	Show only filenames without matches
--line-number	-n	Show line numbers (default when output is terminal)
--no-line-number	-N	Suppress line numbers
--only-matching	-o	Print only the matched text
--invert-match	-v	Show non-matching lines
--multiline	-U	Enable multiline matching (. matches newlines)

Context Lines

# Show 3 lines after each match
rg -A 3 'pattern'

# Show 3 lines before each match
rg -B 3 'pattern'

# Show 3 lines before and after (context)
rg -C 3 'pattern'

File Filtering

By File Type

# Search only in Rust files
rg 'pattern' --type rust
rg 'pattern' -trust

# Exclude JavaScript files
rg 'pattern' --type-not js
rg 'pattern' -Tjs

# List all available types
rg --type-list

# Define custom type
rg --type-add 'web:*.{html,css,js}' -tweb 'pattern'

Common built-in types: py, js, ts, rust, go, java, c, cpp, html, css, json, yaml, md, sh

By Glob Pattern

# Include only .toml files
rg 'pattern' -g '*.toml'

# Include files in specific directory
rg 'pattern' -g 'src/**/*.rs'

# Exclude files (prefix with !)
rg 'pattern' -g '!*.min.js'

# Multiple globs
rg 'pattern' -g '*.rs' -g '*.toml'

Automatic Filtering Control

ripgrep automatically ignores:

1. Files matching .gitignore, .ignore, .rgignore patterns
2. Hidden files and directories
3. Binary files

# Disable .gitignore filtering
rg --no-ignore 'pattern'

# Search hidden files
rg --hidden 'pattern'
rg -. 'pattern'

# Search binary files as text
rg --text 'pattern'
rg -a 'pattern'

# Shorthand for disabling filters
rg -u 'pattern'    # --no-ignore
rg -uu 'pattern'   # --no-ignore --hidden
rg -uuu 'pattern'  # --no-ignore --hidden --text

Regex Patterns

ripgrep uses Rust regex syntax by default.

# Word characters followed by digits
rg '\w+\d+'

# Start/end of line anchors
rg '^start'
rg 'end$'

# Character classes
rg '[A-Z][a-z]+'

# Alternation
rg 'foo|bar'

# Quantifiers
rg 'colou?r'       # 0 or 1
rg 'a+'            # 1 or more
rg 'a*'            # 0 or more
rg 'a{2,4}'        # 2 to 4 times

# Non-greedy matching
rg 'a+?'

# Lookahead/lookbehind (requires PCRE2)
rg -P '(?<=prefix)\w+'    # Lookbehind
rg -P '\w+(?=suffix)'     # Lookahead

PCRE2 Mode

Enable PCRE2 for advanced regex features:

# Enable PCRE2
rg -P 'pattern'
rg --pcre2 'pattern'

# Auto-detect when PCRE2 is needed
rg --engine auto 'pattern'

Multiline Search

# Basic multiline (dot matches newline)
rg -U 'start.*end'

# Match across lines with PCRE2
rg -UP 'function\s+\w+\s*\([^)]*\)\s*\{'

Replacements (Output Only)

ripgrep never modifies files. The --replace flag transforms output only.

# Simple replacement
rg 'old' -r 'new'

# With capture groups
rg '(\w+)@(\w+)' -r '$2:$1'

# Named capture groups
rg '(?P<user>\w+)@(?P<domain>\w+)' -r '$domain:$user'

Output Formats

# JSON output (for parsing)
rg --json 'pattern'

# Null-separated filenames (for xargs -0)
rg -l --null 'pattern'

# Show only matching files
rg -l 'pattern'

# Show files that would be searched
rg --files

# Show files matching glob
rg --files -g '*.rs'

Performance Options

# Limit search depth
rg --max-depth 3 'pattern'

# Limit results
rg --max-count 5 'pattern'    # Per file
rg 'pattern' | head -n 100    # Total

# Disable memory maps (for consistency)
rg --no-mmap 'pattern'

# Sort results by path
rg --sort path 'pattern'

Common Patterns

Find function definitions

# Rust
rg '^(pub\s+)?(async\s+)?fn\s+\w+'

# Python
rg '^def \w+|^class \w+'

# JavaScript/TypeScript
rg '(function|const|let|var)\s+\w+\s*='

Find TODO/FIXME comments

rg 'TODO|FIXME|XXX|HACK' -g '!*.min.*'

Find imports/requires

# Python
rg '^(import|from)\s+\w+'

# JavaScript
rg "^(import|require\()"

# Go
rg '^import\s+'

Search specific patterns

# IP addresses (approximate)
rg '\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}'

# Email addresses (simple)
rg '\w+@\w+\.\w+'

# URLs
rg 'https?://[^\s]+'

Configuration File

Set default options via RIPGREP_CONFIG_PATH:

export RIPGREP_CONFIG_PATH="$HOME/.ripgreprc"

Example ~/.ripgreprc:

--smart-case
--hidden
--glob=!.git/*
--max-columns=150
--max-columns-preview

Debugging

# Show what files would be searched and why others are ignored
rg --debug 'pattern'

# Disable config file
rg --no-config 'pattern'

Key Differences from grep

Feature	ripgrep	GNU grep
Recursive by default	Yes	No (-r required)
Respects .gitignore	Yes	No
Skips binary files	Yes	No
Unicode by default	Yes	Depends on locale
Parallel search	Yes	No
Memory-mapped files	Yes	No

Reference

For advanced features, see:

• references/advanced.md - Preprocessors, encoding, binary handling