ripgrep

ripgrep

文本搜索优先使用 rg 而不是 grep；如果实际任务是查找路径，则优先使用 rg --files 而不是 find | grep。

已于 2026 年 4 月 10 日在本地使用 ripgrep 15.1.0 验证。此技能与具体仓库无关，但示例假定使用类 Unix shell，且 PATH 中有 rg 二进制文件。

决策树

你需要哪种搜索？

• 在文件内容中搜索文本、符号、正则表达式或字面字符串

  • 从 rg 开始
  • 阅读 references/commands.md

• 查找文件名或路径，不读取文件内容

  • 从 rg --files [path] 开始
  • 如有需要，再用第二个 rg 过滤该列表
  • 阅读 references/patterns.md

• 仅搜索特定语言、glob、隐藏文件、忽略的文件、压缩数据或多行文本块

  • 阅读 references/commands.md
  • 如果结果似乎有误或缺失，请阅读 references/gotchas.md

• 使用配置文件、别名或自定义文件类型，让 ripgrep 的行为可重复

  • 阅读 references/configuration.md

• 将结果提供给自动化脚本、编辑器或其他工具

  • 根据情况优先使用 --json、-0、-l、--count-matches 或 --sort path
  • 阅读 references/patterns.md

• 用户需要读取完整文件、查询结构化 JSON 或获取文件系统元数据

  • 不要强行让 rg 承担它不擅长的工作
  • 直接读取文件，或使用 jq、find 或 fd

默认操作规则

1. 文本搜索首先使用 rg。仅当 rg 不可用，或确实需要 POSIX grep 的精确行为时，才改用 grep。
2. 对用户提供的字面字符串使用 -F，除非用户明确要求使用正则表达式语义。
3. 尽早通过明确指定路径和 -t 或 -g 缩小搜索范围，而不是先搜索整个目录树再清理结果。
4. 使用 rg --files 查找路径，然后将结果通过管道传给另一个 rg 过滤文件名，而不是组合使用 find ... | grep ...。
5. 根据已知范围选择忽略规则：常规遍历、使用 --hidden 搜索隐藏条目、使用 -u 或 --no-ignore 搜索被忽略的条目，或在需要时同时使用。直接搜索已知文件；不要为了找到它而运行失败的中间搜索。仅在确实需要搜索二进制文件时才使用 -uuu 等二进制覆盖选项。
6. 结果缺失且需要了解 ripgrep 跳过了哪些内容时，使用 --debug。
7. 供机器处理时使用 --json 或 -n --color never --no-heading。当输出的确定性比最高速度更重要时，优先使用 --sort path。

快速参考

需求	命令	说明
字面文本搜索	rg -n -F 'needle' path/	对包含标点的用户输入字符串，这是最佳默认选项
正则表达式搜索	rg -n 'foo\\s+bar' path/	使用单引号，避免 shell 干扰
仅列出文件名	rg --files path/	默认遵循忽略文件
过滤文件名	`rg --files	rg '(^
匹配特定语言	rg -n -t py 'pattern' src/	-t 包含，-T 排除
匹配特定 glob	rg -n -g '*.tsx' 'pattern' src/	后面的 glob 会覆盖前面的 glob
搜索隐藏或被忽略的内容	rg --hidden 'pattern' path/、rg -u 'pattern' path/ 或 rg --hidden --no-ignore 'pattern' path/	直接选择所需的过滤覆盖选项；也可以显式搜索已知文件路径
列出包含匹配项的文件	rg -l 'pattern' path/	打开文件前先使用
统计单个匹配项	rg --count-matches 'pattern' path/	-c 统计匹配行，而不是匹配项
机器可读输出	rg --json 'pattern' path/	最适合工具和脚本
环视或反向引用	rg -P '...' path/	构建版本必须支持 PCRE2
多行文本块	rg -U '(?s)start.*end' file	多行搜索速度较慢且更耗内存
诊断被跳过的文件	rg --debug 'pattern' path/	显示忽略和跳过原因

阅读指南

任务	阅读
正确的命令、标志或输出模式	references/commands.md
配置文件、别名、自定义类型和环境设置	references/configuration.md
Agent 搜索工作流、文件名发现、Shell 管道和确定性输出	references/patterns.md
结果缺失、引号问题、多行意外行为、JSON 限制及其他陷阱	references/gotchas.md

已验证的行为

1. rg --files 默认遵循忽略规则，并在本地探测中排除了被忽略的 logs/app.log。
2. .rgignore 的优先级高于 .ignore，而 --no-ignore 可重新访问同一个被忽略的文件。
3. --hidden 会显示隐藏内容，但不会关闭忽略处理。
4. -g 标志的顺序会按上游文档所述精确改变结果集：后面的 glob 会覆盖前面的 glob。
5. RIPGREP_CONFIG_PATH 成功从配置文件加载了 --smart-case 和自定义 web 类型。
6. --json 以 JSON Lines 格式输出 begin、match、end 和 summary 消息。
7. -U '(?s)...' 可跨行匹配；由于本机的构建包含 PCRE2，-P 前后查找也能正常工作。

注意事项

1. rg 并非 POSIX grep 的逐字节替代品；在重视速度、递归、忽略处理或 Unicode 感知正则表达式时，它是默认搜索工具。
2. 结果缺失通常是忽略规则、隐藏文件、glob 顺序或引号的问题，而非 ripgrep 的 Bug。已知原因时直接选择相应的修正方法；跳过原因不明确时使用 --debug。
3. --replace 只会更改打印出的内容，不会编辑文件。
4. --json 用于搜索结果，不适用于所有输出模式。它不能与 --files、-l 或 -c 组合使用。
5. -P 和 -U 功能强大，但开销高于默认引擎和常规的逐行搜索。请谨慎使用。

辅助脚本

• scripts/probe_ripgrep.py 会构建临时语料，并验证 rg 的实际行为，例如忽略优先级、JSON 输出、多行匹配和 PCRE2 支持情况。
• scripts/validate.py 会检查结构、frontmatter、引用、必需文件和 Python 语法。
• scripts/test_skill.py 会运行验证、检查评估覆盖范围、验证交叉引用，并执行 ripgrep 探测套件。

指南不再适用时

如果示例与已安装的构建版本不符，请检查 rg --version、rg --help、当前配置和相关官方文档。使用一小份不含敏感信息的语料，区分版本变更与忽略规则或引号错误。提供证据和可复现示例，提出对规范技能指南的修正，并明确指出未经支持的行为。不要悄悄修改已安装的副本，也不要为了证明某个观点而扩大搜索范围到包含机密的路径。