ast-grep

ast-grep (sg)

ast-grep is a fast and polyglot tool for code searching, linting, and rewriting based on Abstract Syntax Trees (AST). It excels at structural search and replace where regex fails.

When to use

• Structural Search: Finding code based on structure (e.g., "all function calls to foo with 2 arguments") regardless of whitespace.
• Refactoring: Renaming variables, changing function signatures, or transforming code patterns safely.
• Linting: Creating custom rules to enforce code style or best practices.
• Code Analysis: Extracting information from codebases.

Quick Start

CLI Basics

# Search (pattern must be in single quotes)
ast-grep -p '$A + $B' --lang ts

Rewrite (dry run)

ast-grep -p '$A != null' --rewrite '$A' --lang ts

Interactive Rewrite

ast-grep -p 'var $A = $B' --rewrite 'const $A = $B' --interactive

### Pattern Syntax
- **Meta-variables**: `$VAR` matches any single node.
- **Multi-meta-variables**: `$$$ARGS` matches zero or more nodes (list of items).
- **Wildcard**: `$_` matches any node (non-capturing).
- **Anonymous**: `$$` matches any list of nodes (non-capturing).

See [Pattern Syntax](references/pattern-syntax.md) for details.

## Core Concepts

Understanding **Named vs Unnamed nodes** and **Matching Strictness** is crucial for precise patterns.

- **Named Nodes**: `identifier`, `function_definition` (matched by `$VAR`).
- **Unnamed Nodes**: `(`, `)`, `;` (skipped by default in `smart` mode).
- **Strictness**: Control matching precision (`smart`, `cst`, `ast`, `relaxed`, `signature`).

See [Core Concepts](references/core-concepts.md) for details.

## Rule Configuration (YAML)

For complex tasks, use YAML configuration files.

```yaml
id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$ARGS)
  inside:
    kind: function_declaration
    stopBy: end
fix: '' # Remove the log

See Rule Configuration for details.

Advanced Rewriting

ast-grep supports complex transformations (regex replace, case conversion) and rewriters for sub-node transformation.

See Rewriting & Transformations for details.

Project Setup & Testing

For larger projects, organize rules and tests using sgconfig.yml.

• Scaffold: ast-grep new project
• Config: sgconfig.yml defines rule and test directories.
• Testing: Define valid and invalid cases to ensure rule accuracy.

See Project Setup & Testing for details.

Utility Rules

Reuse logic with local or global utility rules. Enables recursive matching.

utils:
  is-literal:
    any: [{kind: string}, {kind: number}]
rule:
  matches: is-literal

See Utility Rules for details.

Configuration Reference

Full reference for YAML fields (id, severity, files, ignores) and supported languages.

See Configuration Reference for details.

CLI Reference

Common commands: scan, run, new, test, lsp.

See CLI Reference for details.