Zed 内置 Diff 语言支持解析：Tree-sitter 语法高亮、保护性编辑策略与扩展识别配置

Zed 原生内置了 Diff 语言支持，无需安装任何扩展即可对 *.patch、*.diff 及类似文件进行语法高亮与基础编辑。本文以 Zed 仓库的 Diff 语言官方文档 为主线，结合 grammar 目录、语言注册代码与语法查询文件，讲解 Diff 文件在 Zed 中的解析实现、高亮语义、特殊的编辑保护策略，以及如何通过 file_types 自定义扩展名识别，帮助你在日常 code review 与补丁审阅场景中高效使用。

Zed 对 Diff 的内置支持与实现位置

Diff 支持在 Zed 中开箱即用，属于随编辑器一起分发的一组原生语言之一。其语法解析能力来自 Tree-sitter 生态的 the-mikedavis/tree-sitter-diff 文法（原文档即标注了该上游项目，此处仅为说明来源，可直接在 crates/grammars/Cargo.toml 中看到对应依赖声明）。

在仓库中可以找到支持链路的两层证据：

1. 文法注册：在 crates/grammars/src/grammars.rs 中，native_grammars() 函数将 ("diff", tree_sitter_diff::LANGUAGE.into()) 注册进内置 grammar 列表，与 bash、rust、typescript 等语言并列。
2. 语言配置目录：crates/grammars/src/diff/ 目录下存放了 Diff 语言运行所需的三个核心文件：
   • config.toml——语言识别与基本元数据配置；
   • highlights.scm——语法高亮查询规则；
   • injections.scm——注入规则。

编译运行时，这些内容通过 crates/grammars/src/grammars.rs 中的 util::fs_embed! 宏嵌入二进制，或按构建模式在开发时从目录实时读取。

config.toml：语言识别元数据

crates/grammars/src/diff/config.toml 全文仅五行，却定义了该语言的全部识别规则：

name = "Diff"
grammar = "diff"
path_suffixes = ["diff", "patch"]
brackets = []

逐字段说明：

• name：语言对外显示的名称，即 Zed 语言选择器、file_types 等配置中引用的字符串 "Diff"（注意首字母大写）；
• grammar：实际调用的 tree-sitter grammar 键名，对应上文注册表中的 "diff"；
• path_suffixes：文件扩展名识别表，这就是"自动识别 patch 和 diff 扩展名"的源码出处。Zed 在打开文件时会根据文件路径后缀匹配该表；
• brackets：留空表示 Diff 没有需要编辑器配对的高亮括号对，这与 Diff 文件是纯文本补丁的本质一致。

语法高亮的节点语义映射

Diff 的高亮效果并非硬编码，而是由 Tree-sitter 查询文件驱动。highlights.scm 将语法树节点映射为 Zed 的主题色标。了解这张映射表，可以帮你在自定义主题或排查高亮异常时定位问题：

语法树节点/字面量	捕获标签	语义
comment	comment	注释内容
addition、new_file	string + diff.plus	新增行与新增文件头，匹配 diff.plus 语义色
deletion、old_file	keyword + diff.minus	删除行与旧文件头，匹配 diff.minus 语义色
commit	constant	commit 摘要信息
location	attribute	文件路径定位行（如 --- a/x、+++ b/x）
command 中的 diff 与 argument	function、variable.parameter	补丁命令与参数
mode	number	权限模式变化
..、+、++、+++、++++、-、--、---、----	punctuation.special	增删标记符号
binary_change、similarity、file_change	label	二进制变更、相似度、文件变化说明
index	keyword	index 关键字行
similarity 中的 score 与 %	number	相似度百分比

从这套规则可以看出 Zed 对补丁阅读体验的精细处理：加行、删行、hunk 头信息、文件路径各自获得不同的捕获标签，并与 Zed 的 diff.plus / diff.minus 语义色联动，因此在查看 git diff 导出的补丁时，增删对比一目了然。

针对 Diff 文件定制的编辑保护策略

与其他可格式化的源代码不同，Diff 文件在 Zed 中享受一套"保守编辑"策略。原文档明确说明：Zed 不会尝试对 diff 文件执行格式化，并且针对 Diff 语言将两个通用保存设置设为 false：

• remove_trailing_whitespace_on_save：保存时移除行尾空白；
• ensure_final_newline_on_save：保存时确保文件以换行符结尾。

这一设计有其技术必然性，可结合 Diff 文件格式本身理解：

1. 行尾空白是有意义的：补丁中一个"看似空的"变更行，实际会携带 +/- 前缀以表达该行存在与否。若盲目裁剪行尾空白，会破坏补丁的精确字节内容；
2. 结尾换行是语义的一部分：补丁中常出现 \ No newline at end of file 标记来表示"该文件结尾无换行"，强制补一个换行会直接篡改补丁所描述的文件状态；
3. 格式化会破坏补丁上下文：Diff 的缩进与空白是内容本身而非排版，任何 formatter 介入都可能改变行内容导致补丁失效。

因此 Zed 将 Diff 视为"内容精确"的文本类型：只提供语法感知的查看与导航，绝不越界改写补丁语义。这也是代码审阅类用户最需要的编辑器行为。

文件类型识别与自定义扩展名

默认识别的扩展名

通过上文 path_suffixes = ["diff", "patch"]，Zed 会自动把以下文件识别为 Diff 语言：

• 以 .patch 结尾的文件（例如 Git、git format-patch 的输出）；
• 以 .diff 结尾的文件（例如 git diff > change.diff 的重定向结果）。

用 file_types 扩展识别范围

某些工作流会使用其他后缀保存补丁（例如 *.dif、*.udiff 或团队约定后缀）。此时可在 Zed 的 settings.json 中通过 file_types 把它们映射到 "Diff"：

  "file_types": {
    "Diff": ["dif"]
  },

说明与注意事项：

• 键名必须严格使用语言显示名称 Diff（与 config.toml 中的 name 一致）；
• file_types 值为数组，可一次添加多个后缀，例如 "Diff": ["dif", "udiff"]；
• 该映射的优先级高于默认的 path_suffixes 识别，可用于覆盖个别文件的识别结果；
• 由于 Zed 的 file_types 是通用的语言文件关联机制（适用于所有语言），在 Diff 场景下它解决的只是"让编辑器认出它是补丁"，识别成功之后高亮、编辑保护策略便会一并生效。

小结

Diff 语言支持虽小，却是 Zed 内置语言体系中设计考究的一员：tree-sitter 解析提供可靠的结构化高亮，diff.plus/diff.minus 语义色让增删对比直观，而"不格式化、不裁剪空白、不强制换行"的编辑策略从根源上保护了补丁内容的字节级精确性。若你在审阅补丁时发现某些特殊后缀未被识别，只需在 settings.json 中为 "Diff" 补一条 file_types 映射即可。

如需进一步查看实现，可对照阅读 语言注册代码、diff 语言配置 与 高亮规则；完整用户文档见 docs/src/languages/diff.md。