A data model for Git (and other docs updates)

2026-01-08

Git 的数据模型（及其他文档更新）

原文由 Julia Evans 于 2026-01-08 发布，订阅该博客

大家好！今年秋天，我决定花一些时间来完善 Git 的文档。很长一段时间以来，我一直在考虑参与开源文档的工作——通常如果我觉得某个东西的文档可以改进，我会写一篇博客或者做一本科普小志之类的。但这一次我在想：能不能直接去改进一下官方文档呢？

于是我和 Marie 一起，对 Git 文档做了一些改动！

Git 的数据模型

在处理文档一段时间后，我们注意到 Git 在文档中频繁使用“object（对象）”、“reference（引用）”或“index（索引）”这些术语，却没有很好地解释这些术语的含义，以及它们与“commit（提交）”和“branch（分支）”等核心概念之间的关系。于是我们写了一份新的“数据模型”文档！

你现在可以在这里阅读这份数据模型。我想在某个时候（下个版本发布之后？）它也会出现在 Git 官网上。

我对此感到很兴奋，因为多年来，理解 Git 如何组织提交和分支数据确实帮助我更好地理解了 Git 的工作原理，而且我认为拥有一份简短（仅 1600 字！）且准确的数据模型说明非常重要。

“准确”这一点做起来并不容易：我本来已经了解 Git 数据模型的基本原理，但在审阅过程中我又学到了一些新的细节，不得不做了不少修改（比如合并冲突在暂存区中的存储方式）。

对 `git push`、`git pull` 等的更新

我还对 Git 几个核心手册页的引言部分做了更新。很快我就意识到，仅仅“凭自己的判断去尝试改进”是行不通的：维护者凭什么相信我的版本会更好呢？

在讨论开源文档修改时，我经常看到这样的问题：软件的两位资深用户就某种解释是否清晰争论不休（“我觉得用 X 来解释很好！不，我觉得 Y 更好！”）

我觉得这种争论没什么成效（众所周知，资深用户往往很难判断某种解释对新手是否清晰），所以我需要找到一种更有依据的方法来发现手册页中的问题。

让试读者来发现问题

我在 Mastodon 上征集了试读者，请他们阅读现有版本的文档，并告诉我他们觉得困惑的地方或产生的疑问。大约有 80 位试读者留下了评论，我收获颇丰！

大家留下了大量非常棒的反馈，例如：

他们不理解的术语（什么是 pathspec？“reference”是什么意思？“upstream”在 Git 中是否有特定含义？）
令人困惑的具体句子
关于补充内容的建议（“我经常做 X，我觉得这里应该加上”）
不一致之处（“这里暗示 X 是默认值，但在别处又暗示 Y 是默认值”）

大多数试读者都已经使用 Git 至少 5 到 10 年了，我觉得这效果很好——如果一群已经规律使用 Git 5 年以上的试读者都觉得某个句子或术语难以理解，那就很容易说明文档确实应该修改得更清晰一些。

我觉得这种“让软件用户对现有文档发表评论，然后修复他们发现的问题”的模式效果非常好，我很期待将来有机会再次尝试。

对手册页的修改

我们最终更新了以下 4 个手册页：

git add（之前，之后）
git checkout（之前，之后）
git push（之前，之后）
git pull（之前，之后）

其中 git push 和 git pull 的改动对我来说最有意思：除了更新这两个页面的引言之外，我们最后还写了：

介绍“upstream branch”一词含义的章节（此前这一概念几乎没有得到解释）
对“push refspec”是什么的更清晰的描述

做这些修改让我真正体会到维护开源文档是多么费力：要写出既清晰又准确的内容并不容易，有时我们不得不做出妥协，例如这句话——“如果没有为当前分支设置 upstream，git push 可能会失败，具体取决于 push.default 的设置。”——就有点含糊，但“取决于”背后的确切细节其实非常复杂，要彻底理清是一个大工程。

关于为 Git 做贡献的流程

我花了一段时间才搞明白 Git 的开发流程。我不打算在这里详细描述（那完全可以另写一篇文章了！），不过简单提几点：

Git 有一个 Discord 服务器，其中有一个“my first contribution”频道，可以帮助新人入门贡献。我发现 Discord 上的人都非常热情友好。
我使用 GitGitGadget 提交了所有的贡献。这意味着我可以像往常一样发起 GitHub pull request（这是我熟悉的工作流程），而 GitGitGadget 会把我的 PR 转换成 Git 开发者所使用的系统（附带补丁的邮件）。GitGitGadget 非常好用，我很庆幸不必去学习如何用 Git 通过邮件发送补丁。
除此之外，我就用自己平常用的邮件客户端（Fastmail 的网页版）来回复邮件，并按照邮件列表的惯例将每行文本限制在 80 个字符以内。

我还觉得 lore.kernel.org 上的邮件列表归档很难浏览，于是自己动手拼了一个我自己的 git list viewer，以便更方便地阅读那些很长的邮件讨论串。

许多人在贡献流程和审阅修改方面给了我帮助：感谢 Emily Shaffer、Johannes Schindelin（GitGitGadget 的作者）、Patrick Steinhardt、Ben Knoble、Junio Hamano 等人。

（我正在 Mastodon 上尝试评论功能，你可以在这里查看评论）