ast-grep

ast-grep

Structural code search and rewrite: a pattern is real code with meta-variables, matched against the syntax tree, so it ignores formatting and never matches inside strings or comments. Use it where rg gives false positives and where a refactor must touch every call site exactly once; plain text search stays with rg.

Commands

ast-grep run -p 'print($A)' -l python                                          # search; run is the default subcommand
ast-grep run -p 'console.log($$$ARGS)' -r 'logger.info($$$ARGS)' -l ts         # dry run: prints the diff, changes nothing
ast-grep run -p 'console.log($$$ARGS)' -r 'logger.info($$$ARGS)' -l ts --update-all   # apply after reviewing the dry run (-i to confirm per hunk)
ast-grep run -p 'func _() { os.Getenv($K) }' --selector call_expression -l go  # Go calls need a function context (see Gotchas)
ast-grep run -p 'print($A)' -l python --json=compact                           # structured output; --json=stream gives one object per line
ast-grep scan                                                                  # every rule in sgconfig.yml
ast-grep scan -r rules/no-print.yml --format github                            # one rule file; GitHub annotations in CI

Workflow

1. Write the pattern as code: $NAME matches one node, $$$NAME a sequence (arguments, statements), $_ a node without binding; always pass -l <lang> so the pattern parses in the right grammar, and use --debug-query=ast when a pattern that should match does not.
2. Search first: run without -r, read the matches with -C 2 for context, and tune --globs or --no-ignore when files are skipped.
3. Rewrite in two steps: add -r to see the diff, then --update-all (or -i for an interactive session); captured meta-variables are reused in the replacement.
4. Promote to a rule: for a lint or a repeated refactor, ast-grep new project scaffolds sgconfig.yml and rules/; a rule file has id, language, rule (pattern, kind, inside, has, not), optional fix, severity, and message; ast-grep test runs its valid and invalid cases.
5. Wire into the gate: run ast-grep scan inside check:lint (see mise) so hooks and CI apply the same rules.