# rg 兼容性

`vendor/bin/rg` 是一个 ripgrep 风格的兼容包装器。它接受最常用的 ripgrep 标志，以与 ripgrep 相同的方式遍历文件树，并输出匹配结果。经验证的功能范围根据对上游 `rg` 二进制文件的探测运行结果复现，并收录于 [高级 / 功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix)。

该包装器是一个轻量的 CLI 转换器；实际搜索工作由与 `vendor/bin/greph` 相同的 `Greph\Text\TextSearcher` 引擎完成。

## 适用场景

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

- 你有现成的工具、代理或脚本已经在调用 `rg`。
- 你想要一个即插即用的替代方案，适用于无法安装 ripgrep 本身的环境（共享主机、加固容器、受限的 PaaS）。
- 你想在仅有 PHP 的基础设施上使用 ripgrep 式的操作体验。

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

- 你正在编写新代码，不需要 ripgrep CLI 形式。
- 你想使用包装器未提供的原生标志（例如 AST 模式）。

## 用法

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

直接调用会递归搜索 `.`：

```bash
./vendor/bin/rg -F "function"
```

`--files` 会列出候选文件，而不执行搜索：

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## JSON 输出

`--json` 会输出与 ripgrep 生成的相同事件结构的负载：

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

`stats` 对象中的计时值始终报告为零。

这是下游工具启用 ripgrep 结构化输出时所需的架构。如果你想要更简单的结构，请改用 `vendor/bin/greph --json`。

## 已验证的功能范围

下列标志已通过 `rg` 本身验证，并列于 [功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix) 中。对于每项探测，上游二进制文件和包装器都会产生等效输出。若某标志有短拼写和长拼写，探测会使用其中一种，而包装器会将两种拼写解析为相同选项。

### 搜索标志

- `-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`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### 遍历器标志

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### 输出标志

- `--json`

### 尚未经过探测的接受选项

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

- `-j N`、`--threads N`（工作进程数，参见 [并行工作进程](https://greph.inline0.dev/zh/docs/advanced/parallel)）
- `-q`、`--quiet`
- `--no-follow`

## 限制

Greph 的 `rg` 包装器涵盖了大多数工具和代理使用的搜索与遍历功能。它目前尚未提供以下 ripgrep 功能：

- 多行正则表达式（`-U`、`--multiline`）
- 文本模式下的替换（`-r`、`--replace`）（可改用 `vendor/bin/greph` AST 重写）
- 自定义类型定义（`--type-add`、`--type-clear`）
- 编码标志（`-E`、`--encoding`）
- `--pre` 过滤脚本
- `--sort`、`--sortr`

如果你遇到缺失的标志，请提交问题，并附上你针对上游 `rg` 运行的探测命令及预期输出。新功能会随其对应的预言机探测一起加入，因此经验证的功能范围只会扩大。

## 行为一致性

该包装器旨在实现行为一致，而非字节级一致。输出在行级别等效，但在外观细节上可能有所不同（颜色代码、按终端宽度截断）。[功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix) 使用的探测会检查语义等效性，而非字节级完全相同的差异。

对于解析输出的代理和工具，每项已验证探测中的解析相关字段（文件路径、行号、内容、匹配位置）都与上游 `rg` 字节级完全一致。