Explore Codebase

Tool Selection

Need Tool

Structural patterns (functions, classes) sg (ast-grep)

Text/regex patterns (strings, names) rg (ripgrep)

File discovery by name/extension fd

Decision flow: Find files first? fd → pipe to rg /sg . Syntax-aware match needed? sg . Fast text search? rg . Uncertain? Start with rg , escalate to sg if structure matters.

ast-grep Essentials

ast-grep is the least familiar tool -- key syntax summarized here. See references/ast-grep.md for language-specific patterns and YAML rule files.

sg -p 'PATTERN' -l LANG [PATH] sg -p 'PATTERN' --has 'INNER' -l LANG # Must contain sg -p 'PATTERN' --not-has 'INNER' -l LANG # Must not contain sg -p 'PATTERN' --inside 'OUTER' -l LANG # Must be within

Metavariables

Syntax Captures Example

$VAR

Single node console.log($MSG)

$$$VAR

Zero or more nodes function($$$ARGS) -- any arity

$_

Non-capturing $FUNC($) -- match without capture

Rules: must be UPPERCASE, same name = same content ($A == $A matches x == x not x == y ).

Examples

sg -p 'function $NAME($$$ARGS) { $$$ }' -l js sg -p 'async function $NAME($$$) { $$$ }' --has 'await $EXPR' -l js sg -p 'class $NAME extends $PARENT { $$$ }' -l ts sg -p 'def $NAME($$$): $$$' -l py

ripgrep / fd Quick Reference

Standard CLI tools -- use references/ripgrep.md and references/fd.md for full flag tables.

rg PATTERN -t TYPE [PATH] # Search by file type rg -F 'LITERAL' -t TYPE # Fixed string (no regex) rg PATTERN -l # List matching files only rg PATTERN -C 3 # With context lines

fd -e EXT [PATH] # Find by extension fd PATTERN [PATH] # Find by name regex fd -e py | xargs rg 'pattern' # Pipe fd into rg

Performance

• Narrow scope first: fd -e py src/ | xargs rg 'class.*Test'

• Always use type filters: rg PATTERN -t rust , sg -p 'PATTERN' -l rs

• Exclude artifacts: rg PATTERN -g '!node_modules' -g '!dist'