ast-grep

AST-Grep: Structural Code Search and Rewrite

Pattern-aware code search using the ast-grep (sg) binary. Matches code by its syntactic structure, not just text.

When to Use

• Find all calls to a specific function pattern (not just the name)
• Find all instances of a code structure (e.g., all try/catch blocks)
• Rewrite code patterns across the codebase
• When grep is too imprecise (matches in strings, comments, etc.)

Prerequisites

Check if ast-grep is installed:

sg --version 2>/dev/null || npx ast-grep --version 2>/dev/null

If not installed, fall back to grep with careful regex patterns.

Basic Usage

Search

# Find all console.log calls
sg -p 'console.log($$$)' --lang javascript

# Find all function definitions with a specific name pattern
sg -p 'def $NAME($$$):' --lang python

# Find all if statements with a single return
sg -p 'if ($COND) { return $VAL }' --lang typescript

Replace

# Preview first (ALWAYS dry-run before applying)
sg -p 'console.log($$$)' -r 'logger.info($$$)' --lang javascript

# Apply (only after verifying preview)
sg -p 'console.log($$$)' -r 'logger.info($$$)' --lang javascript --update-all

Validate Pattern

# Check if pattern is valid before searching
sg -p 'pattern' --lang python --json=compact 2>&1 | head -5

Pattern Syntax

Token	Meaning
$NAME	Match a single AST node, bind to NAME
$$$	Match zero or more AST nodes (wildcard)
Literal text	Must match exactly in AST structure

Examples:

# Python: find all decorators
@$DECORATOR
def $FUNC($$$):
    $$$

# TypeScript: find all arrow functions assigned to const
const $NAME = ($$$) => $BODY

# Rust: find all match arms with panic
$PAT => panic!($$$)

Language Detection

ast-grep auto-detects language from file extension. Override with --lang:

sg -p 'pattern' --lang python
sg -p 'pattern' --lang typescript
sg -p 'pattern' --lang rust
sg -p 'pattern' --lang go