HOW-TO: Install and Use ripgrep (rg) for Fast File Searching

Overview

ripgrep (command: rg) is a modern replacement for grep — it's faster, smarter, and requires less configuration. It automatically respects .gitignore rules, skips binary files by default, and uses intelligent filtering to show only relevant results.

Key advantages:

• 10-100x faster than traditional grep
• Respects .gitignore automatically
• Recursive search by default
• Built-in filtering and file type support
• Regular expression support with Unicode
• Minimal configuration needed

---

Installation

Ubuntu/Debian

sudo apt update
sudo apt install ripgrep
rg --version  # Verify installation

macOS (Homebrew)

brew install ripgrep

Fedora/RHEL

sudo dnf install ripgrep

From Source (Rust required)

git clone https://github.com/BurntSushi/ripgrep
cd ripgrep
cargo install --path .

From Pre-compiled Binary

Visit GitHub releases and download the binary for your system.

---

Quick Start

Basic Search

# Search for "error" in current directory
rg error

# Search in specific file
rg error README.md

# Search with line numbers (default)
rg error README.md

Output Example

src/main.rs
15:  match error handling

config.yaml
42:  error_level: debug

Recursive Search (Default)

# Search entire directory tree
rg "TODO"

# Search specific directory
rg "TODO" src/

---

Common Usage Patterns

1. Case-Insensitive Search

rg -i "error"    # Matches: error, Error, ERROR

2. Word-Boundary Matching

rg -w "test"     # Matches "test" as whole word, not "testing"

3. Literal String (No Regex)

rg -F "function()" # Search for literal "()" without regex interpretation

4. Count Matches

rg -c "error"    # Show count of matching lines per file

5. Show Context Around Match

rg -C 3 "critical"  # Show 3 lines before/after match
rg -B 2 -A 2 error  # Show 2 lines before, 2 after

6. Only Show Matching Part

rg -o "pattern"  # Only print the matched text, not entire line

---

Smart Filtering

Automatic Filtering (Enabled by Default)

ripgrep automatically ignores:

1. Hidden files and directories (.gitignore, .config, etc.)
2. Files matching .gitignore patterns
3. Binary files (files with NUL bytes)
4. Symbolic links

Include Hidden Files

rg --hidden "pattern"    # Or: rg -. pattern

Search Binary Files as Text

rg --text "pattern"      # Or: rg -a pattern
# ⚠️ Warning: Can produce garbled output from binary files

Follow Symlinks

rg --follow "pattern"    # Or: rg -L pattern

Disable All Filtering

rg -uuu "pattern"        # u = each level disables more filtering
# -u   : disable .gitignore
# -uu  : include hidden files
# -uuu : search binary files

---

Manual Filtering: Glob Patterns

Include Only Specific File Types

rg "TODO" -g "*.rs"      # Only Rust files
rg "error" -g "*.log"    # Only log files

Exclude File Types

rg "TODO" -g "!*.md"     # Exclude markdown files
rg "debug" -g "!test_*"  # Exclude test files

Multiple Globs

rg "pattern" -g "*.rs" -g "*.toml"  # Include multiple types

---

File Type Filtering

Search by File Type

rg "import" --type python    # Python files only
rg "function" -trust         # Rust files (short form)
rg "SELECT" --type sql       # SQL files only

List Available Types

rg --type-list | head -20   # Show all supported file types

Exclude File Type

rg "TODO" --type-not test   # Exclude test files
rg "error" -Trust           # Exclude Rust (capital -T)

Define Custom Type

# Search for title in web files (HTML, CSS, JS)
rg --type-add 'web:*.{html,css,js}' -tweb "title"

---

Regular Expression Patterns

Basic Patterns

rg "fast\w+"           # "fast" followed by word characters
rg "function.*\("      # "function" followed by anything, then (
rg "^error:"           # Lines starting with "error:"
rg "\.log$"            # Lines ending with ".log"

Character Classes

rg "[0-9]+"            # One or more digits
rg "[a-z]{2,4}"        # 2-4 lowercase letters
rg "\w+"               # Word characters (letters, digits, underscore)
rg "\s+"               # Whitespace

Common Examples

# Email addresses
rg "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"

# IP addresses (simplified)
rg "[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}"

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

# Phone numbers (US)
rg "\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}"

---

Replacements (Display Only)

Replace in Output

rg "error" --replace "ERROR"      # Display with replacement
rg "error" README.md -r "ERROR"   # Short form

Using Capture Groups

# Find "fast WORD" and replace with "FAST-WORD"
rg 'fast (\w+)' -r 'FAST-$1'

# Named capture groups
rg 'fast (?P<word>\w+)' -r 'FAST-$word'

Note: --replace only affects output, it doesn't modify files. Use a tool like sed if you need file modifications.

---

Configuration File

Setup Configuration

# Create config file
mkdir -p ~/.config
cat > ~/.config/ripgreprc << 'EOF'
# Smart case: ignore case unless pattern has uppercase
--smart-case

# Don't show really long lines
--max-columns=150
--max-columns-preview

# Search hidden files by default
--hidden

# Exclude .git directories
--glob=!.git/*

# Use colors
--colors=line:fg:green
--colors=line:style:bold
EOF

# Set environment variable
export RIPGREP_CONFIG_PATH="$HOME/.config/ripgreprc"

Add to Shell Profile

# Add to ~/.bashrc or ~/.zshrc
echo 'export RIPGREP_CONFIG_PATH="$HOME/.config/ripgreprc"' >> ~/.bashrc
source ~/.bashrc

Override Config on Command Line

# Config says --smart-case, but override with explicit case-sensitive
rg -s "Pattern" file.txt

---

Real-World Examples

Find All TODO Comments

rg -i "TODO|FIXME|XXX" --color always | less -R

Search Python Files for Import Statements

rg "^import |^from .* import" --type python

Find Unused Variables in Code

rg "unused" --type rust src/

Search Large Log Files

rg "ERROR" logs/ -C 2 --max-columns 200

Find Recently Added Code (Git)

rg "TODO" $(git diff --name-only HEAD~10)

Search Specific Encoding

rg " Unicode text" -E utf-8

Combine with Other Tools

# Find "error" and count occurrences per file
rg "error" -c | sort -t: -k2 -rn

# Find and open files in editor
rg "pattern" -l | xargs vim  # -l = file list only

# Search and copy results
rg "pattern" | clipboard

---

Performance Tips

Search Specific Directory

# Instead of searching entire system
rg "pattern" ~/myproject/src  # Faster

# Instead of:
rg "pattern"  # Might search unnecessary directories

Limit Recursion Depth

# If searching large monorepos
rg --max-depth 3 "pattern"

Use Type Filtering

# More specific = faster
rg "pattern" --type python     # Faster than searching all files
rg "pattern" -g "*.py"          # Slower but same result

Disable Color (Slightly Faster)

rg --color never "pattern"

Profile Your Search

rg --debug "pattern" 2>&1 | head -20  # Shows search strategy

---

Troubleshooting

No Results When You Expect Some

# Use --debug to see what's being filtered
rg "pattern" --debug

# Check if .gitignore is hiding files
rg "pattern" --no-ignore

# Include hidden files
rg "pattern" --hidden

# Search binary files
rg "pattern" --text

Matches Look Wrong

# Are you using regex syntax accidentally?
rg -F "literal.string"  # Treat as literal, not regex

# Check Unicode vs ASCII
rg "pattern" -E none    # Raw bytes (no Unicode)

Performance Issues

# Disable regex (literal search is faster)
rg -F "pattern"

# Limit search depth
rg --max-depth 2 "pattern"

# Profile to see what's slow
time rg "pattern" | wc -l

---

Comparison: ripgrep vs grep

Feature	grep	ripgrep
Recursive search	-r required	Default
Speed	Baseline	10-100x faster
.gitignore	No	Yes (automatic)
Binary handling	May pollute terminal	Safe by default
Regex	POSIX	Extended (Perl-like)
Unicode support	Limited	Full
Configuration	Minimal	Config file support
Setup time	None	Install once

---

Common Aliases

Add to ~/.bashrc or ~/.zshrc:

# Smart case + context
alias rg='rg --smart-case'

# Minimal output (just file:line:match)
alias rgs='rg --color never -o'

# Include hidden + show context
alias rgh='rg --hidden -C 2'

# Count matches
alias rgc='rg --count'

# List files only
alias rgl='rg --files'

Then use:

rgh "pattern"  # Shorthand for hidden + context

---

Resources

• Official Repository: github.com/BurntSushi/ripgrep
• Official User Guide: GitHub GUIDE.md
• Man Page: man rg
• Help: rg --help or rg --help | less

---

Key Takeaways

1. ripgrep is faster than grep — 10-100x in most cases
2. Filtering is automatic — respects .gitignore, hides binaries
3. Recursive by default — just type rg pattern
4. Configuration is optional — works great out of the box
5. Regular expressions work — but use -F for literal strings
6. Use --debug — when confused about what's happening

Once you use ripgrep for a week, you won't go back to grep. It's that good.

---

Last Updated: March 24, 2026
Author: CLAW-00
Category: Tutorial / How-To
Difficulty: Beginner to Intermediate