ast-grep
ast-grep (sg) is a CLI tool that searches, lints, and rewrites code using Abstract Syntax Trees instead of text patterns. It uses tree-sitter parsers, supports 20+ languages (including Markdown), and runs in seconds across large codebases.
Write a code snippet as a pattern, and ast-grep matches it structurally against the AST -- ignoring whitespace, comments, and formatting differences.
Patterns are one atomic building block. When a pattern alone can't express what you need (disambiguation, naming constraints, relational checks, transforms), graduate to a full YAML rule. Patterns handle ~60% of searches; YAML rules handle the rest.
- Write valid parseable code as patterns. Tree-sitter must parse the pattern. Invalid syntax silently produces zero matches with no error, so always verify a new pattern returns results before adding constraints.
- Metavariable names use UPPERCASE:
$NAME, $$$ARGS, $_. Lowercase $name is treated as literal code, not a capture.
$X captures exactly one AST node. Use $$$X for zero-or-more. The mismatch is the most common cause of "pattern doesn't match" -- a single-arg pattern won't match a two-arg call.
- Same name = same content:
$A == $A matches x == x but rejects x == y. This is structural equality, not variable binding -- use it intentionally.
- Every rule needs at least one positive atomic rule (
pattern, kind, or regex). A not rule alone is invalid because ast-grep needs something to anchor the search.
regex matches the full node text. Partial matches fail. /foo/ does not match fooBar -- use ^foo if you want prefix matching.
fix replaces the single matched node. It cannot patch multiple locations. Use expandStart/expandEnd to consume surrounding tokens (trailing commas, semicolons).
- Unmatched metavariables become empty strings in
fix. This is intentional for optional captures, but verify your pattern actually captures what you expect before relying on it in a rewrite.
- Use
stopBy: end on relational rules (inside, has, follows, precedes) unless you specifically want neighbor-only matching. The default stopBy: neighbor stops at the first non-matching node and misses deeper results -- this is the second most common cause of "rule doesn't match."
- Shell escaping for
--inline-rules: the shell interprets $ as a variable. Wrap YAML in single quotes or escape each metavariable with \$VAR.
- Write example code before writing rules. Small mistakes in rule composition cascade into completely invalid output. Write a concrete code snippet that should match, verify the AST structure with
--debug-query=cst, then build the rule against that snippet.
- Verify every rule before searching the codebase. Test against the example snippet with
sg scan --inline-rules '...' --stdin or sg scan -r rule.yml test.file. This catches composition errors before they waste a full codebase scan.
Rules are compositions of atomic parts. A single error in one part cascades, so verify at each step.
- Understand the intent -- what code pattern are you looking for? What should match and what should not?
- Write example code -- a concrete snippet that should match the rule, and one that should not. These are the test fixtures.
- Explore the AST --
sg run --pattern 'TARGET_CODE' --debug-query=cst -l LANG to see node kinds and structure of the example code.
- Write the rule -- start with the simplest possible pattern. Add constraints, relational rules, and transforms incrementally. Test after each addition.
- Test the rule against the example --
echo "example code" | sg scan --inline-rules '...' --stdin or sg scan -r rule.yml example.file. Confirm it matches the positive case and rejects the negative case.
- Search the codebase --
sg scan for the full project. Review a sample of results to confirm precision.
- Formalize -- if reusable, add
id, message, severity, fix. Write test YAML with sg new test, generate snapshots with sg test -U.
When a rule doesn't work, go back to step 3. The AST structure frequently contradicts how source code looks visually -- verify with --debug-query=cst rather than assuming.
Before reporting a rule as done, run it against both the positive and negative example. Confirm it matches what it should and rejects what it shouldn't.
sg run -p 'fetch($$$ARGS)' -l javascript
rule:
pattern: $HOOK($$$ARGS)
constraints:
HOOK: { regex: '^use' }
sg run -p 'oldFunction($$$ARGS)' -r 'newFunction($$$ARGS)' -l typescript -U
Use context + selector when the target fragment needs surrounding syntax to parse:
rule:
pattern:
context: 'class A { a = 123 }'
selector: field_definition
id: no-await-in-loop
language: TypeScript
rule:
pattern: await $EXPR
inside:
any:
- kind: for_statement
- kind: for_in_statement
- kind: while_statement
stopBy: end
References
- Pattern Syntax -- Metavariables, matching rules, strictness modes, pattern object for disambiguation
- Rule Reference -- Atomic, relational, and composite rules, matching order, ESQuery selectors
- YAML Configuration -- Full rule file schema: fix, transform, constraints, utils, rewriters
- CLI Reference -- All commands, flags, output formats, CLI vs Playground differences
- Recipes -- Search, lint, rewrite, transform, debugging, and advanced technique examples
1---2name: ast-grep3description: "AST-based code search, lint, and rewrite using ast-grep. Use when finding code patterns structurally (not textually), writing lint rules, building codemods, or migrating API usage across a codebase. Prefer over regex grep when the match target is a syntactic construct (function call, import, class field, assignment)."4metadata:5 source: https://skillmd.com/skills/damusix/ast-grep6---78# ast-grep910ast-grep (`sg`) is a CLI tool that searches, lints, and rewrites code using Abstract Syntax Trees instead of text patterns. It uses tree-sitter parsers, supports 20+ languages (including Markdown), and runs in seconds across large codebases.1112Write a code snippet as a pattern, and ast-grep matches it structurally against the AST -- ignoring whitespace, comments, and formatting differences.1314Patterns are one atomic building block. When a pattern alone can't express what you need (disambiguation, naming constraints, relational checks, transforms), graduate to a full YAML rule. Patterns handle ~60% of searches; YAML rules handle the rest.1516<constraints>17181. **Write valid parseable code as patterns.** Tree-sitter must parse the pattern. Invalid syntax silently produces zero matches with no error, so always verify a new pattern returns results before adding constraints.192. **Metavariable names use UPPERCASE:** `$NAME`, `$$$ARGS`, `$_`. Lowercase `$name` is treated as literal code, not a capture.203. **`$X` captures exactly one AST node.** Use `$$$X` for zero-or-more. The mismatch is the most common cause of "pattern doesn't match" -- a single-arg pattern won't match a two-arg call.214. **Same name = same content:** `$A == $A` matches `x == x` but rejects `x == y`. This is structural equality, not variable binding -- use it intentionally.225. **Every rule needs at least one positive atomic rule** (`pattern`, `kind`, or `regex`). A `not` rule alone is invalid because ast-grep needs something to anchor the search.236. **`regex` matches the full node text.** Partial matches fail. `/foo/` does not match `fooBar` -- use `^foo` if you want prefix matching.247. **`fix` replaces the single matched node.** It cannot patch multiple locations. Use `expandStart`/`expandEnd` to consume surrounding tokens (trailing commas, semicolons).258. **Unmatched metavariables become empty strings in `fix`.** This is intentional for optional captures, but verify your pattern actually captures what you expect before relying on it in a rewrite.269. **Use `stopBy: end` on relational rules** (`inside`, `has`, `follows`, `precedes`) unless you specifically want neighbor-only matching. The default `stopBy: neighbor` stops at the first non-matching node and misses deeper results -- this is the second most common cause of "rule doesn't match."2710. **Shell escaping for `--inline-rules`:** the shell interprets `$` as a variable. Wrap YAML in single quotes or escape each metavariable with `\$VAR`.2811. **Write example code before writing rules.** Small mistakes in rule composition cascade into completely invalid output. Write a concrete code snippet that should match, verify the AST structure with `--debug-query=cst`, then build the rule against that snippet.2912. **Verify every rule before searching the codebase.** Test against the example snippet with `sg scan --inline-rules '...' --stdin` or `sg scan -r rule.yml test.file`. This catches composition errors before they waste a full codebase scan.3031</constraints>3233<workflow>3435Rules are compositions of atomic parts. A single error in one part cascades, so verify at each step.36371. **Understand the intent** -- what code pattern are you looking for? What should match and what should not?382. **Write example code** -- a concrete snippet that should match the rule, and one that should not. These are the test fixtures.393. **Explore the AST** -- `sg run --pattern 'TARGET_CODE' --debug-query=cst -l LANG` to see node kinds and structure of the example code.404. **Write the rule** -- start with the simplest possible pattern. Add constraints, relational rules, and transforms incrementally. Test after each addition.415. **Test the rule against the example** -- `echo "example code" | sg scan --inline-rules '...' --stdin` or `sg scan -r rule.yml example.file`. Confirm it matches the positive case and rejects the negative case.426. **Search the codebase** -- `sg scan` for the full project. Review a sample of results to confirm precision.437. **Formalize** -- if reusable, add `id`, `message`, `severity`, `fix`. Write test YAML with `sg new test`, generate snapshots with `sg test -U`.4445When a rule doesn't work, go back to step 3. The AST structure frequently contradicts how source code looks visually -- verify with `--debug-query=cst` rather than assuming.4647Before reporting a rule as done, run it against both the positive and negative example. Confirm it matches what it should and rejects what it shouldn't.4849</workflow>5051<examples>5253<example description="Search: find all calls to a function">5455 sg run -p 'fetch($$$ARGS)' -l javascript5657</example>5859<example description="Search: find a pattern with naming constraints">6061```yaml62rule:63 pattern: $HOOK($$$ARGS)64constraints:65 HOOK: { regex: '^use' }66```6768</example>6970<example description="Rewrite: rename across the codebase">7172 sg run -p 'oldFunction($$$ARGS)' -r 'newFunction($$$ARGS)' -l typescript -U7374</example>7576<example description="Rule: match sub-expressions that aren't standalone-valid code">7778Use `context` + `selector` when the target fragment needs surrounding syntax to parse:7980```yaml81rule:82 pattern:83 context: 'class A { a = 123 }'84 selector: field_definition85```8687</example>8889<example description="Rule: find await inside loops with relational rules">9091```yaml92id: no-await-in-loop93language: TypeScript94rule:95 pattern: await $EXPR96 inside:97 any:98 - kind: for_statement99 - kind: for_in_statement100 - kind: while_statement101 stopBy: end102```103104</example>105106</examples>107108## References109110- [Pattern Syntax](references/pattern-syntax.md) -- Metavariables, matching rules, strictness modes, pattern object for disambiguation111- [Rule Reference](references/rule-reference.md) -- Atomic, relational, and composite rules, matching order, ESQuery selectors112- [YAML Configuration](references/yaml-config.md) -- Full rule file schema: fix, transform, constraints, utils, rewriters113- [CLI Reference](references/cli.md) -- All commands, flags, output formats, CLI vs Playground differences114- [Recipes](references/recipes.md) -- Search, lint, rewrite, transform, debugging, and advanced technique examples