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 如何組織 commit 和 branch 的資料真的幫助我更能掌握 Git 的運作方式，而我覺得有一份簡短（只有 1600 字！）又準確的資料模型版本是很重要的。

不過「準確」這部分沒那麼容易：我原本已經知道 Git 資料模型的基本運作方式，但在審閱過程中我又學到了一些新的細節，不得不做了不少修改（例如合併衝突在暫存區中是如何儲存的）。

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

我也著手更新了幾個 Git 核心 man page 的前言。我很快就意識到，單靠「就照我自己的判斷盡量改得更好」是行不通的：維護者為什麼要相信我的版本比較好？

在討論開源文件的修改時，我常常看到這樣的問題：兩個軟體的專家使用者爭論某個說明到底清不清楚（「我覺得用 X 來解釋比較好！」「不，我覺得 Y 比較好！」）

我覺得這樣沒什麼效率（眾所皆知，軟體的專家使用者往往很難判斷一個說明對非專家來說是否清楚），所以我需要找到一種更有根據的方式來找出 man page 的問題。

找試讀者來找出問題

我在 Mastodon 上招募試讀者，請他們閱讀現有版本的文件，並告訴我他們覺得哪裡困惑、有什麼疑問。大約有 80 位試讀者留下了意見，讓我收穫非常多！

大家提供了大量很棒的回饋，例如：

他們不懂的術語（什麼是 pathspec？「reference」是什麼意思？「upstream」在 Git 裡有特定的含義嗎？）
讓人困惑的特定句子
建議新增的內容（「我常常做 X，我覺得應該把它加進來」）
不一致的地方（「這裡暗示預設是 X，但別的地方卻暗示預設是 Y」）

大多數試讀者都已經使用 Git 至少 5 到 10 年，我覺得這樣的組合效果很好——如果一群已經規律使用 Git 五年以上的試讀者都覺得某個句子或術語完全看不懂，那就很容易主張文件應該要修改得更清楚。

我覺得這種「先讓軟體的使用者對現有文件發表意見，再針對他們發現的問題去修正」的模式效果非常好，也很期待未來有機會再嘗試一次。

man page 的異動

我們最後更新了這 4 個 man page：

git add (修改前、修改後)
git checkout (修改前、修改後)
git push (修改前、修改後)
git pull (修改前、修改後)

對我來說，git push 和 git pull 的修改最有趣：除了更新這些頁面的前言之外，我們最後還寫了：

解釋「upstream branch」這個詞是什麼意思的章節（之前幾乎沒有說明過）
整理過後、關於什麼是「push refspec」的說明

進行這些修改真的讓我體會到維護開源文件需要多少工夫：要寫出既清楚又正確的內容並不容易，有時候我們也必須做出妥協，例如「git push may fail if you haven’t set an upstream for the current branch, depending on what push.default is set to.」這句話有點模糊，但「depending」背後的精確細節其實非常複雜，要徹底釐清是一項大工程。

關於參與 Git 貢獻的流程

我花了一段時間才搞懂 Git 的開發流程。我在這裡就不打算詳細描述（那大概可以另外寫一篇文了！），不過先簡單提幾個重點：

Git 有一個Discord 伺服器，裡面有一個 “my first contribution” 頻道，可以幫助新手開始參與貢獻。我覺得 Discord 上的人都非常友善。
我所有的貢獻都是透過GitGitGadget 提交的。這表示我可以用我熟悉的 GitHub pull request 流程來發 PR，而 GitGitGadget 會把我的 PR 轉換成 Git 開發者使用的系統（附上 patch 的電子郵件）。GitGitGadget 運作得非常順暢，讓我不用去學怎麼用 Git 透過電子郵件寄送 patch，對此我非常感激。
其他時候我就是用平常的電子郵件客戶端（Fastmail 的網頁介面）來回信，並把文字折行成每行 80 個字元，因為這是郵件清單的慣例。

我也覺得 lore.kernel.org 上的郵件清單封存不太好瀏覽，所以就自己拼湊了一個自製的 git 清單檢視器，讓長長的郵件討論串更容易閱讀。

有許多人幫助我熟悉貢獻流程並審閱這些修改：感謝 Emily Shaffer、Johannes Schindelin（GitGitGadget 的作者）、Patrick Steinhardt、Ben Knoble、Junio Hamano 等人。

（我正在嘗試在 Mastodon 上的留言功能，你可以在這裡看到留言）