Back to Details

ast-grep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ast-grep

ast-grep

Structural code search and rewriting using AST matching.
基于AST匹配的结构化代码搜索与重写工具。

Pattern Syntax

模式语法

PatternDescription
$VAR
Match a single AST node and capture it as 
VAR
$$$VAR
Match zero or more AST nodes (spread) and capture as 
VAR
$_
Anonymous placeholder (matches any single node, no capture)
$$$_
Anonymous spread placeholder (matches any number of nodes)
Shell quoting: Escape 
$
as 
\$VAR
or wrap in single quotes.
模式描述
$VAR
匹配单个AST节点并将其捕获为
VAR
$$$VAR
匹配零个或多个AST节点（展开）并捕获为
VAR
$_
匿名占位符（匹配任意单个节点，不捕获）
$$$_
匿名展开占位符（匹配任意数量的节点）
Shell 转义： 将
$
转义为
\$VAR
或用单引号包裹。

Supported Languages

支持的语言

javascript, typescript, tsx, html, css, python, go, rust, java, c, cpp, csharp, ruby, php, yaml
javascript, typescript, tsx, html, css, python, go, rust, java, c, cpp, csharp, ruby, php, yaml

Commands

命令

CommandDescription
ast-grep run
One-time search or rewrite (default)
ast-grep scan
Scan and rewrite by configuration
ast-grep test
Test ast-grep rules
ast-grep new
Create new project or rules
命令描述
ast-grep run
一次性搜索或重写（默认命令）
ast-grep scan
按配置执行扫描与重写
ast-grep test
测试ast-grep规则
ast-grep new
创建新项目或规则

Search Examples

搜索示例

bash
undefined
bash
undefined

Find console.log calls

查找console.log调用

ast-grep run --pattern 'console.log($$$ARGS)' --lang javascript .
ast-grep run --pattern 'console.log($$$ARGS)' --lang javascript .

Find React useState hooks

查找React useState钩子

ast-grep run --pattern 'const [$STATE, $SETTER] = useState($INIT)' --lang tsx .
ast-grep run --pattern 'const [$STATE, $SETTER] = useState($INIT)' --lang tsx .

Find async functions

查找异步函数

ast-grep run --pattern 'async function $NAME($$$ARGS) { $$$BODY }' --lang typescript .
ast-grep run --pattern 'async function $NAME($$$ARGS) { $$$BODY }' --lang typescript .

Find Express route handlers

查找Express路由处理器

ast-grep run --pattern 'app.$METHOD($PATH, ($$$ARGS) => { $$$BODY })' --lang javascript .
ast-grep run --pattern 'app.$METHOD($PATH, ($$$ARGS) => { $$$BODY })' --lang javascript .

Find Python function definitions

查找Python函数定义

ast-grep run --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python .
ast-grep run --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python .

Find Go error handling

查找Go错误处理

ast-grep run --pattern 'if $ERR != nil { $$$BODY }' --lang go .
ast-grep run --pattern 'if $ERR != nil { $$$BODY }' --lang go .

Find all function calls

查找所有函数调用

ast-grep run --pattern '$FUNCTION($$$_)' --lang typescript .
ast-grep run --pattern '$FUNCTION($$$_)' --lang typescript .

Find specific function calls

查找特定函数调用

ast-grep run --pattern 'fetch($$$_)' --lang typescript .
ast-grep run --pattern 'fetch($$$_)' --lang typescript .

Find try-catch blocks

查找try-catch块

ast-grep run --pattern 'try { $$$BODY } catch ($$$_)' --lang typescript .
ast-grep run --pattern 'try { $$$BODY } catch ($$$_)' --lang typescript .

Find Promise error handling

查找Promise错误处理

ast-grep run --pattern '.catch($$$_)' --lang typescript .
undefined
ast-grep run --pattern '.catch($$$_)' --lang typescript .
undefined

Search and Replace (Dry Run)

搜索与替换（试运行）

bash
undefined
bash
undefined

Replace == with ===

将 == 替换为 ===

ast-grep run --pattern '$A == $B' --rewrite '$A === $B' --lang javascript .
ast-grep run --pattern '$A == $B' --rewrite '$A === $B' --lang javascript .

Replace != with !==

将 != 替换为 !==

ast-grep run --pattern '$A != $B' --rewrite '$A !== $B' --lang typescript .
ast-grep run --pattern '$A != $B' --rewrite '$A !== $B' --lang typescript .

Convert function to arrow function

将普通函数转换为箭头函数

ast-grep run --pattern 'function $NAME($$$ARGS) { $$$BODY }'
--rewrite 'const $NAME = ($$$ARGS) => { $$$BODY }' --lang javascript .
ast-grep run --pattern 'function $NAME($$$ARGS) { $$$BODY }'
--rewrite 'const $NAME = ($$$ARGS) => { $$$BODY }' --lang javascript .

Replace var with let

将var替换为let

ast-grep run --pattern 'var $NAME = $VALUE' --rewrite 'let $NAME = $VALUE' --lang javascript .
ast-grep run --pattern 'var $NAME = $VALUE' --rewrite 'let $NAME = $VALUE' --lang javascript .

Add optional chaining

添加可选链操作符

ast-grep run --pattern '$OBJ && $OBJ.$PROP' --rewrite '$OBJ?.$PROP' --lang javascript .
ast-grep run --pattern '$OBJ && $OBJ.$PROP' --rewrite '$OBJ?.$PROP' --lang javascript .

Replace console.log with logger

将console.log替换为logger

ast-grep run --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang typescript .
undefined
ast-grep run --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang typescript .
undefined

Apply Changes

应用修改

bash
undefined
bash
undefined

Apply changes with --update-all

使用--update-all应用修改

ast-grep run --pattern '$A == $B' --rewrite '$A === $B' --lang javascript --update-all .
undefined
ast-grep run --pattern '$A == $B' --rewrite '$A === $B' --lang javascript --update-all .
undefined

Configuration-Based Rules

基于配置的规则

yaml
undefined
yaml
undefined

rules/my-rules.yaml

rules/my-rules.yaml

patterns:
  • pattern: "console.log($$$)" rewrite: "logger.info($$$)" languages: [javascript, typescript] message: "Use logger instead of console.log"

```bash
patterns:
  • pattern: "console.log($$$)" rewrite: "logger.info($$$)" languages: [javascript, typescript] message: "Use logger instead of console.log"

```bash

Run custom rules

运行自定义规则

ast-grep scan --project my-rules
ast-grep scan --project my-rules

Dry-run preview

试运行预览

ast-grep scan --project my-rules --dry-run
undefined
ast-grep scan --project my-rules --dry-run
undefined

Tips

小贴士

  • Use 
    --dry-run
    to preview changes before applying
  • Use 
    --update-all
    to apply to all matching files
  • Use single quotes for patterns with 
    $
    variables
  • Combine with 
    --verbose
    for detailed matching info
  • 使用
    --dry-run
    在应用修改前预览变更
  • 使用
    --update-all
    将修改应用到所有匹配的文件
  • 对于包含
    $
    变量的模式，使用单引号包裹
  • 结合
    --verbose
    获取详细的匹配信息