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