File Search

File Search Skill

Efficient CLI search tools for AI agents.

Tool Selection Guide

Decision flow: text → rg | structural → sg | rule packs → semgrep | filenames → fd | PDFs/archives → rga | LOC → tokei/scc

Quick Examples

rg 'def \w+\(' -t py src/          # rg: text search in Python files
rg -c 'TODO' -t js | wc -l         # rg: count first, then drill down
sg --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang js  # sg: structural replace
fd -g '*.test.ts' --changed-within 1d  # fd: -g for compound suffixes (NOT -e)
fd -g '*_test.go' -X rg 'func Test'   # fd+rg: find files, verify contents
rga 'quarterly revenue' docs/       # rga: search inside PDFs/archives
tokei --sort code                   # tokei: language stats
scc --wide                          # scc: complexity + COCOMO

Best Practices

1. Start narrow. Specify types (-t, --lang, -e), scope dirs, count first (rg -c). 2. Exclude noise (-g '!vendor/', fd -E node_modules). 3. Batch independent queries. Union patterns with rg -e P1 -e P2 -e P3 (one walk, one process), or issue distinct queries as parallel tool calls in a single message — never sequential && chains for independent searches. 4. `--json` for programmatic processing. 5. rg ≠ fd types. rg -t ts includes .tsx; fd -e ts does NOT. No -t tsx in rg.

See references/search-strategies.md.

Beyond Local Files

If local search finds nothing and context lives in issues/PRs/external docs — hand off (gh, Jira, WebFetch). Issue keys in comments signal this.

See references/remote-handoff.md.

References

ast-grep Pattern Recipes

Structural search patterns for sg (ast-grep), organized by language.

ast-grep matches code by AST structure, not text. This means patterns are immune to whitespace differences, comment variations, and formatting styles.

---

Metavariable Reference

Key rules:

• Named metavariables ($VAR) capture their match and must match consistently

within a pattern (same $VAR = same value).

• $$$ is greedy and matches any number of arguments, statements, etc.
• Use $_ when you do not care about capturing the value.

---

JavaScript / TypeScript

React Patterns

# useState hooks
sg --pattern 'const [$STATE, $SETTER] = useState($$$)' --lang tsx

# useEffect with dependency array
sg --pattern 'useEffect(() => { $$$ }, [$$$])' --lang tsx

# useEffect without dependencies (runs every render)
sg --pattern 'useEffect(() => { $$$ })' --lang tsx

# Component definitions (function)
sg --pattern 'function $NAME($$$) { $$$ return $$$ }' --lang tsx

# Arrow function components
sg --pattern 'const $NAME = ($$$) => { $$$ }' --lang tsx

# JSX with specific prop
sg --pattern '<$COMP className={$$$} />' --lang tsx
sg --pattern '<$COMP onClick={$$$}>$$$</$COMP>' --lang tsx

# Custom hook calls
sg --pattern 'const $RESULT = use$HOOK($$$)' --lang tsx

Async/Await Patterns

# Async function declarations
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js

# Await expressions
sg --pattern 'await $EXPR' --lang js

# Try/catch around await
sg --pattern 'try { $$$ await $EXPR $$$ } catch ($ERR) { $$$ }' --lang ts

# Promise.all usage
sg --pattern 'await Promise.all([$$$])' --lang ts

# Unhandled promise (missing await)
sg --pattern '$VAR.$METHOD($$$).then($$$)' --lang ts

Error Handling

# Empty catch blocks
sg --pattern 'try { $$$ } catch ($ERR) { }' --lang js

# Console.log in catch (often should be proper logging)
sg --pattern 'catch ($ERR) { $$$ console.log($$$) $$$ }' --lang js

# Throw new Error
sg --pattern 'throw new Error($MSG)' --lang ts

# Throw non-Error objects
sg --pattern 'throw $MSG' --lang ts

Module Patterns

# Default exports
sg --pattern 'export default $EXPR' --lang ts

# Named exports
sg --pattern 'export const $NAME = $VALUE' --lang ts
sg --pattern 'export function $NAME($$$) { $$$ }' --lang ts

# Dynamic imports
sg --pattern 'import($PATH)' --lang ts
sg --pattern 'await import($PATH)' --lang ts

Common Anti-Patterns

# Direct DOM manipulation in React
sg --pattern 'document.getElementById($$$)' --lang tsx
sg --pattern 'document.querySelector($$$)' --lang tsx

# setState in useEffect without cleanup
sg --pattern 'useEffect(() => { $$$ $SETTER($$$) $$$ })' --lang tsx

# Object mutation
sg --pattern '$OBJ.$PROP = $VALUE' --lang ts

---

Python

Function and Class Patterns

# Function definitions
sg --pattern 'def $NAME($$$):
    $$$' --lang py

# Async function definitions
sg --pattern 'async def $NAME($$$):
    $$$' --lang py

# Class with inheritance
sg --pattern 'class $NAME($BASE):
    $$$' --lang py

# Static methods
sg --pattern '@staticmethod
def $NAME($$$):
    $$$' --lang py

# Class methods
sg --pattern '@classmethod
def $NAME(cls, $$$):
    $$$' --lang py

# Property definitions
sg --pattern '@property
def $NAME(self):
    $$$' --lang py

Decorator Patterns

# Any decorated function
sg --pattern '@$DECORATOR
def $NAME($$$):
    $$$' --lang py

# Specific decorator
sg --pattern '@app.route($$$)
def $NAME($$$):
    $$$' --lang py

# Decorator with arguments
sg --pattern '@$DECORATOR($$$)
def $NAME($$$):
    $$$' --lang py

# Pytest fixtures
sg --pattern '@pytest.fixture($$$)
def $NAME($$$):
    $$$' --lang py

Error Handling

# Bare except (catches everything including SystemExit)
sg --pattern 'try:
    $$$
except:
    $$$' --lang py

# Except with pass (silenced errors)
sg --pattern 'except $EXCEPTION:
    pass' --lang py

# Broad exception catching
sg --pattern 'except Exception as $ERR:
    $$$' --lang py

# Context managers
sg --pattern 'with $EXPR as $VAR:
    $$$' --lang py

Type Annotation Patterns

# Typed function signatures
sg --pattern 'def $NAME($$$) -> $RETURN:
    $$$' --lang py

# Optional types
sg --pattern 'Optional[$TYPE]' --lang py

# Union types
sg --pattern 'Union[$$$]' --lang py

---

PHP

Class and Method Patterns

# Class definitions
sg --pattern 'class $NAME { $$$ }' --lang php
sg --pattern 'class $NAME extends $BASE { $$$ }' --lang php
sg --pattern 'class $NAME implements $IFACE { $$$ }' --lang php

# Method definitions
sg --pattern 'public function $NAME($$$) { $$$ }' --lang php
sg --pattern 'protected function $NAME($$$) { $$$ }' --lang php
sg --pattern 'private function $NAME($$$) { $$$ }' --lang php

# Static methods
sg --pattern 'public static function $NAME($$$) { $$$ }' --lang php

# Constructor
sg --pattern 'public function __construct($$$) { $$$ }' --lang php

# Constructor property promotion (PHP 8+)
sg --pattern 'public function __construct(
    $$$
) { $$$ }' --lang php

Common PHP Patterns

# Array operations
sg --pattern 'array_map($CALLBACK, $$$)' --lang php
sg --pattern 'array_filter($ARRAY, $$$)' --lang php

# Method chaining
sg --pattern '$OBJ->$METHOD1($$$)->$METHOD2($$$)' --lang php

# Type-hinted parameters
sg --pattern 'function $NAME($TYPE $PARAM) { $$$ }' --lang php

# Null coalescing
sg --pattern '$EXPR ?? $DEFAULT' --lang php

# Match expression (PHP 8+)
sg --pattern 'match ($EXPR) { $$$ }' --lang php

TYPO3/Symfony/Laravel Patterns

# Dependency injection
sg --pattern 'public function __construct($TYPE $PARAM) { $$$ }' --lang php

# Route annotations
sg --pattern '#[Route($$$)]' --lang php

# Doctrine annotations
sg --pattern '#[ORM\Column($$$)]' --lang php

---

Go

Function and Method Patterns

# Function definitions
sg --pattern 'func $NAME($$$) $RETURN { $$$ }' --lang go

# Methods with receiver
sg --pattern 'func ($RECV $TYPE) $NAME($$$) $RETURN { $$$ }' --lang go

# Pointer receiver methods
sg --pattern 'func ($RECV *$TYPE) $NAME($$$) $RETURN { $$$ }' --lang go

# Init functions
sg --pattern 'func init() { $$$ }' --lang go

# Main functions
sg --pattern 'func main() { $$$ }' --lang go

Error Handling

# Standard error check
sg --pattern 'if $ERR != nil { $$$ }' --lang go

# Error return without wrapping
sg --pattern 'if $ERR != nil { return $ERR }' --lang go

# Error wrapping with fmt.Errorf
sg --pattern 'fmt.Errorf($FMT, $$$)' --lang go

# errors.Is / errors.As
sg --pattern 'errors.Is($ERR, $TARGET)' --lang go
sg --pattern 'errors.As($ERR, $TARGET)' --lang go

Concurrency

# Goroutine launches
sg --pattern 'go $FUNC($$$)' --lang go

# Channel operations
sg --pattern '$CH <- $VALUE' --lang go
sg --pattern '<-$CH' --lang go

# Select statements
sg --pattern 'select { $$$ }' --lang go

# Mutex usage
sg --pattern '$MU.Lock()' --lang go
sg --pattern 'defer $MU.Unlock()' --lang go

# WaitGroup
sg --pattern '$WG.Add($N)' --lang go
sg --pattern 'defer $WG.Done()' --lang go

Struct and Interface Patterns

# Struct definitions
sg --pattern 'type $NAME struct { $$$ }' --lang go

# Interface definitions
sg --pattern 'type $NAME interface { $$$ }' --lang go

# Struct literal initialization
sg --pattern '$TYPE{ $$$ }' --lang go

Testing

# Test functions
sg --pattern 'func Test$NAME(t *testing.T) { $$$ }' --lang go

# Benchmark functions
sg --pattern 'func Benchmark$NAME(b *testing.B) { $$$ }' --lang go

# Table-driven tests
sg --pattern 'for $_, $TC := range $CASES { $$$ }' --lang go

# t.Run subtests
sg --pattern 't.Run($NAME, func(t *testing.T) { $$$ })' --lang go

---

Rust

Function Patterns

# Function definitions
sg --pattern 'fn $NAME($$$) -> $RETURN { $$$ }' --lang rust

# Async functions
sg --pattern 'async fn $NAME($$$) -> $RETURN { $$$ }' --lang rust

# Impl blocks
sg --pattern 'impl $TYPE { $$$ }' --lang rust

# Trait implementations
sg --pattern 'impl $TRAIT for $TYPE { $$$ }' --lang rust

Error Handling

# unwrap calls (potential panics)
sg --pattern '$EXPR.unwrap()' --lang rust

# expect calls
sg --pattern '$EXPR.expect($MSG)' --lang rust

# Match on Result
sg --pattern 'match $EXPR { Ok($VAL) => $$$, Err($ERR) => $$$ }' --lang rust

# Question mark operator
sg --pattern '$EXPR?' --lang rust

---

Tips for Writing ast-grep Patterns

1. Start simple. Begin with a small pattern and add complexity. If $FUNC($$$) matches too broadly, add more structure.

2. Use `--json` output for programmatic processing. The JSON includes file path, line/column ranges, and matched metavariable bindings.

3. Test patterns interactively at https://ast-grep.github.io/playground to verify they match what you expect.

4. Language matters. Always specify --lang -- the same text may parse differently in different languages.

5. Metavariable consistency. Within a single pattern, the same $NAME must match the same text. Use different names ($A, $B) for different captures.

6. Whitespace is ignored in pattern matching. func ( $ARG ) matches func(arg), func( arg ), etc.

---

When to Use ast-grep Over ripgrep

• Matching code structure regardless of formatting/whitespace
• Finding function calls with specific argument patterns
• Matching patterns that span multiple lines unpredictably
• Refactoring patterns (find + replace structurally)
• When regex would be too fragile for the code pattern

---

Basic Usage

# Search with a pattern in a language
sg --pattern 'console.log($$$)' --lang js

# Search in specific directory
sg --pattern 'fmt.Errorf($$$)' --lang go src/

# JSON output for programmatic use
sg --pattern '$FUNC($$$)' --lang py --json

# Find and replace structurally
sg --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang js

Code Metrics: tokei and scc

Fast codebase analysis tools for counting lines of code, comments, and blanks by language.

---

tokei

# Basic usage -- counts all code in current directory
tokei

# Count specific directory
tokei src/

# Sort by lines of code
tokei --sort code

# Specific languages only
tokei --type=Python,JavaScript

# Output as JSON for processing
tokei --output json

# Exclude directories
tokei --exclude='vendor/*' --exclude='node_modules/*'

---

scc

Like tokei but adds complexity estimation and COCOMO cost modeling.

# Basic usage
scc

# Specific directory
scc src/

# Sort by lines of code
scc --sort-by code

# Include complexity and COCOMO
scc --wide

# Specific languages
scc --include-ext py,js,ts

# Exclude directories
scc --exclude-dir vendor,node_modules

# Output as JSON
scc --format json

---

When to Use Which

fd Guide

Fast, user-friendly file finder. Replaces find with sane defaults: respects .gitignore, colorized output, regex by default, smart case.

---

Key Flags

-e EXT          Filter by extension (-e py, -e rs)
-t TYPE         Filter by type: f (file), d (directory), l (symlink), x (executable)
-H              Include hidden files
-I              Do not respect .gitignore
-E PATTERN      Exclude glob pattern
-d DEPTH        Limit directory depth
-x CMD          Execute command for each result
-X CMD          Execute command with all results at once
-0              Null-byte separator (for xargs -0)
-a              Show absolute paths
-L              Follow symlinks
-g GLOB         Use glob pattern instead of regex
-p              Match against full path (not just filename)
--changed-within TIME   Files modified within duration (e.g., 1h, 2d, 1w)
--changed-before TIME   Files modified before duration
-S / --size     Filter by size (e.g., +1m for >1MB)

---

Important: -e Matches the Literal Final Extension Only

fd -e ts matches *.ts — files whose extension is exactly .ts. Unlike rg -t ts (which includes .tsx), fd -e is a literal extension match:

fd -e ts                            # matches *.ts only (NOT *.tsx)
fd -e js                            # matches *.js only (NOT *.jsx or *.mjs)
fd -e ts -e tsx                     # matches *.ts AND *.tsx

# WRONG: compound suffixes don't work with -e
fd -e test.ts                       # matches nothing useful

# RIGHT: use glob patterns for compound suffixes
fd -g '*.test.ts'                   # matches foo.test.ts
fd -g '*.{test,spec}.ts'           # matches foo.test.ts and foo.spec.ts

---

Common Usage

# Find Python files
fd -e py

# Find all test files
fd 'test_.*\.py$'
fd -g '*_test.go'

# Find files modified in the last day
fd -e js --changed-within 1d

# Find large files
fd -S +10m

# Find and delete all .pyc files
fd -e pyc -x rm {}

# Find directories named "test" or "tests"
fd -t d '^tests?$'

# Find executable files
fd -t x

# Find files excluding certain directories
fd -e ts -E node_modules -E dist

# Find hidden config files
fd -H '^\.' -t f

# Find files and pipe to rg for content search
fd -0 -e py | xargs -0 rg 'import os'

---

fd + rg Combinations

# Find Python files, then search for a pattern
fd -e py -x rg -l 'async def'

# Find recently changed files and search them
fd --changed-within 2h -e ts -X rg 'TODO'

# Find config files and search for a key
fd -g '*.{yml,yaml,toml,json}' -X rg 'database'

Beyond Local Files — Remote Handoff Guide

This skill covers local CLI search tools. When the context you need lives outside the repository, hand off to the appropriate tool or skill.

---

Handoff Table

---

When to Hand Off

• rg/fd return no results and the answer likely lives in issues, PRs,

or external docs

• Code comments reference issue keys (#123, PROJ-456, JIRA-789)
• You need the rationale behind a change (check the PR/MR, not just the diff)
• The user asks about deployment status, CI results, or external service state

---

Combining Local and Remote Search

A common pattern is local-first, then remote:

1. Local: rg 'PROJ-1234' — find where the issue is referenced in code 2. Local: git log --grep='PROJ-1234' — find commits mentioning it 3. Remote: gh issue view 1234 or Jira API — get current status 4. Decision: combine local context with remote status to answer the question

---

Signals That Context Is Remote

• Comments like // TODO: see #456, // Workaround for PROJ-123
• Commit messages referencing PRs (Merge pull request #89)
• Configuration referencing external services (URLs, API endpoints)
• Questions about "why" something was done (rationale lives in PRs/issues)

rga (ripgrep-all) Guide

Extends ripgrep to search inside PDFs, Word/Excel/PowerPoint, SQLite databases, compressed archives, and more.

---

When to Use rga Instead of rg

• Searching PDF documents for text
• Searching Word (.docx), Excel (.xlsx), PowerPoint (.pptx) files
• Searching inside .zip, .tar.gz, .tar.bz2 archives
• Searching SQLite database contents
• Searching EPUB ebooks

---

Supported Formats

---

Usage

# Search PDFs for a term
rga 'quarterly revenue' docs/

# Search all document types
rga 'confidential' --rga-adapters=+pdfpages,poppler /path/to/docs/

# Search inside archives
rga 'config' backups/*.tar.gz

# Search with ripgrep flags (most rg flags work)
rga -i -c 'error' logs/

# List matching files only
rga -l 'password' /shared/docs/

---

Dependencies

rga requires adapters to process different file types:

• PDF: poppler (pdftotext) — usually pre-installed on Linux
• Office (.docx, .xlsx, .pptx): built-in via zip + XML parsing
• Legacy Office (.doc, .xls): requires libreoffice or catdoc
• Archives: requires standard tools (tar, unzip, etc.)

Install adapters: sudo apt install poppler-utils (Debian/Ubuntu) or brew install poppler (macOS).

---

Cache Behavior

rga caches extracted text for faster subsequent searches. The cache is stored in the system cache directory. Use --rga-no-cache to disable.

ripgrep Pattern Recipes

Practical rg patterns organized by use case. All examples assume you are in the project root directory.

---

Security Scanning

# Hardcoded passwords/secrets
rg -i '(password|passwd|secret|api_key|apikey|token)\s*[:=]' -g '!*.lock'
rg -i '(password|secret|key)\s*=\s*["\x27][^"\x27]{8,}' -g '!*.lock' -g '!*.md'

# AWS credentials
rg '(AKIA|ASIA)[A-Z0-9]{16}'
rg 'aws_secret_access_key\s*[:=]'

# Private keys
rg 'BEGIN (RSA |DSA |EC |OPENSSH )?PRIVATE KEY'

# JWT tokens
rg 'eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}'

# Dangerous functions
rg '\beval\s*\(' -t py -t js -t php -t ruby
rg '\bexec\s*\(' -t py -t php
rg 'innerHTML\s*=' -t js -t ts

# SQL injection vectors
rg '(query|execute)\s*\(.*["\x27]\s*\+' -t py -t js -t java
rg '\$\w+.*->query\(\s*["\x27]' -t php
rg 'raw\s*\(\s*f["\x27]' -t py  # f-string in raw SQL (Python)

# Insecure HTTP
rg 'http://' -t py -t js -t go -t java -g '!*.lock' -g '!*.md'
rg 'verify\s*=\s*False' -t py    # disabled SSL verification
rg 'rejectUnauthorized.*false' -t js -t ts

# Debug/dev artifacts left in code
rg '(console\.log|print\(|fmt\.Print)' -t js -t py -t go --count-matches
rg 'binding\.pry' -t ruby
rg 'debugger;' -t js -t ts
rg 'dd\(' -t php

---

Dependency Analysis

# Python imports
rg '^from (\S+) import' -t py -o -r '$1' --no-filename | sort -u
rg '^import (\S+)' -t py -o -r '$1' --no-filename | sort -u

# JavaScript/TypeScript imports
rg "^import .+ from ['\"]([^'\"]+)" -t js -t ts -o -r '$1' --no-filename | sort -u
rg "require\(['\"]([^'\"]+)" -t js -o -r '$1' --no-filename | sort -u

# Go imports
rg '"([\w./]+)"' -t go -o -r '$1' --no-filename | sort -u

# PHP use statements
rg '^use\s+([\w\\\\]+)' -t php -o -r '$1' --no-filename | sort -u

# Java imports
rg '^import\s+([\w.]+)' -t java -o -r '$1' --no-filename | sort -u

# Rust use statements
rg '^use\s+([\w:]+)' -t rust -o -r '$1' --no-filename | sort -u

# Find unused imports (files that import X but never reference it again)
# Step 1: find files importing the module
rg -l 'import someModule' -t js
# Step 2: check if the module is used beyond the import line
rg -c 'someModule' -t js  # files with count=1 likely only have the import

---

Code Quality

# TODO/FIXME/HACK/XXX with context
rg '(TODO|FIXME|HACK|XXX|WARN|DEPRECATED):?\s' -n --trim
rg '(TODO|FIXME)\((\w+)\)' -o -r '$1 by $2' --no-filename  # extract assignee

# Deprecated usage
rg '@deprecated' -n -t py -t js -t ts -t java -t php
rg '@Deprecated' -t java

# Magic numbers (numeric literals in logic, not in declarations)
rg 'if.*[^=!<>]==[^=].*\d{2,}' -t py -t js -t go

# Long functions (find function start, count lines until next function)
rg -n 'def \w+\(' -t py  # list all function definitions with line numbers

# Empty exception handling
rg -U 'except.*:\s*\n\s*(pass|\.\.\.)\s*$' -t py
rg -U 'catch\s*\(.*\)\s*\{\s*\}' -t js -t ts -t java

# Commented-out code (heuristic)
rg '^\s*//\s*(if|for|while|return|function|var|let|const)\b' -t js -t ts
rg '^\s*#\s*(if|for|while|return|def|class|import)\b' -t py

# Dead code indicators
rg 'noinspection' -t java -t py
rg '@ts-ignore' -t ts
rg '// eslint-disable' -t js -t ts
rg '# type: ignore' -t py
rg '# noqa' -t py
rg '# noinspection' -t py

---

Refactoring

# Find all usages of a function
rg '\bfunctionName\b' -t py -n

# Find function definitions (various languages)
rg 'def functionName\(' -t py
rg 'function functionName\(' -t js
rg 'func functionName\(' -t go
rg 'fn functionName\(' -t rust

# Find class definitions
rg 'class ClassName' -t py -t java -t ts

# Find method calls on a specific type
rg '\.methodName\(' -t go -t java -t ts

# Find variable assignments
rg '\bvarName\s*[:=]' -t py -t js -t ts

# Find all files referencing a module (across languages)
rg -l '(import|require|use|from).*moduleName'

# Rename preview (show what would change)
rg 'oldName' -t py -r 'newName'   # shows replacements, does not write

# Find interface implementations (Go)
rg 'func \(.*\) MethodName\(' -t go

# Find all routes/endpoints
rg '(@app\.(get|post|put|delete|patch)|router\.(get|post|put|delete|patch))' -t py
rg 'app\.(get|post|put|delete|patch)\(' -t js -t ts
rg '(GET|POST|PUT|DELETE|PATCH)\s+/' -t go

---

Configuration and Infrastructure

# Find all config files
rg -l '.' -g '*.{yml,yaml,toml,ini,cfg,conf,json,env,env.*}'

# Find Docker-related configs
rg -l '.' -g 'Dockerfile*' -g 'docker-compose*' -g '.dockerignore'

# Find port bindings
rg '(port|PORT)\s*[:=]\s*\d+' -g '*.{yml,yaml,toml,json,env,py,js,go}'
rg ':\d{4,5}' -g '*.{yml,yaml,toml,env}'

# Find database connection strings
rg '(postgres|mysql|mongo|redis|sqlite)://' -g '!*.lock' -g '!*.md'

# Find environment variable references
rg 'os\.environ\[' -t py
rg 'os\.Getenv\(' -t go
rg 'process\.env\.' -t js -t ts
rg '\$_ENV\[' -t php
rg 'getenv\(' -t php

# Find CI/CD references
rg -l '.' -g '.github/workflows/*.yml'
rg -l '.' -g '.gitlab-ci.yml' -g 'Jenkinsfile' -g '.circleci/*'

---

Advanced Flags and Techniques

# Invert match (show lines NOT matching)
rg -v 'pattern' file.txt

# Show only the matched portion
rg -o 'pattern' -t py

# Capture groups with replacement (extract data)
rg 'version:\s*"([^"]+)"' -o -r '$1' --no-filename

# Search binary files
rg --binary 'pattern'

# Search compressed files (use rga instead for full support)
rg -z 'pattern' archive.gz

# Null-byte separated output (for xargs -0)
rg -l0 'pattern' | xargs -0 wc -l

# Limit number of results
rg 'pattern' --max-count 5   # max 5 matches per file
rg 'pattern' -l | head -20   # first 20 matching files

# Search with lookahead/lookbehind (PCRE2)
rg -P '(?<=import\s)\w+' -t py    # word after "import "
rg -P 'def \w+\((?=.*self)' -t py  # methods (have self param)

# Stats about the search
rg 'pattern' --stats

# Sorted output by file path
rg 'pattern' --sort path

# Glob patterns for includes
rg 'pattern' -g '*.{ts,tsx}' -g '!*.test.*' -g '!*.spec.*'

---

Performance Tips

• Always specify file types (-t) when possible. This avoids scanning

irrelevant files entirely.

• Limit directory scope to the relevant subtree.
• Use `-l` (list files) when you only need to know which files match, not

the matching lines.

• Use `--max-count N` to stop searching a file after N matches.
• Exclude large directories like vendor/, node_modules/, dist/,

.git/ with -g '!dir/'.

• Use `-F` (fixed string) when your pattern has no regex metacharacters.

This is faster than regex matching.

• Pipe to `head` when exploring. You do not need all 10,000 results to

understand the pattern.

---

Key Flags Reference

-i              Case-insensitive search
-w              Match whole words only
-l              List matching file paths only (no content)
-c              Count matching lines per file
-n              Show line numbers (default)
-t TYPE         Restrict to file type (e.g., -t py, -t js, -t go)
-T TYPE         Exclude file type
-g 'GLOB'       Filter by glob pattern (e.g., -g '*.tsx')
--json          Machine-readable JSON output
-A N / -B N     Show N lines after/before match
-C N            Show N lines of context (before + after)
-U              Enable multiline matching
--hidden        Include hidden files (dotfiles)
--no-ignore     Search files ignored by .gitignore
-F              Treat pattern as fixed string (no regex)
-e PATTERN      Specify pattern (useful for multiple patterns or leading dashes)
--count-matches Count individual matches per file (vs -c which counts matching lines)
-r REPLACEMENT  Replace matches in output (preview, does not modify files)

---

Progressive Refinement Strategy

Start narrow, widen only if needed:

# 1. Count matches first to gauge scope
rg -c 'pattern' -t py

# 2. If too many, narrow by directory
rg -c 'pattern' -t py src/core/

# 3. View results with context
rg -n -C 2 'pattern' -t py src/core/

# 4. If still too many, add word boundaries or refine regex
rg -nw 'exactFunction' -t py src/core/

---

Common Patterns

# Find function definitions in Python
rg 'def \w+\(' -t py

# Find class definitions in TypeScript
rg 'class \w+' -t ts

# Find all imports of a module
rg "from ['\"](react|vue)" -t js -t ts

# Find TODO/FIXME comments
rg '(TODO|FIXME|HACK|XXX):' -n

# Find environment variable usage
rg '\$\{?\w+\}?' -t sh

# Find SQL injection risks
rg 'execute\(.*\+.*\)' -t py
rg '\$\w+.*->query\(' -t php

# Search with multiple patterns
rg -e 'pattern1' -e 'pattern2' -t js

# Search for multiline patterns (e.g., function with decorator)
rg -U '@deprecated\n.*def \w+' -t py

# Exclude directories
rg 'pattern' -g '!vendor/' -g '!node_modules/'

# Fixed string search (no regex interpretation)
rg -F 'array_map($callback, $items)' -t php

---

File Type Targeting

ripgrep has built-in type definitions. List all with rg --type-list.

Common types: py, js, ts, go, rust, java, php, ruby, css, html, json, yaml, toml, md, sh, sql, c, cpp.

Note: -t ts typically matches .ts AND .tsx. Run rg --type-list | grep ts to check your version — some builds include a separate tsx type. Similarly, -t js usually covers .js, .jsx, .mjs. Always verify with rg --type-list.

# Multiple types
rg 'pattern' -t js -t ts

# Custom type definition (one-off)
rg --type-add 'web:*.{html,css,js}' -t web 'pattern'

Search Strategies

Unfocused searches produce overwhelming output. Always scope searches deliberately.

---

1. Specify File Types

# Good: targeted by type
rg 'pattern' -t py
sg --pattern '$FUNC($$$)' --lang go

# Bad: search everything
rg 'pattern'

---

2. Limit Directory Scope

# Good: specific directory
rg 'pattern' src/api/
fd -e ts src/components/

# Bad: search from root
rg 'pattern' /

---

3. Count Before Viewing

# First: how many matches?
rg -c 'pattern' -t py | wc -l    # number of files
rg --count-matches 'pattern' -t py  # total matches per file

# Then: view if manageable
rg -n 'pattern' -t py

---

4. Progressive Refinement

# Start: broad count
rg -c 'import' -t py | wc -l
# => 847 files -- too many

# Narrow: specific module
rg -c 'from requests import' -t py | wc -l
# => 23 files -- manageable

# View: with context
rg -n -C 1 'from requests import' -t py

---

5. Exclude Noise

# Exclude generated/vendor code
rg 'pattern' -g '!vendor/' -g '!node_modules/' -g '!*.min.js' -g '!dist/'
fd -e py -E __pycache__ -E .venv -E '*.pyc'

---

6. Batch & Parallelize Independent Queries

rg walks the filesystem once per invocation. N sequential calls = N walks + N startup costs. Two ways to collapse that:

6a. Union patterns in one process (rg -e ... -e ...)

When you want any of several patterns from the same scope, pass them all to one rg:

# Good: one walk, one process
rg -t php -e 'RequestHandlerInterface' -e 'MiddlewareInterface' -e 'PSR-15'

# Bad: three walks
rg -t php 'RequestHandlerInterface'
rg -t php 'MiddlewareInterface'
rg -t php 'PSR-15'

Use -f patterns.txt for many patterns. Note: ripgrep does not annotate output with which -e/-f pattern matched — neither plain text nor --json exposes a stable pattern index. If you need provenance, run separate searches or post-process by re-matching the captured text.

rg also accepts multiple -t flags and multiple path arguments, so prefer batching scope into a single call:

# Good: one walk, multiple types
rg -t php -t js -t ts 'pattern'

# Good: one walk, multiple paths
rg 'pattern' src/ tests/ docs/

6b. Parallel tool calls for distinct intents

Use parallel tool calls when the queries can't collapse into one rg invocation — different patterns in different scopes, different tools, or different post-processing. Issue them as parallel tool calls in a single message; the agent harness runs them concurrently and total wall time ≈ slowest single call.

Good candidates for parallel calls:

• Different patterns in different scopes: rg 'Error' logs/ + rg 'TODO' src/
• Different tools on same target: rg X + fd -g '*X*' + tokei
• Different search modes: rg 'pattern' + sg --pattern 'func($$$)'

Anti-pattern: chaining independent greps with && in one Bash call — the shell still runs them sequentially.

semgrep Pattern Recipes

Rule-driven structural code search with semgrep, focused on security and lint patterns. Use when sg (ast-grep) is the wrong tool: semgrep ships with curated rule packs, supports taint analysis (source → sink dataflow), and is the standard for security CI gates.

semgrep vs ast-grep

Rule of thumb: reach for sg when you have a structural pattern in your head; reach for semgrep when you want to apply a catalog of patterns (OWASP, CWE, framework-specific lints).

Quick Examples

# Apply the curated security rule pack (no local rules needed)
semgrep --config=auto .

# Run a specific rule pack
semgrep --config=p/security-audit .
semgrep --config=p/owasp-top-ten .
semgrep --config=p/r2c-ci .

# Single inline pattern (ad-hoc, no YAML)
semgrep -e 'eval(...)' --lang python .
semgrep -e 'exec($CMD)' -e 'os.system($CMD)' --lang python .

# JSON output for pipelines
semgrep --config=auto --json --quiet .

# Only report severity ERROR (skip WARNING/INFO)
semgrep --config=auto --severity=ERROR .

# Limit scope
semgrep --config=auto --include='*.py' src/

Inline Patterns by Language

# Python: dangerous deserialization
semgrep -e 'pickle.loads($X)' --lang python .
semgrep -e 'yaml.load($X)' --lang python .   # missing SafeLoader

# Python: SQL string concatenation
semgrep -e 'cursor.execute("..." + $X)' --lang python .

# JavaScript/TypeScript: dangerous DOM sinks
semgrep -e '$EL.innerHTML = $X' --lang js .
semgrep -e 'document.write($X)' --lang js .

# Go: ignored errors (both assignment and short-declaration forms)
semgrep -e '_, _ = $F(...)' -e '_, _ := $F(...)' --lang go .

# PHP: unsafe shell
semgrep -e 'shell_exec($X)' --lang php .
semgrep -e 'eval($X)' --lang php .

Custom Rule (YAML)

For anything you want to reuse, write a rule file:

# .semgrep/no-eval.yml
rules:
  - id: no-eval
    message: "Avoid eval() — use ast.literal_eval or a parser."
    severity: ERROR
    languages: [python]
    pattern: eval(...)

Run it:

semgrep --config=.semgrep/ .

Taint Mode (Dataflow)

Use when you need to track that user input flows into a dangerous sink. Pattern-only matches miss this; taint mode tracks it across assignments and function calls.

# .semgrep/sql-injection.yml
rules:
  - id: sql-from-request
    mode: taint
    message: "User input flows into raw SQL."
    severity: ERROR
    languages: [python]
    pattern-sources:
      - pattern: request.args.get($X)
      - pattern: request.form.get($X)
    pattern-sinks:
      - pattern: cursor.execute($Q)

CI Integration

# Fail the build on findings of severity ERROR
semgrep --config=auto --severity=ERROR --error .

# Diff-aware: only scan changed lines (fast CI mode)
semgrep ci --baseline-ref=origin/main

When NOT to Use semgrep

• Unstructured text search → use rg instead. semgrep parses code

(and structured formats like YAML/JSON); it cannot match log lines or free-form prose.

• One-off structural refactor with a rewrite → use sg instead. Its

--rewrite is first-class; semgrep autofix is more constrained.

• Files semgrep cannot parse → semgrep reports parse errors on

stderr but produces no findings for those files. If a file is unsupported or unparseable, fall back to rg/sg.

Further Reading

• semgrep docs: https://semgrep.dev/docs
• Rule registry: https://semgrep.dev/r
• Writing rules: https://semgrep.dev/docs/writing-rules/overview

Tool Comparison and Decision Guide

Detailed comparison of the file search tools covered by this skill, with guidance on when to use each one.

---

Quick Decision Flowchart

What are you trying to do?
|
|-- Search for TEXT PATTERNS in files?
|   |
|   |-- In source code files?
|   |   --> Use rg (ripgrep)
|   |
|   |-- In PDFs, Word docs, Excel, archives?
|   |   --> Use rga (ripgrep-all)
|   |
|   |-- Need to match CODE STRUCTURE (not just text)?
|       |
|       |-- One-off structural pattern / refactor?
|       |   --> Use sg (ast-grep)
|       |
|       |-- Apply a CATALOG of security/lint rules (with dataflow)?
|           --> Use semgrep
|
|-- Find FILES by name, path, or attributes?
|   --> Use fd
|
|-- Count lines of code / analyze codebase?
    |
    |-- Just language breakdown and line counts?
    |   --> Use tokei
    |
    |-- Need complexity metrics or cost estimates?
        --> Use scc

---

Feature Comparison: Text Search Tools

When to Choose Which

Choose rg when:

• Searching for string literals, log messages, error codes
• Searching for simple patterns like function names, variable names
• Searching across all file types simultaneously
• You need maximum speed on large codebases
• The pattern is straightforward text or regex

Choose rga when:

• Searching inside PDF documents
• Searching inside Word, Excel, PowerPoint files
• Searching inside compressed archives (.zip, .tar.gz)
• Searching SQLite database contents
• You need rg features but on non-plaintext files

Choose sg when:

• Matching function calls with specific argument patterns
• Finding code structures regardless of formatting
• Matching patterns that span multiple lines unpredictably
• Finding anti-patterns or code smells structurally
• You need to ignore comments and whitespace in matches
• Regex would be too fragile for the code pattern

Choose semgrep when:

• Applying a curated rule pack (OWASP, CWE, framework-specific)
• You need taint analysis (source → sink dataflow), not just pattern match
• Wiring a security/lint gate into CI (semgrep ci)
• Maintaining a reusable rule library in YAML across the team
• The pattern is meaningless without severity/message metadata

For inline patterns and recipes, see references/semgrep-patterns.md.

---

Feature Comparison: File Finding

fd vs find: Syntax Comparison

Always use fd instead of find. It is faster, has better defaults, and requires less typing.

---

Feature Comparison: Code Statistics

When to Choose Which

Choose tokei when:

• You need a fast, accurate language breakdown
• You want lines of code separated by code, comments, blanks
• You need reliable .gitignore support
• You want the fastest possible count

Choose scc when:

• You need complexity estimates alongside line counts
• You need COCOMO cost modeling
• You want to generate badges for a README
• You need per-file breakdowns with complexity

Do NOT use:

• cloc -- significantly slower, no advantage over tokei/scc
• wc -l -- counts all lines including blanks and comments, does not detect

languages, gives misleading results

---

Performance Characteristics

Approximate performance on a large codebase (~500K files, 50M lines):

---

Tool Combinations

These tools work well together. Common combinations:

# Find files, then search contents
fd -e py --changed-within 1d -X rg 'TODO'

# Search for files, then analyze structurally
rg -l 'deprecated' -t py | xargs sg --pattern '@deprecated' --lang py

# Get codebase overview, then search largest language
tokei --sort code  # see which language dominates
rg 'pattern' -t py  # search that language

# Find config files, search for setting
fd -g '*.{yml,yaml}' -X rg 'database:'

# Find test files by name, verify they test something
fd -g '*_test.go' -X rg 'func Test'

# Combine fd size filter with rg
fd -S +100k -e js -X rg 'TODO'  # TODOs in large JS files

---

Installation

All tools are available through common package managers:

# Ubuntu/Debian
sudo apt install ripgrep fd-find
# Note: fd binary is 'fdfind' on Debian/Ubuntu, alias to 'fd'

# macOS (Homebrew)
brew install ripgrep fd ast-grep ripgrep-all tokei scc semgrep

# Cargo (Rust)
cargo install ripgrep fd-find ast-grep tokei

# Go
go install github.com/boyter/scc/v3@latest

# npm (ast-grep)
npm install -g @ast-grep/cli

# pipx (semgrep — Python-based)
pipx install semgrep

---

Further Reading

• ripgrep: https://github.com/BurntSushi/ripgrep
• ast-grep: https://github.com/ast-grep/ast-grep
• semgrep: https://semgrep.dev/docs
• fd: https://github.com/sharkdp/fd
• rga: https://github.com/phiresky/ripgrep-all
• tokei: https://github.com/XAMPPRocky/tokei
• scc: https://github.com/boyter/scc