• 开发工具
• CLI

导读

本文介绍如何使用 delta 将git show、git diff等输出的彩色 diff 保存为带颜色的 HTML 文件，并借助浏览器打印功能进一步导出为 PDF。你将掌握一条完整的 ANSI 转 HTML 管道命令，理解--no-gitconfig、--file-decoration-style、--hunk-header-decoration-style等关键参数的实际作用与取值规则，并了解 ansifilter 在超链接、装饰框等特性上的已知限制，从而在自己的机器上获得可复制、可分享的彩色 diff 快照。

一、整体思路：delta 着色 + ansifilter 转 HTML

delta 本质是一个"渲染层"：它读取 git 等工具的标准输出，为 diff 内容追加 ANSI 转义序列（颜色、样式、装饰框、行号等）。终端能解释这些转义序列，但 HTML 文件不能。因此导出流程分两步：

1. 用 delta 对 diff 输出进行美化着色；
2. 用 ansifilter 把带 ANSI 转义序列的文本流转换为等价的 HTML 标记。

这也是官方文档 export-to-html.md 给出的核心工作流，一条管道即可完成：

git show \ | delta --no-gitconfig --file-decoration-style blue --hunk-header-decoration-style blue \ | ansifilter --html \ > /tmp/diff.html

随后用浏览器打开/tmp/diff.html，即可查看彩色 diff，也可以直接在浏览器的打印对话框中选择"另存为 PDF"，完成 PDF 导出。

二、安装 ansifilter

管道中的唯一外部依赖是 ansifilter。它负责将 ANSI 转义序列（SGR 颜色、加粗、下划线等）翻译成 HTML 的<span>与内联样式。macOS 用户可以直接通过 Homebrew 安装：

brew install ansifilter

Linux 发行版通常也在软件源中提供ansifilter包（如 Debian/Ubuntu 的apt install ansifilter）。安装完成后可用ansifilter --help确认版本与可用输出格式（--html、--latex、--rtf等，本文聚焦--html）。

三、逐段拆解管道命令

1. 输入源：git show

git show默认展示最近一次提交的完整 diff（含 commit 元信息）。你可以按需替换输入源：

• 查看指定提交：git show <commit-ish>
• 查看未暂存改动：git diff
• 查看暂存区改动：git diff --cached
• 查看最近 N 条提交的合并输出：git log -p -n 3

delta 兼容这些输入，因为它解析的是统一 diff 格式的标准文本流，而非 git 内部对象。

2. 渲染：delta 及其参数

这条示例命令为 delta 显式指定了三个参数，全部是为了"导出场景"服务的：

--no-gitconfig：完全忽略 git 配置中[delta]段（以及.gitconfig中设置的全部 delta 选项），只使用命令行参数与默认值。从源码看，该选项的作用层级有两处：

• 在 src/cli.rs 中，from_args_and_git_config会在--no-gitconfig存在时直接将final_config置为None，即不加载任何 git 配置；
• 在 src/options/set.rs 中，set_options还会将已加载的GitConfig.enabled置为false，确保后续合并选项时不再读取配置。

因此--no-gitconfig能保证"无论这台机器上的.gitconfig长什么样，输出都一致"，这对导出可复现的 HTML 非常有用——尤其是当本机配置了side-by-side、line-numbers、自定义语法主题等会显著改变布局的选项时。

--file-decoration-style blue：文件路径行的装饰样式。其 CLI 定义位于 src/cli.rs，默认值是"blue ul"（蓝色下划线）。STYLE 字符串必须包含特殊属性之一：box（方框）、ul（下划线）、ol（上划线），或组合ul ol。示例中写成blue表示"仅着色、不带装饰符号"。

--hunk-header-decoration-style blue：hunk 头（形如@@ -1,5 +1,7 @@的行）的装饰样式，定义位于 src/cli.rs，默认值为"blue box"（蓝色方框）。同样支持box/ul/ol特殊属性。

为什么要刻意去掉box？因为方框装饰依赖特殊的 Unicode 制表符（╭、│、╰等），而 ansifilter 对这类装饰符号的转换支持有限（见第五节限制说明）。把两处装饰都收敛成纯色blue，可以让最终 HTML 的每一行都是干净可读的普通文本行。

3. 转换：ansifilter --html

ansifilter --html读取标准输入中的 ANSI 转义序列并输出 HTML。最终通过>重定向写入/tmp/diff.html。这里值得注意：

• 命令对输出做了重定向，因此 delta 与 ansifilter 都不需要分页器参与，建议同时配合--paging never（该选项定义于 src/cli.rs）以确保输出直接落到管道而非 less；
• 如果你的终端与 delta 交互时启用了 24-bit truecolor 输出（参见 24-bit-color-truecolor.md），而 ansifilter 版本不支持\x1b[38;2;R;G;Bm序列，颜色可能丢失或错乱，可通过 delta 的--true-color选项（src/cli.rs）显式控制；
• 宽 diff 行可能被 delta 按终端宽度换行（--width，见 src/cli.rs），导出为 HTML 前可适当调大宽度，避免内容被截断。

四、去掉--no-gitconfig：使用你自己的风格

如果希望导出的 HTML 使用你日常配置的 delta 风格（自定义语法主题、行号、配色等），只需移除--no-gitconfig：

git show \ | delta --file-decoration-style blue --hunk-header-decoration-style blue \ | ansifilter --html \ > /tmp/diff.html

此时 delta 会读取~/.gitconfig中[delta]段的全部设置，例如：

[delta] side-by-side = true line-numbers = true syntax-theme = Monokai Extended minus-style = syntax "#340001" plus-style = syntax "#000200"

注意两点：

1. 务必保留两个--*-decoration-style blue覆盖。因为命令行参数优先级高于 git 配置（delta 的选项合并顺序遵循 set.rs 中的规则，命令行显式参数覆盖配置文件），所以即使配置里写了hunk-header-decoration-style = white box，这里也会被显式参数压成纯色blue，从而避开方框符号。
2. 确认本机配置不包含 ansifilter 无法处理的特性，例如hyperlinks（超链接）、方框类装饰、raw输出等，否则 HTML 中可能出现乱码或失控样式（详见下节）。

五、已知限制：ansifilter 不处理的特性

官方文档明确提醒：ansifilter 不处理超链接与装饰方框。具体表现为：

• 超链接（hyperlinks）：delta 的--hyperlinks选项（见 src/cli.rs）会在输出中嵌入终端超链接 OSC 序列（commit hash 链接到 GitHub、文件名与行号链接到本地文件）。这类 OSC 序列并非 ANSI SGR 颜色码，ansifilter 的 HTML 转换不会将它们翻译为<a>标签，最终在浏览器中表现为一串可见的乱码或噪音字符。导出前应关闭--hyperlinks。
• 装饰方框（decoration boxes）：box装饰输出的╭─╮│╰╯制表符绘制边框，ansifilter 不会把它们转换为 HTML/CSS 边框，导致 HTML 中出现裸的特殊字符。这就是示例命令把两个 decoration style 都改成纯blue的原因。
• 24-bit 颜色与部分样式组合：不同 ansifilter 版本对38;2;...;m扩展色的支持程度不同，若输出颜色异常，可用--true-color never（配置写法true-color = never，见 set.rs）回退到 256 色模式。

测试用例也可佐证这些样式参数的行为边界：在 src/tests/test_example_diffs.rs 中，--hunk-header-decoration-style支持omit、none、空字符串等"无装饰"取值，且white box等组合被专门测试（见 test_example_diffs.rs）。这说明 delta 的装饰样式设计本身就以终端为第一渲染目标，导出到 HTML 时选择最朴素的取值（纯色、无 box）是最稳妥的策略。

六、导出 PDF 与进一步美化

HTML 生成后，导出 PDF 非常简单：在浏览器中打开/tmp/diff.html，按Ctrl/Cmd + P（打印），在目标中选择"另存为 PDF"即可。浏览器会按页面宽度重新排版 HTML，且保留 ANSI 颜色转换而来的内联颜色样式。

若想得到更适合打印的效果，可以给 delta 补充排版类参数：

git show \ | delta --no-gitconfig \ --file-decoration-style blue --hunk-header-decoration-style blue \ --paging never \ --true-color never \ --width 120 \ | ansifilter --html \ > /tmp/diff.pdf.html

• --paging never：关闭分页，保证管道输出完整（对应配置项paging = never，见 set.rs）；
• --true-color never：统一回退 256 色，兼顾 ansifilter 兼容性；
• --width 120：避免长行被换行截断，提升打印可读性。

七、小结与相关阅读

完整流程可以概括为：git 输出 → delta 着色（去除装饰/超链接特性）→ ansifilter 转 HTML → 浏览器查看或打印为 PDF。核心要点是：导出场景下，delta 的职责是提供稳定的 ANSI 颜色流，而装饰框、超链接这类"终端专属"特性应主动关闭，避免污染 HTML 输出。

如需进一步了解相关主题，可继续阅读仓库内的以下资料：

• export-to-html.md：本文所依据的官方原始文档；
• tips-and-tricks.md：其他使用技巧的入口页；
• configuration.md：delta 全部配置项与 git 配置写法；
• full---help-output.md：delta --help的完整输出，含全部命令行参数说明；
• 24-bit-color-truecolor.md：truecolor 输出与终端兼容性；
• side-by-side-view.md：并排视图模式，适合导出到宽幅页面打印。

• 开发工具
• CLI