CLI 参考手册

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

Greph 附带四个可执行文件。它们共用同一引擎，区别在于各自提供的接口层。

二进制文件	用途
`greph`	原生文本搜索、AST 搜索和 AST 重写
`greph-index`	预热文本索引、AST 事实索引和缓存 AST 搜索
`rg`	兼容 ripgrep 风格的包装器
`sg`	兼容 ast-grep 风格的包装器

示例中的所有路径都使用 ./vendor/bin/<binary>，它适用于 Greph 0.2.3 或作为后续安装的依赖项。如果你在仓库克隆副本中工作，请替换为 ./bin/<binary>。

`greph`

原生文本搜索、AST 搜索和 AST 重写。

命令行

greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]

如果省略路径，则搜索当前目录。

文本模式

除非设置了 -F，否则默认模式会使用 PCRE2 正则表达式。

命令行

# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src

输出格式与 grep -rn 一致：

Text

src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...

AST 模式

由 -p 激活。模式使用普通 PHP 编写，并包含 $VAR 和 $$$VARIADIC 元变量。完整的模式语法请参阅模式 / AST 搜索。

命令行

./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

重写模式

将 -p 与 -r 组合使用即可激活。替换模板使用与搜索模式相同的元变量；捕获的节点会按名称插入。

命令行

# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

选项

标志	含义
`-F`	固定字符串搜索（不使用正则表达式）
`-i`	不区分大小写匹配
`-w`	全词匹配
`-v`	反转匹配
`-c`	按文件统计匹配数
`-l`	仅列出匹配的文件路径
`-L`	仅列出不匹配的文件路径
`-h`	在文本模式下隐藏文件名前缀
`-H`	在文本模式下始终打印文件名前缀
`-n`	显示行号（默认：开）
`-A N`	显示每个匹配项之后的 N 行
`-B N`	显示每个匹配项之前的 N 行
`-C N`	显示每个匹配项前后的 N 行上下文
`-m N`	每个文件匹配 N 次后停止
`-j N`	使用 N 个并行工作线程
`-p PATTERN`	AST 搜索模式
`-r TEMPLATE`	AST 重写模板（需要 `-p`）
`--glob GLOB`	仅包含路径与 GLOB 匹配的文件
`--type NAME`	包含一种文件类型别名（`php`、`js`、`md` 等）
`--type-not NAME`	排除一种文件类型别名
`--lang NAME`	AST 语言。默认值：`php`
`--json`	输出 JSON 格式
`--no-ignore`	忽略 `.gitignore` 和 `.grephignore` 规则
`--hidden`	包含隐藏文件
`--dry-run`	打印重写结果但不写入文件
`--interactive`	确认每个重写的文件
`--help`	显示内联用法说明

`greph-index`

预热文本索引、AST 事实索引和缓存 AST 搜索。

命令行

greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]

文本索引

命令行

# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin

文本索引是已预热的 trigram + 标识符倒排存储。默认位于已索引根目录下的 .greph-index/。

索引集

索引集可将重复的多索引工作流转化为一个命名清单：

命令行

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

默认清单文件为 .greph-index-set.json。每个条目都指向一个根目录、一种模式和一个生命周期配置。set build 和 set refresh 会对已启用的条目执行操作；set search 会对选定条目进行分发，并对重叠的匹配结果去重。

AST 事实索引

命令行

./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin

AST 事实索引会将节点级事实（调用、实例化、类、方法）提取到可查询的存储中。查找时会根据事实键执行 O(log n)，然后再针对源代码验证。默认存储于 .greph-ast-index/。

AST 缓存

命令行

./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

AST 缓存会将解析后的语法树存储在磁盘上，因此搜索时可以完全跳过解析器。默认存储于 .greph-ast-cache/。

选项

文本搜索选项与 greph 标志集一致（-F、-i、-w、-v、-c、-l、-L、-A、-B、-C、-m、--glob、--type、--type-not、--json、--no-ignore、--hidden）。

其他标志：

标志	含义
`--index-dir DIR`	使用非默认的预热索引目录。可重复指定，用于多索引搜索和统计。
`--lifecycle PROFILE`	构建策略：`static`、`manual-refresh`、`opportunistic-refresh`、`strict-stale-check`
`--auto-refresh-max-files N`	机会式刷新的文件数阈值
`--auto-refresh-max-bytes N`	机会式刷新的字节数阈值
`--manifest FILE`	加载索引集清单。默认值：`.greph-index-set.json`
`--mode MODE`	将集合操作限制为 `text`、`ast-index` 或 `ast-cache`
`--index NAME`	将集合操作限制为指定名称的清单条目。可重复指定。
`--show-index-origin`	为预热的多索引或集合输出添加匹配索引条目的名称前缀
`--trace-plan`	将预热规划器诊断信息输出到 `stderr`
`--dry-refresh`	在 `stats` 中，报告预热搜索将执行的操作，但不进行任何修改
`--lang NAME`	`ast-index` / `ast-cache` 搜索使用的 AST 语言。默认值：`php`
`-j N`、`--jobs N`	AST 扫描的工作进程数
`-l`、`--files-with-matches`	仅列出匹配的文件路径（AST 模式）
`--strict-parse`	遇到解析错误时失败，而非跳过
`--fallback MODE`	索引缺失时的行为：`fail`（默认）或 `scan`
`--help`	显示内联用法说明

`rg`

ripgrep 风格的兼容包装器。支持最常用的 ripgrep 标志。经验证的功能范围发布在功能矩阵中。

命令行

rg [options] pattern [path...]
rg --files [options] [path...]

示例

命令行

./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .

支持的选项

标志	含义
`-F`、`--fixed-strings`	固定字符串搜索
`-i`、`--ignore-case`	不区分大小写搜索
`-w`、`--word-regexp`	全词搜索
`-v`、`--invert-match`	反转匹配结果
`-c`、`--count`	统计匹配行数
`-l`、`--files-with-matches`	列出匹配的文件
`--files-without-match`	列出未匹配的文件
`-I`、`--no-filename`	隐藏文件名前缀
`-H`、`--with-filename`	始终显示文件名前缀
`-n`、`--line-number`	显示行号
`-A N`、`--after-context N`	显示每个匹配项之后的 N 行
`-B N`、`--before-context N`	显示每个匹配项之前的 N 行
`-C N`、`--context N`	显示每个匹配项前后的 N 行
`-m N`、`--max-count N`	每个文件匹配 N 次后停止
`-j N`、`--threads N`	使用 N 个并行工作进程
`-e P`、`--regexp P`	搜索模式
`-L`、`--follow`	跟踪符号链接
`--glob GLOB`	仅包含路径与 GLOB 匹配的文件
`--type NAME`	包含指定文件类型
`--type-not NAME`	排除指定文件类型
`--json`	输出 ripgrep 风格的 JSON 事件
`--no-ignore`	忽略 `.gitignore` 和 `.grephignore` 规则
`--hidden`	包含隐藏文件
`--files`	列出候选文件，而不执行搜索
`--help`	显示内联用法说明

`sg`

ast-grep 风格的兼容包装器。支持最常用的 ast-grep 标志。经验证的功能范围发布在功能矩阵中。

命令行

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 是仅供包装器使用的别名，用来映射常见用法。也可以直接调用（sg --pattern ... .）执行一次性搜索。

示例

命令行

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php

支持的选项

标志	含义
`-p`、`--pattern PATTERN`	AST 模式
`-r`、`--rewrite TEMPLATE`	重写模板
`-l`、`--lang NAME`	AST 语言。默认值：`php`
`-j`、`--threads N`	使用 N 个并行工作进程
`-i`、`--interactive`	确认每次重写
`-U`、`--update-all`	无需确认即可应用重写
`--files-with-matches`	仅打印包含匹配项的文件路径
`--json[=STYLE]`	输出 JSON 格式。STYLE = `pretty`、`stream` 或 `compact`
`--no-ignore [MODE]`	忽略仓库忽略规则
`--hidden`	包含隐藏文件
`--glob GLOB`、`--globs GLOB`	仅包含路径与 GLOB 匹配的文件
`--type NAME`	包含指定文件类型
`--type-not NAME`	排除指定文件类型
`--dry-run`	预览重写结果，不写入文件
`--help`	显示内联用法说明

退出代码

Greph 遵循 grep / ripgrep 约定：

代码	含义
`0`	找到至少一个匹配项（对于重写操作，则表示至少有一个文件被更改）
`1`	未找到匹配项
`2`	用法错误或运行时失败（参数错误、索引缺失、`--strict-parse` 模式下发生解析错误）