Ast Grep

ast-grep: Structural Code Search & Rewriting

AST-aware search, replace, and lint. Matches code structure, not text patterns.

Installation

Before first use, ensure ast-grep is installed:

bash /home/xly/AgentSkillsArxiv/ast-grep/scripts/ensure_installed.sh

When to Use ast-grep vs ripgrep

Rule of thumb: If you care about code structure (calls, assignments, blocks), use ast-grep. If you care about text content, use ripgrep.

Core Commands

Search — find matching code

ast-grep run -p 'PATTERN' -l LANG PATH

Examples:

ast-grep run -p 'print($$$)' -l python .
ast-grep run -p 'console.log($$$)' -l javascript src/
ast-grep run -p '$ERR.unwrap()' -l rust .

Rewrite — search and replace structurally

# Preview (dry run, no changes)
ast-grep run -p 'PATTERN' -r 'REPLACEMENT' -l LANG PATH

# Apply changes
ast-grep run -p 'PATTERN' -r 'REPLACEMENT' -l LANG --update-all PATH

Examples:

# Preview: print → logger.info
ast-grep run -p 'print($MSG)' -r 'logger.info($MSG)' -l python .

# Apply: require → import
ast-grep run -p 'const $N = require($P)' -r 'import $N from $P' -l javascript --update-all .

Scan — run YAML lint rules

# Single rule file
ast-grep scan -r rule.yml

# Project rules (reads sgconfig.yml)
ast-grep scan

# Apply auto-fixes from rules
ast-grep scan --update-all

Pattern Quick Reference

Same-name meta-variables must match identical content: $A == $A matches x == x but NOT x == y.

Language IDs

Use with -l flag:

Full list: ast-grep list-languages

Common Pitfalls

1. Use ast-grep, not sg — On Linux, sg is the setgroups command. Always use the full ast-grep binary name.

2. Never use -i (interactive mode) — Interactive mode requires terminal input and will hang. Always use --update-all (or -U) to apply changes non-interactively:

   # WRONG: hangs waiting for input
   ast-grep run -p 'old($$$)' -r 'new($$$)' -i -l python .
   
   # CORRECT: applies all changes
   ast-grep run -p 'old($$$)' -r 'new($$$)' --update-all -l python .
   

3. Patterns must be valid syntax — $FUNC( is not valid code and will fail. Patterns must parse as real code with meta-variables substituted.

4. Strictness for ambiguous patterns — If a simple pattern matches too broadly, use --strictness to control matching:

   ast-grep run -p '$EXPR' --strictness relaxed -l python .   # more matches
   ast-grep run -p '$EXPR' --strictness strict -l python .    # fewer matches
   

5. Path argument comes last — The search path must be the final argument:

   # CORRECT
   ast-grep run -p 'pattern' -l python ./src
   
   # WRONG
   ast-grep run ./src -p 'pattern' -l python
   

6. No output = no matches — ast-grep only prints matches. Empty output means the pattern didn't match anything (check the pattern and language flag).

When to Load References

Load pattern-examples.md when:

• You need language-specific pattern templates
• You're unsure how to express a structural pattern
• You want ready-made find/replace recipes for a specific language
• You need the full meta-variable reference with edge cases

Load yaml-rules-guide.md when:

• You need to write a YAML lint/scan rule
• You need relational rules (inside, has, follows, precedes)
• You need composite rules (all, any, not)
• You need constraints or transforms
• You need sgconfig.yml setup for project-wide scanning