Reading

Version Control


Fanyi Pu · GPT-6 Astra

Git 的数据模型

Git 用对象表示项目的文件状态和版本历史,用引用为提交命名。文件状态描述某个版本包含哪些路径及其内容;版本历史描述提交之间的先后与分叉关系。

文件、目录与快照

Git 的 blob 保存文件内容,即一串字节,不包含文件名。tree 表示一个目录,其中每个条目记录名字、文件模式和所引用的对象。普通文件条目指向 blob,子目录条目指向另一个 tree。根 tree 及其递归引用的对象确定整个项目的文件状态,称为一个快照。具体结构见 Git 对象模型。

下面沿用 Missing Semester 2026 的目录示例:根目录包含子目录 foo 和文件 baz.txt,foo 中包含文件 bar.txt。图中将目录条目与它引用的对象分开画出。

根目录、子目录与文件内容根 tree 的 foo 条目指向子 tree,子 tree 的 bar.txt 条目指向内容为 "hello world" 的 blob;根 tree 的 baz.txt 条目直接指向内容为 "git is wonderful" 的 blob。<root> (tree)foobaz.txttreebar.txtblob"git is wonderful"blob"hello world"
根 tree 的 foo 条目指向子 tree,子 tree 的 bar.txt 条目指向内容为 "hello world" 的 blob;根 tree 的 baz.txt 条目直接指向内容为 "git is wonderful" 的 blob。

文件名属于目录条目,内容属于 blob。两份目录清单可以引用同一个 blob;一个文件改名而内容不变时,也可以复用原来的 blob。快照描述的是 Git 跟踪的文件状态,不包括未跟踪文件,也不是操作系统全部文件属性的备份。

提交与历史

commit 对象记录一个根 tree、父提交、作者、提交者、时间和提交说明。根 tree 确定这个版本的内容,父提交确定它在历史中的位置。初始提交没有父提交,普通提交通常有一个父提交,合并提交可以有多个父提交。字段定义见 git commit-tree。

提交之间的父子关系构成有向无环图。以下用 A、B、C、D 代替提交 ID,箭头均从提交指向其父提交:

顺序提交C 的父提交是 B,B 的父提交是 A;A 没有父提交。ABC
C 的父提交是 B,B 的父提交是 A;A 没有父提交。

两个修改都从 B 开始,就会形成分叉。合并提交 M 可以同时以 C 和 D 为父提交:

分叉与合并的提交图箭头从提交指向父提交。C、D 共享父提交 B;M 有两个父提交 C 和 D。ABCDM
箭头从提交指向父提交。C、D 共享父提交 B;M 有两个父提交 C 和 D。

M 的 tree 记录合并后的文件状态;两个 parent 记录被连接起来的历史。提交图描述版本关系,目录树描述文件结构,这两种关系需要区分。

继续使用上面的目录。第一次提交后,将 baz.txt 从 git is wonderful 改为 git is great,foo/bar.txt 不变,再提交一次。这个修改实验是在 Missing Semester 的目录示例上扩展的。新 commit 引用新的根 tree 和新的 baz.txt blob;foo 的整个子 tree 及其引用的 blob 都可以复用。

两次提交共享未变化的子目录每个 commit 指向自己的根 tree。旧 tree 的 baz.txt 指向旧 baz.txt blob,新 tree 的 baz.txt 指向新 baz.txt blob;两棵 tree 的 foo 都指向同一个 foo tree。新 commit 另有一条 parent 引用指向旧 commit。实线表示查找文件状态,虚线表示历史关系。上一次 committree旧 treebaz.txtfooblobgit is wonderful这一次 committree新 treebaz.txtfooblobgit is greatparent同一个 foo treec68d233
每条实线都表示对象引用:baz.txt 变了,根 tree 改为引用新 blob;foo 没变,两棵根 tree 共用同一个子 tree。共享的 foo tree 仍引用内容为 hello world 的 bar.txt blob。虚线 parent 连接提交历史。

沿 tree 引用可以读取一个版本的文件,沿 parent 引用可以遍历历史。读取某个版本的文件状态不要求按时间顺序重放每次修改。对象的物理压缩与重建放在后面的“文件存储与规模”一节讨论。

对象 ID 与内容寻址

blob、tree 和 commit 都属于 Git 对象。对象通过 object ID 标识,其他对象用 ID 引用它。在同一种对象格式下,ID 由对象类型、长度和内容计算哈希得到;相同的对象具有相同 ID。这种用内容决定地址的方式称为内容寻址,编码规则见 Git 对象格式。

因此,内容发生变化时,会形成新的对象,而不是覆盖原对象。例如,baz.txt 变化会产生新的 blob;根 tree 中的对应条目随之变化,根 tree 也获得新的 ID。没有变化的 blob 和子 tree 可以继续复用。

commit 的 ID 还受到父提交、身份、时间和提交说明的影响。两个 commit 可以引用同一个根 tree,却具有不同 ID:它们的文件状态相同,但历史或元数据不同。所谓改写提交,是创建新的 commit 并调整引用,不是在原 ID 下修改对象内容。

分支、引用与 HEAD

**引用(reference)**为对象 ID 提供名称。分支引用指向一个 commit,并可以更新;commit 对象本身不随引用的移动而改变。通常附着于分支时,HEAD 是指向当前分支的符号引用;detached HEAD 状态下,它直接记录一个 commit ID。参见 Git References 和 git symbolic-ref。

HEAD、分支引用与提交HEAD 指向分支 main,main 指向提交 C。虚线是可更新的引用,实线是 commit 中记录的 parent。HEADmainparentCB分支引用commit 对象
HEAD 指向分支 main,main 指向提交 C。虚线是可更新的引用,实线是 commit 中记录的 parent。

新建分支是增加一个引用,不需要复制项目文件或历史。多个分支可以指向同一个提交,也可以共享一段历史。切换分支时如何更新工作目录,与引用本身的表示是两个层面,后面按操作分别说明。

读取对象与比较版本

继续观察这两次提交。HEAD 是当前提交,HEAD~1 是它的第一个父提交。完整的建仓步骤放在本小节末尾。

git ls-tree 列出根 tree 的条目:

bash
git ls-tree --abbrev=7 HEAD~1
git ls-tree --abbrev=7 HEAD

两次输出依次为:

code
100644 blob 4448adb baz.txt
040000 tree c68d233 foo
code
100644 blob 8115464 baz.txt
040000 tree c68d233 foo

四列分别是文件模式、对象类型、缩短后的对象 ID 和名字。100644 表示普通的非可执行文件,040000 表示目录。baz.txt 的 blob ID 变了,foo 的 tree ID 没变。

继续沿 foo 查找,再读取文件内容:

bash
git ls-tree --abbrev=7 HEAD:foo
# 100644 blob 3b18e51 bar.txt

git cat-file -p HEAD:foo/bar.txt
# hello world

这里的路径是查找对象的方式。也可以将 ls-tree 输出的对象 ID 交给 git cat-file -p,直接读取同一个对象。

git cat-file -p HEAD 显示 commit 对象。用占位名称代替实际值后,输出结构如下:

code
tree <根 tree 的 ID>
parent <父 commit 的 ID>
author <作者及时间>
committer <提交者及时间>

Update baz.txt

读取旧版 baz.txt 时,从旧 commit 找到根 tree,再按文件名查找 blob:

bash
git show HEAD~1:baz.txt
# git is wonderful
沿旧提交读取 baz.txtHEAD~1 选中上一次提交,从它的 tree 中查找 baz.txt,得到 blob 4448adb,再读取旧内容。无需修改工作目录。HEAD~1上一次 committree旧目录清单baz.txt → 4448adbfoo → c68d233读取选中的 blob4448adbgit is wonderful末尾有一个换行符
选定版本 → 按文件名找到内容 ID → 读出旧内容。绿色条目是这次查找走过的路径。

show 显示所选内容,不覆盖工作目录中的文件。比较两个版本则使用:

bash
git diff HEAD~1 HEAD -- baz.txt

其中内容变化为:

diff
-git is wonderful
+git is great

diff 是对两个版本内容的比较结果。commit 记录快照引用和历史信息,并不保存这份逐行差异。

复现目录与两次提交

在一个新目录中运行下面的命令。需要已经配置 Git 的提交姓名和邮箱。例子使用 SHA-1 对象格式、LF 换行,且没有额外的内容转换规则。

bash
mkdir git-objects-example
cd git-objects-example
git init --object-format=sha1
git config core.autocrlf false
mkdir foo
printf 'hello world\n' > foo/bar.txt
printf 'git is wonderful\n' > baz.txt
git add foo/bar.txt baz.txt
git commit -m "Initial snapshot"

printf 'git is great\n' > baz.txt
git add baz.txt
git commit -m "Update baz.txt"

然后执行正文中的 ls-tree、cat-file、show 和 diff 命令。文件的空格、换行和编码会影响 blob ID,提交的身份和时间会影响 commit ID。使用 SHA-256 对象格式时,ID 也会不同。

Git 的操作与状态变化

工作目录、暂存区与提交

Git 的日常操作涉及三种状态:

状态含义
工作目录当前供编辑器、编译器等程序读写的文件
暂存区(index)准备写入下一次提交的文件状态
当前提交已记录的版本,由 HEAD 确定

在没有合并冲突的普通工作区中,index 记录路径、文件模式、选定的 blob ID 和缓存信息等。它包含未修改的已跟踪文件,而不只包含“这次改过的文件”。

add 与 commit

暂存区允许工作目录与下一次提交包含不同内容。Missing Semester 的暂存区示例是:修复 bug 时加入了调试输出,但只希望提交修复。

将这个场景具体化:add.py 中的 add(a, b) 原来误写成 return a - b。现在改为 return a + b,并临时加入 print(a, b) 来检查输入。修复需要保留,调试输出暂不提交。

工作目录修复 + 调试输出:add.py 返回 a + b,并打印 a、b。工作目录修复 + 调试输出add.pydef add(a, b):print(a, b)return a + b暂存区只选入修复:add.py 返回 a + b,没有调试输出。暂存区只选入修复add.pydef add(a, b):return a + b新提交保存暂存区的内容:add.py 返回 a + b,没有调试输出。新提交保存暂存区的内容add.pydef add(a, b):return a + b
原提交中是 return a - b。新提交保存加法修复;虚线框中的 print(a, b) 只留在工作目录里。

可以先让文件只包含修复,执行 git add add.py,然后再加入调试输出。add 保存的是执行那一刻的内容;之后编辑工作目录,不会自动改变 index 中已经选定的版本。

bash
# 先保存只包含修复的版本,再暂存
printf 'def add(a, b):\n    return a + b\n' > add.py
git add add.py

# 继续调试:此时只改变工作目录
printf 'def add(a, b):\n    print(a, b)\n    return a + b\n' > add.py
git diff --cached -- add.py
git diff -- add.py
git commit -m "Fix addition"

这段操作假设 add.py 的错误版本已在当前提交中。git diff --cached 显示减法改为加法,git diff 显示新增的调试输出。普通 git commit 根据 index 创建新 commit,因此只提交修复,print(a, b) 仍是工作目录中未暂存的修改。如果两种修改已经混在工作目录中,也可以用 git add -p 选择要暂存的部分。

不带路径或 -a 的普通 git commit 根据 index 生成目录树,并在附着于分支的状态下更新当前分支引用。git ls-files --stage 可以观察 index 中的文件模式、对象 ID 和 stage 编号。

准备暂存区实验的初始版本

在另一个新目录中执行,再接着运行上面的修复与调试命令:

bash
mkdir git-index-example
cd git-index-example
git init
printf 'def add(a, b):\n    return a - b\n' > add.py
git add add.py
git commit -m "Add function"

diff 的比较对象

命令比较的两端
git diffindex 与工作目录
git diff --cachedHEAD 与 index
git diff HEADHEAD 与工作目录
git diff A B提交 A 与提交 B

前两项分别显示尚未暂存和已经暂存的变化。这里讨论已跟踪文件的普通修改;未跟踪文件不会自动成为 git diff 的比较内容。

分支、合并与历史改写

待展开:

  • branch 与 switch:引用的创建和移动、HEAD 的变化、工作目录与 index 的更新。
  • 三方合并:共同祖先、两侧修改与合并结果;文本冲突和行为不兼容的区别。
  • merge、rebase 与 amend:提交图、对象身份和后续提交的变化。
  • restore、reset、revert 与 reflog:恢复文件、移动引用、反向提交和找回历史的不同作用。

仓库同步与协作

对象传输与引用更新

待展开:

  • 本地与远端分别持有的对象和引用,remote-tracking references 的含义。
  • clone、fetch、push 的对象传输、缺失对象判定和引用更新。
  • 本地历史查询与远端通信的边界;取得对象与展开工作目录的区别。
  • 同步前后的双仓库示意图,以及并发更新时的检查和拒绝条件。

托管平台与协作记录

待展开:

  • Git 仓库与 GitHub 等托管平台的职责;PR、评审、权限和检查结果。
  • Fossil 的版本历史、issue、wiki 与 SQLite 存储;集成协作信息的同步方式。
  • 仓库迁移、备份、离线使用和权限边界:代码以外的信息能否一起恢复。

其他版本模型

SVN:仓库 revision 与工作副本

待展开:

  • 全局 revision、原子提交、工作副本基准、局部更新与 mixed revisions。
  • 目录复制表示 branch/tag、merge tracking、在线与离线操作。
  • 两个工作副本的提交、更新和合并;与 Git 本地提交及后续 push 对照。

Perforce:depot、workspace 与 changelist

待展开:

  • depot 到 workspace 的映射,pending/submitted changelist、shelve 与 streams。
  • 文件锁、并发编辑和 exclusive checkout;区分 p4 lock 与 +l。
  • 路径权限、局部同步、断线恢复;文件锁与跨文件语义一致性的边界。

Mercurial:changeset、manifest 与文件历史

待展开:

  • changelog、manifest 和 filelog 各自记录的信息及其关联。
  • named branches、bookmarks 与 Git 分支引用的区别。
  • 逻辑版本模型与 revlog 存储的分层;存储细节在“文件存储与规模”中对照。

Darcs 与 Pijul:patch 模型

待展开:

  • patch 的上下文、依赖与组合;独立修改和依赖修改的区别。
  • Darcs 的 patch algebra 与 Pijul 的图表示,分别说明其机制。
  • patch commutation、冲突记录与冲突解决的传播;与 cherry-pick、rebase 对照。
  • 改变引入顺序的实验;逻辑变更模型与存储 delta、文本合并与程序正确性的区别。

工作区与历史整理

jj

待展开:

  • working-copy commit、change ID、commit ID、bookmarks 和 Git 存储后端。
  • 一段具体操作:编辑、拆分修改、补充前面的提交、调整后续提交、处理冲突、撤销操作。
  • 每一步的状态图及必要命令;冲突表示与 operation log。
  • Git 兼容边界与实际测试版本。

Mercurial evolution 与 Sapling

待展开:

  • phases、obsolescence markers 与 changeset evolution;已发布历史和可改写历史。
  • Sapling 的 smartlog、提交堆栈、历史改写与恢复。
  • CLI、Mononoke 服务端和 EdenFS 工作区的分工;扩展、实验性功能和 Git 兼容模式。

GitButler 与 Graphite

待展开:

  • GitButler 的并行修改、改动归属和提交整理;共享工作目录中的运行状态。
  • Graphite 的 stacked branches/PR、评审修改和 restack。
  • 提交依赖、任务依赖和评审依赖;工具元数据与 Git 状态的关系。
  • 退出工具后可保留的历史与需要迁移的协作状态。

文件存储与规模

对象复用与压缩

版本模型、差异展示和物理存储是三个层次:

层次内容
版本模型commit 引用根 tree,根 tree 确定文件状态
差异展示比较两个版本的内容,生成 diff
物理存储复用相同对象,对不同对象进行压缩和组织

文件内容不变时可以复用 blob;子目录的条目不变时可以复用 tree。完整快照不意味着每次提交都复制整个项目。

Git 通常先把新对象保存为单独的 loose object,之后可以通过维护操作将它们整理进 packfile。修改前后的文件虽然是不同的 blob,仍可能包含大量重复字节。packfile 可以保存基准对象和 delta,用重建指令复用相似内容。

从基准和重建指令还原完整内容示意:以旧内容为基准,复制前缀,写入 great,复制换行,重建新内容。此图说明 delta 的作用,不代表本例 Git 实际选择的编码或基准方向。基准:旧内容git is␣wonderful换行重建指令(示意)① 复制前 7 bytes:git is + 空格② 写入 5 bytes:great③ 复制末尾的换行符重建结果:完整的新内容git is␣great换行
delta 可以复用相似内容中的一部分。这里仅示意字节复用,不表示 Git 会对这个短文件采用 delta。␣ 表示空格;基准选择不受提交先后顺序限制。

存储上的基准依赖不要求与 commit 的父子关系一致,基准也不必是历史上更早的版本。读取对象时可能需要解压和重建,重建后仍然得到原 ID 标识的完整对象。压缩不改变 commit、tree 和 blob 的逻辑引用关系;具体编码见 pack 格式。

大量小文件

待展开:

  • 目录遍历、变更检测、元数据索引、对象查找、网络请求与文件展开的成本。
  • 文件监听、缓存、批量请求、按需检出和虚拟文件系统。
  • 总字节数接近而文件数量不同的实验;分别测量 status、传输与 checkout,区分冷缓存和热缓存。

克隆范围与工作目录范围

待展开:

  • 完整克隆、shallow clone、partial clone 与 sparse checkout。
  • 历史深度、对象可用性、路径选择和文件展开的区别。
  • 历史查询、diff、merge 与离线操作在不同配置下的成本。

超大文件与分块

待展开:

  • Git LFS 的指针、内容身份、外部存储、上传与旧版本恢复。
  • 整文件去重、固定分块和内容定义分块;局部修改、插入和重新编码对复用的影响。
  • Xet 的分块存储与传输,以及客户端、服务端和托管环境要求。
  • 分别测量存储量、上传量、下载量与重建成本。

数据版本与内容保留

待展开:

  • DVC 中代码、数据、配置和产物的版本对应;恢复同一个实验状态。
  • git-annex 的位置记录、按需获取、离线介质与副本策略。
  • Oxen 的数据仓库、数据差异与分支;lakeFS 的对象存储版本元数据、分支与发布。
  • 历史数据保留、可达性、垃圾回收与缺失对象;版本记录与备份的区别。
  • 固定版本、修改数据和恢复旧状态的实验,并记录实际复制的数据量。

客户端与服务端架构

待展开:

  • 内容存储、历史查询、diff、merge、验证和工作目录生成分别在哪一端执行。
  • Piper/CitC、Mononoke/EdenFS 和 Scion 的公开架构:权威存储、缓存、工作区与按需获取。
  • 局部检出、历史查询和提交的数据路径图。
  • 与 SVN、Perforce 对照:共同需求、实现差异、权限、可用性、故障恢复和运维成本。
  • 标明资料年代、公开证据范围与可用产品边界。

多 Agent 协作

工作环境与任务状态

待展开:

  • 任务的起始版本、文件获取、执行过程与交付结果。
  • 共享目录、独立 worktree 和独立运行环境各自的隔离范围。
  • 依赖、生成文件、缓存、进程和外部服务的共享关系。
  • 按任务获取文件、复用只读内容,以及任务、提交和验证记录的关联。

整合、验证与恢复

待展开:

  • 两个 Agent 各自测试通过、组合后失败的例子。
  • 对具体整合版本进行验证;主分支并发更新、整合顺序与重新验证。
  • 工作进展、评审、接纳和部署的不同状态,以及权限和人工检查的位置。
  • 中断、超时、重试、重复交付、放弃任务和回滚时的状态保留与清理。

设计对照与适用场景

待展开:用数据模型、工作流、文件存储、同步方式、服务端职责和执行隔离比较各系统。分别讨论普通代码仓库、数据密集项目和多 Agent 工作负载中的约束、成本与适用条件;这里只归纳前文已解释和验证的机制。

资料入口

已展开内容的来源标在正文中。以下资料也用于后续章节;待展开部分的具体机制与命令仍需核对。

Cite this post

@misc{pu2026csnotesversioncontroldesign,
  author = {Pu, Fanyi and {GPT-6 Astra}},
  title  = {Version Control},
  year   = {2026},
  month  = {10},
  url    = {https://pufanyi.com/blog/cs/notes/version-control-design}
}