ast-grep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

ast-grep是一款基于抽象语法树（AST）的快速多语言工具，用于代码搜索、代码检查与代码重写。在正则表达式无法胜任的结构化搜索和替换场景中，它表现出色。

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.

结构化搜索：基于代码结构查找内容（例如“所有传入2个参数的
```
foo
```
函数调用”），不受空格格式影响。
代码重构：安全地重命名变量、修改函数签名或转换代码模式。
代码检查：创建自定义规则以强制执行代码风格或最佳实践。
代码分析：从代码库中提取信息。

Quick Start

快速开始

CLI Basics

CLI基础操作

bash

undefined

bash

undefined

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

undefined

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

undefined

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 for details.

元变量：
```
$VAR
```
匹配任意单个节点。
多元变量：
```
$$$ARGS
```
匹配零个或多个节点（节点列表）。
通配符：
```
$_
```
匹配任意节点（非捕获型）。
匿名变量：
```
$$
```
匹配任意节点列表（非捕获型）。

详情请查看模式语法。

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 for details.

理解命名节点与未命名节点以及匹配严格度是编写精准模式的关键。

命名节点：
```
identifier
```
、
```
function_definition
```
（可通过
```
$VAR
```
匹配）。
未命名节点：
```
(
```
、
```
)
```
、
```
;
```
（默认在
```
smart
```
模式下会被忽略）。
严格度：控制匹配精度（可选值：
```
smart
```
、
```
cst
```
、
```
ast
```
、
```
relaxed
```
、
```
signature
```
）。

详情请查看核心概念。

Rule Configuration (YAML)

规则配置（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.

对于复杂任务，可使用YAML配置文件。

yaml

id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$ARGS)
  inside:
    kind: function_declaration
    stopBy: end
fix: '' # 移除日志语句

详情请查看规则配置。

Advanced Rewriting

高级重写

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

See Rewriting & Transformations for details.

ast-grep支持复杂的转换操作（正则替换、大小写转换）以及用于子节点转换的重写器。

详情请查看重写与转换。

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.

针对大型项目，可使用

sgconfig.yml

组织规则与测试用例。

初始化项目：
```
ast-grep new project
```
配置文件：
```
sgconfig.yml
```
定义规则与测试目录。
测试：定义
```
valid
```
和
```
invalid
```
用例以确保规则的准确性。

详情请查看项目设置与测试。

Utility Rules

工具规则

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

yaml

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

See Utility Rules for details.

可复用本地或全局的工具规则，支持递归匹配。

yaml

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

详情请查看工具规则。

Configuration Reference

配置参考

Full reference for YAML fields (

id

severity

files

ignores

) and supported languages.

See Configuration Reference for details.

包含YAML字段（

id

、

severity

、

files

、

ignores

）及支持语言的完整参考。

详情请查看配置参考。

CLI Reference

CLI参考

Common commands:

scan

run

new

test

lsp

See CLI Reference for details.

常用命令：

scan

、

run

、

new

、

test

、

lsp

。

详情请查看CLI参考。