输出格式化

相关源文件

• crates/printer/src/counter.rs
• crates/printer/src/hyperlink.rs
• crates/printer/src/hyperlink_aliases.rs
• crates/printer/src/json.rs
• crates/printer/src/lib.rs
• crates/printer/src/standard.rs
• crates/printer/src/summary.rs
• crates/printer/src/util.rs
• tests/feature.rs

本页介绍 ripgrep 的输出格式系统，该系统决定了搜索结果如何呈现给用户。该系统处理从基本结果显示到匹配着色、文件路径格式化、JSON 输出、上下文行和摘要统计信息的一切内容。

有关 ripgrep 如何搜索模式的信息，请参阅 核心搜索引擎。有关 ripgrep 如何遍历和过滤文件的详细信息，请参阅 文件遍历和过滤。

打印机类型

Ripgrep 提供三种主要的打印机实现，每种都服务于不同的用例。

标准打印机

标准打印机是默认选项，可生成人类可读的类 grep 输出。它高度可配置，支持：

• 文件路径显示（作为标题或前缀）
• 行号和列号
• 带自定义分隔符的上下文行
• 匹配和其他元素的彩色输出
• 终端模拟器的超链接支持
• 匹配替换
• 行宽限制和截断
• 各种输出字段分隔符

JSON 打印机

JSON 打印机以结构化的 JSON Lines 格式输出结果，其中每一行都是一个有效的 JSON 对象。此格式专为程序化处理搜索结果而设计。它发出不同的消息类型：

• begin - 指示文件搜索已开始
• match - 包含匹配的详细信息
• context - 包含上下文行的详细信息
• end - 指示文件搜索已完成，包括统计信息

摘要打印机

摘要打印机提供汇总信息而不是单个匹配。它支持几种模式：

• Count - 显示每个文件的匹配行数
• CountMatches - 显示每个文件的总匹配数
• PathWithMatch - 仅显示带有匹配的文件路径
• PathWithoutMatch - 仅显示不带匹配的文件路径
• Quiet - 不显示输出，但在找到第一个匹配后停止

来源：crates/printer/src/lib.rs58-73 crates/printer/src/standard.rs478-497 crates/printer/src/json.rs103-462 crates/printer/src/summary.rs61-91

输出格式架构

打印机组件架构

来源：crates/printer/src/standard.rs102-110 crates/printer/src/json.rs49-53 crates/printer/src/summary.rs139-143

搜索结果处理流程

来源：crates/printer/src/standard.rs528-586 crates/printer/src/standard.rs654-666

标准打印机配置

标准打印机通过 StandardBuilder 提供广泛的配置选项。下表显示了最重要的选项：

选项	描述	默认
heading	将文件路径显示为标题	false
path	显示文件路径	true
only_matching	仅显示匹配的文本	false
per_match	每行打印一个匹配项	false
per_match_one_line	对于多行匹配，仅打印第一行	false
column	显示列号	false
byte_offset	显示字节偏移量	false
trim_ascii	修剪前导空格	false
max_columns	限制行宽	无
max_columns_preview	显示截断行的预览	false
max_matches	限制匹配数	无
color_specs	配置颜色	默认颜色
hyperlink	配置超链接	无超链接
stats	收集统计信息	false

来源：crates/printer/src/standard.rs36-87 crates/printer/src/standard.rs221-337

输出行结构

来源：crates/printer/src/standard.rs79-84 crates/printer/src/standard.rs420-441

字段分隔符和行格式

标准打印机使用多个可自定义的分隔符：

分隔符	默认	描述
separator_field_match	:	匹配行中的字段之间
separator_field_context	-	上下文行中的字段之间
separator_context	--	非连续上下文块之间
separator_search	无	不同搜索结果之间
separator_path	无	覆盖系统路径分隔符
path_terminator	无	路径后的字符（使用 -0 时为 null 字节）

这些分隔符可以通过命令行标志自定义，例如 --field-match-separator 和 --field-context-separator。

来源：crates/printer/src/standard.rs79-84 tests/feature.rs1005-1051 tests/feature.rs1053-1094

超链接支持

Ripgrep 可以输出终端超链接，在支持的终端模拟器中点击时会打开匹配的文件。这通过 HyperlinkConfig 进行配置。可用的变量包括：

• {path} - 文件路径
• {line} - 行号
• {column} - 列号
• {host} - 主机名
• {wslprefix} - WSL 发行版前缀（适用于 Linux 子系统 for Windows）

内置的超链接方案包括：

• vscode - Visual Studio Code 格式（vscode://file{path}:{line}:{column}）
• textmate - TextMate 格式
• macvim - MacVim 格式
• file - 本地文件 URL 格式

来源：crates/printer/src/hyperlink.rs10-27 crates/printer/src/hyperlink_aliases.rs1-22

颜色支持

Ripgrep 支持通过 termcolor crate 进行终端颜色处理。颜色可以为各种元素配置：

• 匹配文本
• 文件路径
• 行号
• 上下文分隔符

颜色系统通过 ColorSpecs 结构实现，并处理跨平台的不同终端功能。

来源：crates/printer/src/standard.rs18 crates/printer/src/standard.rs64 crates/printer/src/standard.rs167-169

输出格式示例

标准格式

默认输出，显示文件名和匹配项

file.txt:This line contains a match

带行号

file.txt:10:This line contains a match

带上下文（-B1 -A1）

file.txt-9-Context line before
file.txt:10:This line contains a match
file.txt-11-Context line after

带标题（--heading）

file.txt
10:This line contains a match

仅匹配（-o）

file.txt:match

来源： tests/feature.rs79-111 tests/feature.rs215-238 tests/feature.rs89-111

JSON 格式

每个结果都是一个带有 type 字段和 data payload 的 JSON 对象

摘要格式

计数模式

file.txt:5

PathWithMatch 模式

file.txt

来源： tests/feature.rs215-238 tests/feature.rs223-230

统计收集

当启用统计信息时（使用 --stats），ripgrep 会收集

• 已用时间
• 搜索运行次数
• 匹配搜索次数
• 搜索字节数
• 打印字节数
• 匹配行数
• 总匹配数

这些统计信息可以在启用时通过 sink 的 stats 方法访问。

2 matches
1 matched lines
1 files contained matches
1 files searched
0.000048 seconds

来源： tests/feature.rs421-475

常用 CLI 选项

最常用的控制输出格式的 CLI 选项有：

选项	描述
--heading	将文件路径显示为标题
--no-filename	不显示文件路径
-n, --line-number	显示行号
--column	显示列号
-b, --byte-offset	显示字节偏移量
-o, --only-matching	仅显示匹配的文本
-r, --replace	将匹配项替换为文本
-m, --max-count	限制匹配数
--max-columns	限制行宽
--max-columns-preview	显示截断行的预览
--trim	修剪前导空格
--json	使用 JSON 格式
-c, --count	显示匹配计数
-l, --files-with-matches	仅显示匹配的文件
--color	控制颜色使用（永不、自动、总是）
--colors	配置特定颜色
-0, --null	使用 null 字节作为路径终止符
--passthru	打印所有行，并标记匹配的行
--sort-files	按文件路径排序结果

来源： tests/feature.rs79-111 tests/feature.rs215-248 tests/feature.rs309-332 tests/feature.rs349-368

实现细节

输出格式系统采用分层架构构建

1. Builder 类（StandardBuilder、JSONBuilder、SummaryBuilder）- 配置打印机
2. Printer 类（Standard、JSON、Summary）- 保存配置并创建 sink
3. Sink 实现（StandardSink、JSONSink、SummarySink）- 处理搜索结果并格式化输出

CounterWriter 包装输出写入器并计算写入的字节数，这对于统计信息很有用。Sunk 结构体提供了对匹配项和上下文行的统一抽象。

Printer 实现通过实现 Sink trait 与 grep_searcher::Searcher 配合工作，该 trait 接收匹配项和上下文行的回调。

来源： crates/printer/src/standard.rs714-751 crates/printer/src/util.rs163-219 crates/printer/src/counter.rs1-97