Initial commit

skills/ripgrep/reference/ripgrep-guide.md

@@ -0,0 +1,326 @@
+# 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.