git fsck 深度解析 Git 仓库的体检医生

git fsck（File System ChecK）是 Git 内置的仓库完整性验证工具。它通过遍历对象数据库，验证每一个对象的哈希值与内容是否一致，找出悬空对象、损坏数据和引用断裂等问题。理解 git fsck，本质上就是理解 Git 的对象存储模型。

---

一、Git 对象模型：理解 fsck 的前提

Git 的底层是一个内容寻址存储系统 ，所有数据以四种对象 类 型存储在 .git/objects/ 目录下：每个对象通过其内容的 SHA-1（或 SHA-256）哈希值寻址，存储在 .git/objects/<前2位>/<剩余38位> 路径下。git fsck 的核心工作就是重新计算每个对象的哈希值，与文件名比对，并验证所有引用链的连通性。

---

二、git fsck 的核心用法

基本执行

git fsck

典型输出示例：

Checking object directories: 100% (256/256), done.
Checking connectivity: done.
dangling blob   d670460b4b4aece5915caf5c68d12f560a9fe3e6
dangling commit a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
unreachable tree 7a3f9c2b1d4e8f0a6c5b3e2d1f4a7c9b2e5d8f0a

常用选项一览

选项	说明
--full	检查 pack 文件内的每个对象（默认只检查松散对象）
--strict	严格模式，对 committer/author 格式等进行额外检查
--unreachable	显示不可达对象（默认隐藏）
--dangling	显示悬空对象（默认开启）
--no-dangling	隐藏悬空对象，减少输出噪音
--root	显示根 commit（无父节点）
--tags	显示所有 tag 对象
--lost-found	将不可达对象写入 .git/lost-found/
--connectivity-only	只检查连通性，跳过对象内容校验（速度更快）
--progress	强制显示进度条

---

三、输出 信息 解读：三类问题的诊断

3.1 dangling（悬空对象）

dangling blob   d670460b4b4aece5915caf5c68d12f560a9fe3e6
dangling commit 7f3e1a9b...

成因：对象存在于对象数据库，但没有任何引用（branch、tag、HEAD）能"到达"它。常见场景：

• git commit --amend 后，旧 commit 变为悬空
• git reset --hard 后，被抛弃的提交变为悬空
• git stash drop 后的 stash commit
• git rebase 过程中被改写的提交

危害程度 ：⚠️ 低。悬空对象是正常现象，Git 的 gc 会定期清理它们（默认保留 90 天）。它们是数据恢复的来源，不要急于删除。

3.2 unreachable（不可达对象）

unreachable commit a1b2c3d4...
unreachable tree   9f8e7d6c...
unreachable blob   1a2b3c4d...

不可达对象与悬空对象的区别在于：不可达对象可能被其他不可达对象所引用 ，形成一个孤立的子图。dangling 是不可达对象中"最顶层"的那些（没有任何其他对象指向它们）。

3.3 missing（缺失对象）⚠️ 严重

error: object file .git/objects/ab/cd1234... is empty
error: sha1 mismatch ab/cd1234...
missing blob 1a2b3c4d...
broken link from tree 9f8e7d6c... to blob 1a2b3c4d...

这是真正的数据损坏信号：

• 某个对象文件为空或损坏
• SHA-1 校验不匹配（内容与文件名不符）
• 某个 tree/commit 引用了一个根本不存在的对象

危害程度：🚨 严重。需要立即处理，否则受影响的历史无法读取。

---

四、实战场景与恢复技巧

场景 1：找回"消失"的提交

# 查看所有悬空 commit
git fsck --lost-found

# Git 会把不可达对象写入 .git/lost-found/
ls .git/lost-found/commit/

# 检查某个悬空 commit 的内容
git show a1b2c3d4

# 确认有用后，创建新分支恢复
git branch recovery/lost-work a1b2c3d4

--lost-found 是最实用的恢复工具之一，配合 git reflog 可覆盖几乎所有"误操作"场景。

场景 2：排查对象损坏的根因

# 完整校验，包括 pack 文件
git fsck --full --strict

# 只验证连通性（大仓库快速扫描）
git fsck --connectivity-only

# 找出所有损坏对象后，尝试从远端修复
git fetch origin
git fsck --full  # 重新验证

场景 3：清理悬空对象

# 先用 fsck 确认悬空对象列表
git fsck --dangling

# 如果确认不需要恢复，运行 gc 清理
git gc --prune=now  # 立即清理所有不可达对象
# 或
git gc --prune=30.days.ago  # 清理 30 天前的

---

五、git fsck 的内部工作流程---

六、进阶：git fsck 与相关命令的协同

与 git reflog 配合

reflog 记录了 HEAD 的历史移动轨迹，是 fsck 的重要补充。当 fsck 发现悬空 commit 但你不确定它是什么时：

# 先查 reflog 按时间线找
git reflog --all

# 再用 fsck 的 --lost-found 找 reflog 未覆盖的
git fsck --lost-found

# 结合 git log 查看悬空提交的树结构
git log --graph --oneline a1b2c3d4

与 git cat-file 配合诊断

# 检查某个具体对象的类型和内容
git cat-file -t d670460b     # 输出: blob / commit / tree / tag
git cat-file -p d670460b     # 打印对象内容
git cat-file --batch-check < <(git fsck 2>&1 | grep dangling | awk '{print $3}')

与 git gc 的关系

git fsck ──[发现问题]──► 决策：恢复 or 清理
                              │
              ┌───────────────┴──────────────┐
              ▼                              ▼
     git branch <hash>              git gc --prune=now
     git cherry-pick <hash>         （清理确认无用的悬空对象）

fsck 是诊断工具，gc 是清理工具，二者互补，绝不能混淆。

---

七、在 CI/ CD 中集成 git fsck

在关键分支的推送钩子或 CI 流水线中运行 fsck，可以在损坏扩散前提前发现问题：

#!/bin/bash
# .git/hooks/pre-receive 或 CI 脚本

echo "Running git fsck integrity check..."

# 严格模式检查，任何损坏立即失败
if ! git fsck --full --strict --no-dangling 2>&1 | grep -E "^error:|^missing"; then
  echo "✓ Repository integrity OK"
  exit 0
else
  echo "✗ Integrity check failed! Check output above."
  exit 1
fi

对于超大型仓库，可以使用 --connectivity-only 降低 CI 时间消耗，仅在定期维护窗口执行 --full。

---

八、常见问题排查手册

Q：git fsck 报了很多 dangling blob，正常吗？

完全正常。每次 git add 一个文件再修改它，旧内容就变成悬空 blob。执行一次 git gc 即可清理（超过 gc.pruneExpire 配置的才会被清除）。

Q：发现 missing blob 怎么办？

# 1. 先确认哪些文件受影响
git ls-tree -r HEAD | grep <missing-sha>

# 2. 尝试从远端拉取
git fetch --all
git fsck --full  # 重新检查

# 3. 如果远端也没有，考虑从备份恢复
# 或用 git checkout -- <file> 用远端版本覆盖本地

Q：error: sha1 mismatch 是什么原因？

这通常是磁盘故障（坏道）、文件系统错误、或网络传输 中断 导致的对象文件损坏。建议立即检查磁盘健康状态（smartctl），并从完好的克隆或备份中恢复该对象文件。

Q：git fsck 会修改仓库吗？

除了 --lost-found 选项会向 .git/lost-found/ 写入文件外，git fsck 是完全只读的，可以放心在生产仓库上执行。

---

九、总结

git fsck 是 Git 仓库健康管理的核心工具，其设计哲学与 Git 的内容寻址存储模型高度统一------哈希即验证，校验即自证。掌握它需要理解四个层面：

1. 对象模型：理解 commit / tree / blob / tag 的关系，才能读懂 fsck 的输出
2. 问题分类：区分 dangling（正常）、unreachable（可清理）、missing（危险）三种情况
3. 工具协同 ：与 git reflog、git cat-file、git gc 结合使用，形成完整的诊断-恢复-清理工作流
4. 预防意识 ：将 git fsck 集成进 CI 或定期维护脚本，做到防患于未然

对于任何长期维护的 Git 仓库，定期执行 git fsck --full 应当成为标准运维动作之一。