sg 兼容性

以 Markdown 格式查看在 GitHub 上编辑文档位置 d105217

vendor/bin/sg 是一个 ast-grep 风格的兼容包装器。它接受最常用的 ast-grep 标志，并复用 vendor/bin/greph -p 所用的同一 Greph\Ast\AstSearcher 引擎。经验证的功能范围根据对上游 sg 二进制文件的探测运行结果复现，并收录于高级 / 功能矩阵。

适用场景

在以下情况下使用该包装器：

你有现成的工具、代理或脚本已经在调用 sg。
你想要一个即插即用的替代方案，适用于无法安装 ast-grep 本身的环境。
你想在仅安装 Composer 的环境中获得 ast-grep 式的操作体验。

以下情况下使用原生 vendor/bin/greph -p：

你正在编写新代码，不需要 ast-grep CLI 形式。
你想使用与文本模式相同的一组标志（原生二进制文件统一了两种模式）。

用法

命令行

sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run 是规范的 ast-grep 动词。scan 和 rewrite 是仅供包装器使用的别名，用来映射常见用法。直接调用即可执行一次性搜索：

命令行

./vendor/bin/sg --pattern 'array($$$ITEMS)' src

模式

模式语法与原生 AST 搜索完全相同。完整参考请参见模式 / AST 搜索。

命令行

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src

重写

该包装器支持与原生重写相同的试运行 / 交互 / 写入工作流，标志名称使用 ast-grep：

命令行

# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

JSON 输出

--json 会输出 JSON 结构的 ast-grep。支持三种样式：

命令行

./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src

样式	结构
`--json`（默认 `pretty`）	单个美化打印的 JSON 数组
`--json=stream`	每行一个匹配项，以换行符分隔的 JSON
`--json=compact`	单个紧凑的 JSON 数组

已验证的功能范围

以下标志已针对上游 sg 二进制文件进行验证，详见功能矩阵。对于有两种写法的标志（-p 和 --pattern、--glob 和 --globs），探测会使用其中一种，而封装程序会将两种写法解析为相同的选项。

模式标志

--pattern PATTERN（顶层及 run 内部）
-p PATTERN（别名）
--rewrite TEMPLATE
-r TEMPLATE
--lang NAME、-l NAME

匹配标志

--files-with-matches
--json (pretty, stream, compact)
--update-all, -U

遍历器标志

--no-ignore hidden（组合形式）
--glob GLOB、--globs GLOB

工作进程标志

-j N, --threads N

尚未经过探测的接受选项

包装器也接受这些标志，但目前尚无功能矩阵探测涵盖它们：

单独使用 --no-ignore，或为其指定除 hidden 以外的值
--type NAME、--type-not NAME

仅供包装器使用的附加项

该包装器提供了几个 ast-grep 本身不具备的辅助功能：

scan 和 rewrite 是 run 的别名
--hidden 标志（ast-grep 会将其合并到 --no-ignore hidden 中）
--dry-run 重写预览别名
--interactive 重写确认流程

限制

Greph 的 sg 包装器涵盖了大多数工具和代理使用的结构化搜索与重写功能。它目前尚未提供以下 ast-grep 功能：

YAML 规则文件（--rule、--config）
除 PHP 之外的多语言扫描
非模式转换器（--debug-query、--inspect）
LSP 集成

如果你遇到缺失的标志，请提交问题，并附上你针对上游 sg 运行的探测命令及预期输出。

行为一致性

该包装器旨在实现行为一致，而非字节级一致。输出在语义上等效，但外观细节可能有所不同。功能矩阵使用的探测会检查解析相关字段（文件路径、行号、捕获的代码、捕获内容、JSON 结构）是否等效，而非比较字节流。