ast-grep

name	ast-grep
description	Structural code search and refactoring via ast-grep. Reach for this when Edit fails with 'old_string not unique', when refactoring across formatting variations, or when matching code shape rather than text.

ast-grep

Search and rewrite code by AST shape instead of literal text. Resilient to whitespace, line breaks, and formatting differences that defeat string matching.

Invocation

• Search: ast-grep -l LANG -p 'PATTERN'
• Preview a rewrite: ast-grep -l LANG -p 'OLD' -r 'NEW'
• Apply the rewrite: ast-grep -l LANG -p 'OLD' -r 'NEW' --update-all

-l (language) is required -- auto-detection is unreliable. The interactive flag -i does not work from this harness.

Metavariables

• $VAR -- a single AST node (an expression or identifier)
• $$$ARGS -- zero or more list items (function args, statement bodies)
• $$STMT -- multiple statements

Canonical patterns

Rename a function across all call sites:

ast-grep -l typescript -p 'oldFn($$$ARGS)' -r 'newFn($$$ARGS)'

Rename a method on any receiver:

ast-grep -l javascript -p '$OBJ.oldMethod($$$ARGS)' -r '$OBJ.newMethod($$$ARGS)'

Rewrite imports:

ast-grep -l typescript -p 'import $WHAT from "old-pkg"' -r 'import $WHAT from "new-pkg"'

Workflow

Run without -r to see matches, with -r to preview the diff, then add --update-all to apply. For surgical per-site control, use ast-grep to find the locations and the Edit tool to apply each change.