【Git 内部】index 暂存区：dircache v2 与扩展节

git status 比较的是工作区、索引与 HEAD 三处状态；git add 写入的是 .git/index，不是对象库。index 是二进制 dircache 文件，记录路径、元数据（stat）、对象 SHA 和冲突 stage。读不懂 index，就无法解释 merge 冲突时 git ls-files -u 的三行同名路径。

本文对照 gitformat-index 说明 v2 布局与常见扩展。冲突 stage 在 merge 场景的完整例子见 第 13 篇。

一、文件角色

index 不进入对象库；但条目里的 SHA 指向 blob 对象（git add 时创建）。

二、头部与魔数

xxd .git/index 前几行（Git 2.54.0，单文件仓库）：

00000000: 4449 5243 0000 0002 0000 0001 6a49 509e  DIRC........jIP.

其后是每个 index entry 和可选 extensions。

三、index entry 概要

每个条目（简化）包含：

• 路径名（NUL 结尾，8 字节对齐）
• ctime / mtime（stat 信息）
• 设备、inode、模式、uid、gid、文件大小
• SHA-1（20 字节）对象 ID
• flags：路径长度、stage（冲突时 1–3）、assume-unchanged 等

git ls-files -s 显示 stage 与 SHA：

100644 ce013625030ba8dba906f756967f9e9ca394464a 0   hello.txt

100644 为模式，0 为 stage（正常暂存）。

四、冲突 stage

merge 失败时，同一路径可出现三条：

100644 df967b96… 1  shared.txt
100644 c354fa8c… 2  shared.txt
100644 1de5a387… 3  shared.txt

磁盘上即 index 中三条独立 entry，同名不同 stage。

五、扩展节（extensions）

常见扩展（四字 tag + 数据）：

本实验仓库 index 末尾可见 TREE 扩展（xxd 中出现 TREE ASCII）。扩展可忽略解析仍能正常用 Git 操作——只有写工具时才需完整实现 gitformat-index。

六、index 与工作区一致性

index 存 stat 用于快速判断工作区是否修改（git status 先 stat 再可能读内容）。git update-index --assume-unchanged 等标志在 flags 里。这与对象库不变性正交：blob 一旦写入 objects，内容不因 index 改变。

七、本文边界

• 不实现完整 entry 解析器代码。
• v4 等新版本字段以官方文档为准，实验环境为 v2。

复现：

git add .
xxd .git/index | head -6
git ls-files -s

参考资料

• Git documentation, gitformat-index
• 实验环境：Git 2.54.0

系列索引：Git 内部结构 · 上篇：reflog · 下篇：pack 格式