rg 兼容性

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

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

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

适用场景

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

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

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

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

用法

命令行

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

直接调用会递归搜索 .：

命令行

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

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

命令行

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

JSON 输出

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

命令行

./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 本身验证，并列于功能矩阵中。对于每项探测，上游二进制文件和包装器都会产生等效输出。若某标志有短拼写和长拼写，探测会使用其中一种，而包装器会将两种拼写解析为相同选项。

搜索标志

-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（工作进程数，参见并行工作进程）
-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 运行的探测命令及预期输出。新功能会随其对应的预言机探测一起加入，因此经验证的功能范围只会扩大。

行为一致性

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

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