# CLI 参考手册

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 重写。

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

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

### 文本模式

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

```bash
# 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 搜索](https://greph.inline0.dev/zh/docs/modes/ast)。

```bash
./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` 组合使用即可激活。替换模板使用与搜索模式相同的元变量；捕获的节点会按名称插入。

```bash
# 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 搜索。

```bash
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...]
```

### 文本索引

```bash
# 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/`。

### 索引集

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

```bash
./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 事实索引

```bash
./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 缓存

```bash
./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 标志。经验证的功能范围发布在 [功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix) 中。

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

### 示例

```bash
./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 标志。经验证的功能范围发布在 [功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix) 中。

```bash
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 ... .`）执行一次性搜索。

### 示例

```bash
./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` 模式下发生解析错误） |