# ripgrep Search Patterns Reference

Practical search patterns for efficient one-shot searches with ripgrep.

# One-Shot Search Strategy

**Goal: Get files + line numbers + context in ONE call.**

## The Primary Pattern

```bash
rg -n -C 2 -t TYPE -e 'pattern'
```

**What this gives:**
- `-n` - Line numbers
- `-C 2` - 2 lines context before/after
- `-t TYPE` - File type filter
- `-e 'pattern'` - The search pattern

**Use this as the default.** Adjust only when needed.

---

# Essential Flag Combinations

## 1. Standard Search with Context
```bash
rg -n -C 2 -t js -e 'functionName'
```
Most common pattern - gives everything needed.

## 2. Fixed String (Literal) Search
```bash
rg -F -n -C 2 -t js -e 'exact.string.with.dots'
```
Use `-F` when pattern has regex special chars (`.` `*` `(` `)` etc.)
**Avoids regex escaping hell.**

## 3. Word Boundary (Precise) Search
```bash
rg -w -n -C 2 -t js -e 'variable'
```
`-w` matches whole words only. Finds "variable" but not "variableName".

## 4. Case-Insensitive Search
```bash
rg -i -n -C 2 -t js -e 'pattern'
```
`-i` for case-insensitive matching.

## 5. List Files Only (Quick Overview)
```bash
rg -l -t js -e 'pattern' | head -20
```
`-l` lists filenames only. Pipe to `head` to limit.

## 6. Count Matches
```bash
rg -c -t js -e 'pattern'
```
`-c` shows count per file.

## 7. Invert Match (Find Files WITHOUT Pattern)
```bash
rg -l -t js -e 'import React' | rg -v -F -e 'import { useState }'
```
First find files with React, then filter out files with useState.

Or simpler:
```bash
rg -L -t js -e 'pattern'
```
`-L` lists files that do NOT match.

## 8. Multiple Patterns (OR Logic)
```bash
rg -n -C 2 -t js -e 'pattern1' -e 'pattern2'
```
Matches either pattern.

## 9. Specific Directory
```bash
rg -n -C 2 -t js -e 'pattern' src/components
```
Add directory path at end to narrow scope.

---

# Pipe Composition Patterns

## Limit Results
```bash
rg -n -t js -e 'pattern' | head -30
```
Get first 30 result lines.

## Count Total Matches
```bash
rg -n -t js -e 'pattern' | wc -l
```

## Sort and Deduplicate
```bash
rg -o -t js -e 'import.*from.*' | sort | uniq
```
`-o` shows only matching part. Useful for extracting patterns.

## Filter Results Further
```bash
rg -n -t js -e 'function' | rg -e 'export'
```
Find functions, then filter to only exported ones.

---

# File Type Filters (-t)

**Common types:**
- `-t js` - JavaScript (.js, .jsx, .mjs, .cjs, .vue)
- `-t ts` - TypeScript (.ts, .tsx, .cts, .mts)
- `-t py` - Python (.py, .pyi)
- `-t go` - Go (.go)
- `-t rust` - Rust (.rs)
- `-t java` - Java (.java, .jsp, .properties)
- `-t ruby` - Ruby (.rb, .gemspec, Gemfile, Rakefile)
- `-t c` - C (.c, .h)
- `-t cpp` - C++ (.cpp, .hpp, .cc, .hh)
- `-t sh` - Shell (.sh, .bash, .zsh, .bashrc)
- `-t html` - HTML (.html, .htm, .ejs)
- `-t css` - CSS (.css, .scss)
- `-t md` - Markdown (.md, .markdown, .mdx)
- `-t json` - JSON (.json)
- `-t yaml` - YAML (.yaml, .yml)

**Multiple types:**
```bash
rg -t js -t ts -e 'pattern'
```

**Glob patterns (more flexible):**
```bash
rg -g '*.test.js' -e 'pattern'          # Test files only
rg -g '!*.test.js' -e 'pattern'         # Exclude test files
rg -g 'src/**/*.js' -e 'pattern'        # Specific directory pattern
```

---

# Pattern Syntax Quick Reference

## Literal Search (Use -F)
```bash
rg -F -e 'exact.string'
```
When pattern has special chars, use `-F` instead of escaping.

## Regex Patterns
```bash
rg -e 'function\s+\w+'           # Function declarations
rg -e 'import.*from\s+["\']'     # Import statements
rg -e 'class\s+\w+.*\{'          # Class definitions
rg -e '^\s*#'                    # Lines starting with #
rg -e 'TODO:|FIXME:|XXX:'        # Multiple comment markers
```

## Common Regex Elements
- `\s` - whitespace
- `\w` - word character
- `\d` - digit
- `.` - any character
- `.*` - zero or more any character
- `\b` - word boundary (or use `-w` flag)
- `^` - start of line
- `$` - end of line
- `[abc]` - character class
- `(foo|bar)` - alternation

---

# Decision Flow

```
Need to search code?
│
├─ Simple pattern, no special needs?
│  → Use Grep tool (structured output)
│
├─ Need one-shot with context?
│  → rg -n -C 2 -t TYPE -e 'pattern'
│
├─ Pattern has dots, parens, special chars?
│  → rg -F -n -C 2 -t TYPE -e 'exact.string'
│
├─ Need precise word matching?
│  → rg -w -n -C 2 -t TYPE -e 'word'
│
├─ Need to find files WITHOUT something?
│  → rg -L -t TYPE -e 'pattern'
│
└─ Need to compose with other commands?
   → rg -n -t TYPE -e 'pattern' | head/wc/sort/etc
```

---

# Common Workflows

## "Find all uses of this function"
```bash
rg -n -C 2 -t js -e 'functionName\('
```
Use `\(` to find actual calls (not definitions).

## "Which files import this package?"
```bash
rg -l -t js -e 'from ["\']package-name["\']'
```

## "How is this class used?"
```bash
rg -n -C 3 -t py -e 'ClassName'
```
More context (C 3) to see usage patterns.

## "Find TODOs in specific directory"
```bash
rg -n -e 'TODO:' src/
```

## "Find files that import X but not Y"
```bash
rg -l -t js -e 'import.*from.*package-x' | rg -v -F -e 'package-y'
```

## "Count occurrences across codebase"
```bash
rg -c -t js -e 'pattern' | rg -e ':' | wc -l
```
Count files with matches.

---

# Best Practices

## 1. Start with Standard Pattern
```bash
rg -n -C 2 -t TYPE -e 'pattern'
```
Adjust only if needed.

## 2. Use -F for Literal Strings
Don't escape regex chars - use `-F`:
```bash
# BAD: rg -e 'function\(\)'
# GOOD: rg -F -e 'function()'
```

## 3. Always Use Single Quotes
```bash
# GOOD: rg -e 'pattern'
# BAD:  rg -e "pattern"  # Shell may interpret special chars
```

## 4. Use Type Filters
```bash
# GOOD: rg -t js -e 'pattern'
# LESS GOOD: rg -e 'pattern'  # Searches everything
```

## 5. Limit Large Results
```bash
rg -n -t js -e 'common_word' | head -50
```

## 6. Use -w for Precision
```bash
# Finds "test" in "testing", "latest", etc:
rg -e 'test'

# Finds only "test" as whole word:
rg -w -e 'test'
```

---

# When to Use Grep Tool Instead

Use Grep tool when:
- Simple pattern with no special flags needed
- Want structured output modes (files/content/count)
- Don't need to pipe results
- Pattern doesn't need -F, -v, or -w

Use Bash(rg) when:
- Need one-shot results with context
- Need -F (literal), -v (invert), -w (word boundary)
- Want to pipe/compose with other commands
- Need maximum control and efficiency

**Default to Bash(rg) for most searches** - it's more efficient for one-shot results.

---

# Summary

**Default search command:**
```bash
rg -n -C 2 -t TYPE -e 'pattern'
```

**Key flags to remember:**
- `-F` - Literal search (avoid escaping)
- `-w` - Word boundaries (precise)
- `-v` - Invert match (find files WITHOUT)
- `-l` - List files only
- `-L` - List files that DON'T match

**Compose with pipes:**
```bash
rg ... | head -N      # Limit results
rg ... | wc -l        # Count
rg ... | rg ...       # Filter further
```

This reference provides practical patterns for efficient one-shot searches.