ast-grep
Use ast-grep for structural code search and refactoring when editing code structure with ambiguity in text matching, handling "old_string not unique" problems, or performing formatting-independent pattern matching across function signatures, method calls, and class structures
When & Why to Use This Skill
ast-grep is a specialized structural code search and refactoring tool designed to handle complex code edits that traditional text-based tools struggle with. By leveraging Abstract Syntax Tree (AST) matching, it solves the common 'old_string not unique' problem, allowing for precise, formatting-independent code transformations across various programming languages.
Use Cases
- Refactoring function signatures and method calls where the same name appears in multiple contexts, ensuring only the correct structural matches are edited.
- Performing large-scale code migrations that require matching patterns across multiple lines, regardless of whitespace or indentation variations.
- Identifying and replacing complex nested structures, such as specific try-catch blocks or conditional logic patterns, that are difficult to capture with regular expressions.
- Standardizing codebases by finding and updating deprecated API usages that involve variable arguments and diverse structural implementations.
| name | ast-grep |
|---|---|
| description | Use ast-grep for structural code search and refactoring when editing code structure with ambiguity in text matching, handling "old_string not unique" problems, or performing formatting-independent pattern matching across function signatures, method calls, and class structures |
ast-grep: Structural Code Search and Editing
Use ast-grep to solve the "old_string not unique" problem by matching code structure instead of exact text. This enables refactoring across formatting variations and structural patterns.
When to Use ast-grep vs Text Tools
Use ast-grep when:
- Structural code changes - Refactoring function signatures, method calls, class structures
- Formatting-independent matching - Need to find code regardless of whitespace/line breaks
- Pattern variations - Matching similar structures with different variable names/arguments
- "old_string not unique" problem - Edit tool fails because text appears in multiple contexts
- Complex queries - Finding nested structures, specific AST patterns
Use text tools (Edit/Grep) when:
- Simple, unique string replacement - The exact text appears once or in consistent format
- Non-code files - Markdown, configs, data files
- Comment/documentation edits - Content that isn't code structure
- Very small changes - Single line, obvious context, no ambiguity
Key Decision Rule
If editing code structure and there's any ambiguity in text matching → use ast-grep.
ast-grep's primary value: Solves the "old_string not unique" problem by matching structure instead of exact text.
Detailed Reference
For comprehensive patterns, syntax, metavariables, common use cases, language-specific tips, and best practices, load ast-grep guide.
The reference includes:
- Pattern syntax and metavariables (
$VAR,$$$ARGS,$$STMT) - Recommended workflow (search, verify, apply, validate)
- Common use cases with examples (function calls, imports, method renames)
- Language-specific tips (JavaScript/TypeScript, Python, Go, Rust)
- Best practices and pitfalls to avoid
- Integration strategies with Edit tool