User Guide

This guide covers ripgrep's features in depth. It is adapted from the official GUIDE.md in the ripgrep repository.

By default, ripgrep searches the current directory recursively. You can also specify one or more paths explicitly: 

# Search current directory
rg 'pattern'

# Search a specific directory
rg 'pattern' src/

# Search specific files
rg 'pattern' src/main.rs src/lib.rs

# Search stdin
echo "hello world" | rg 'hello'

ripgrep follows symlinks by default. To prevent following symlinks, use --no-follow. To set a maximum search depth, use --max-depth: 

# Only search 2 levels deep
rg 'pattern' --max-depth 2

Automatic filtering

Out of the box, ripgrep respects several ignore rules so you almost never search files you do not care about:

  • .gitignore — respects rules from your project's git ignore file
  • .ignore — same syntax as .gitignore, honoured even outside git repos
  • .rgignore — ripgrep-specific ignore file, takes precedence over .ignore
  • Hidden files — files and directories beginning with . are skipped
  • Binary files — files detected as binary (containing NUL bytes) are skipped

You can selectively disable these filters:

# Include hidden files and directories
rg -. 'pattern'

# Do not respect .gitignore (but still skip hidden/binary)
rg --no-ignore 'pattern'

# Disable ALL filtering (search truly everything)
rg -uu 'pattern'

# Show which files would be searched without actually searching
rg --files

Manual filtering: globs

Use -g / --glob to include or exclude files by glob pattern. Prefix with ! to negate (exclude). 

# Only search .ts files
rg 'interface' -g '*.ts'

# Exclude test files
rg 'TODO' -g '!*.test.*'

# Multiple globs
rg 'import' -g '*.ts' -g '!*.d.ts'

# Exclude a directory
rg 'console.log' -g '!dist/**'

Manual filtering: file types

File type aliases are a convenient shorthand for common glob patterns. Use -t to include a type and -T to exclude it. 

# Show all built-in file types
rg --type-list

# Only Python files
rg 'def ' -t py

# Only Rust files, excluding tests
rg 'unsafe' -t rust -T test

# Define a custom type and use it
rg --type-add 'web:*.{html,css,js,ts}' -t web 'className'

Replacements

The -r / --replace flag substitutes all matches in the printed output (it does not modify files). Use capture groups with $1, $2, or named groups with $name. 

# Replace matches in output
rg 'fn (w+)' -r 'function $1'

# Swap date format YYYY-MM-DD → DD/MM/YYYY
rg '(d{4})-(d{2})-(d{2})' -r '$3/$2/$1'

# Named capture groups
rg '(?P<last>w+), (?P<first>w+)' -r '$first $last'

# To actually write changes to files, pipe through sed or use sd:
rg --passthru 'old_name' -r 'new_name' src/main.rs | sponge src/main.rs

File encoding

ripgrep searches files as UTF-8 by default. It automatically detects UTF-16 via BOM. For other encodings, use -E / --encoding. 

# Force Latin-1 (ISO-8859-1) encoding
rg -E latin-1 'pattern' legacy.txt

# Force Shift-JIS (Japanese)
rg -E shift-jis 'パターン' file.txt

# Common encodings supported:
# utf-8, utf-16, latin-1, ascii, gbk, euc-jp, euc-kr, ...

Binary data

By default, ripgrep skips binary files (files containing NUL bytes). You can override this with -a / --text to treat all files as text: 

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

# Explicitly search a binary file
rg -a 'pattern' binary-file.bin

Searching compressed files

With -z / --search-zip, ripgrep decompresses files on the fly before searching. Supported formats: gzip, bzip2, xz, LZ4, Brotli, Zstandard, LZMA. 

# Search inside .gz log files
rg -z 'ERROR' /var/log/app.log.gz

# Search all compressed logs in a directory
rg -z 'WARN' /var/log/nginx/

# Combine with type filter
rg -z 'pattern' -g '*.gz'

Preprocessors

The --pre flag specifies a command to run on each file before searching. ripgrep passes the file path as an argument and searches the command's stdout. This enables searching non-text formats like PDFs. 

# Search PDFs (requires pdftotext from poppler)
rg --pre pdftotext 'keyword' docs/

# Search Word documents (requires docx2txt)
rg --pre docx2txt 'pattern' documents/

# Only preprocess specific file types
rg --pre pdftotext --pre-glob '*.pdf' 'keyword' .

Configuration files

ripgrep reads a configuration file to set default flags. The path is specified via the RIPGREP_CONFIG_PATH environment variable, or you can use ~/.ripgreprc on Unix / %APPDATA%\ripgrep\config on Windows.

~/.ripgreprc bash 
# Always use smart-case (case-insensitive unless pattern has uppercase)
--smart-case

# Always search hidden files
--hidden

# Always show line numbers (rg already does this in terminals, but useful for pipes)
--line-number

# Set a custom colors
--colors=match:fg:yellow

# Ignore some directories globally
--glob=!.git/
--glob=!node_modules/
--glob=!.venv/
# Point to a config file explicitly
RIPGREP_CONFIG_PATH=~/.ripgreprc rg 'pattern'

# Or export it in your shell profile
export RIPGREP_CONFIG_PATH="$HOME/.ripgreprc"
← Getting Started FAQ →