历史分析需要把问题描述转换成可以检查的证据：哪些文件发生变化，哪些提交可能相关，哪个版本首次不再满足预期。Git 提供的日志、补丁和二分搜索能够缩小范围，但仍需要明确的验证标准。
本文是 Git 系列第五篇。前四节围绕任务统计程序的回归问题展开，后两节介绍交付与维护工具，可按需查阅。建议已经掌握基础操作；若要修改或恢复历史，应先参考历史重写与撤销恢复。
1. 故障分析流程
复现条件
“统计结果不对”还不足以开始排查。应先固定输入、预期结果、实际结果和运行环境。例如，两项任务中只有一项标记 [x]，预期完成数为 1，当前程序却返回 2。这一条件比“程序能否启动”更适合作为回归判据。
排查顺序通常是：确认当前未提交差异，检查相关文件的历史，定位候选提交，再用一致的测试验证。切换旧版本前，应提交或另行保存当前工作；也可建立独立 worktree，避免干扰正在进行的开发。
练习历史
本例需要 Python 3。在新的 git-analysis-lab 目录中初始化仓库并配置练习身份：
mkdir git-analysis-lab
cd git-analysis-lab
git init -b main
git config user.name "Practice User"
git config user.email "practice@example.com"
创建 count_tasks.py：
def count_completed(text):
return sum(line.startswith("[x] ") for line in text.splitlines())
if __name__ == "__main__":
sample = "[x] Read Git basics\n[ ] Practice branching\n"
print(count_completed(sample))
提交正常版本并标记起点：
git add count_tasks.py
git commit -m "feat: count completed tasks"
git tag lab-good
创建 README，写入 Task counter practice 并单独提交为 docs: describe counter。然后将函数的返回语句故意改成下面一行，其余代码不变：
return len(text.splitlines())
git add count_tasks.py
git commit -m "refactor: simplify task counting"
再向 README 分别增加 Usage: python count_tasks.py 和 Expected completed count: 1，每增加一行就单独提交一次，说明分别为 docs: add usage、docs: clarify expected result。最后执行 git tag lab-bad。
现在有五个线性提交：第一、二个版本正常，第三个引入错误，第四、五个只改文档。运行 python count_tasks.py，最新版本应输出 2，这就是后续要定位的回归。
2. 历史检索与差异比较
日志筛选
git log --oneline --decorate
git log --graph --oneline --decorate --all
git log -p -- count_tasks.py
git show lab-good:count_tasks.py
第一条适合浏览说明，图形视图补充引用与分支关系，-p 展开补丁。最后一条直接读取历史文件，不切换工作区。若知道日期、作者或说明关键词，还可使用 --since、--author、--grep 过滤；过滤条件太多可能隐藏真正的原因，初期不宜过早缩小范围。
单个文件经历重命名时可尝试 git log --follow -- <file>。它不是任意复杂重命名的完整追踪器，仍需结合补丁核对。
提交集合与文件差异
在一张分叉图中理解范围最直观：
L1 ── L2 ← left
/
O ──
\
R1 ── R2 ← right
| 表达式 | 含义 |
|---|---|
git log left..right |
right 可达而 left 不可达的提交，即 R1、R2 |
git log left...right |
双方各自独有提交，即 L1、L2、R1、R2 |
git diff left right |
比较 L2 与 R2 的文件树 |
git diff left..right |
对 diff 而言同样比较两个端点 |
git diff left...right |
比较合并基点 O 到 R2 的变化 |
因此，日志范围与差异端点不能仅凭相同符号混用。审查功能分支通常关注它相对共同基点增加的变化；比较两个发布版本则直接比较两个端点。
在本例中执行 git diff lab-good lab-bad -- count_tasks.py，应能看到完成状态判断被替换为总行数统计。若项目很大，可先用 --stat 或 --name-only 确定文件范围。
3. 代码溯源与变更追踪
行级来源
git blame -L 1,3 count_tasks.py
git log -p -- count_tasks.py
blame 标出当前每行最后相关的提交，用于进入上下文。它显示的最近改动可能只是格式调整，不能据此直接认定根因，更不能等同于个人贡献或责任评价。必要时使用 -w 忽略空白差异，再阅读实际补丁与说明。
内容检索
git grep -n "count_completed"
git grep -n "count_completed" lab-good
git log -S"startswith" --oneline -- count_tasks.py
git log -G"return.*len" -p -- count_tasks.py
git grep 搜索当前已跟踪内容或指定版本。-S 查找指定字符串出现次数发生变化的提交，-G 则匹配补丁增删行中的正则表达式。若只是移动代码且字符串数量不变，-S 可能不会命中，此时应考虑 -G 或文件日志。
本例中的 startswith 被移除，-S 能提供候选；return.*len 则直接指向新的返回语句。搜索得到候选后仍需复现：同一次重构可能同时包含正确和错误修改，提交说明本身不是功能证据。
4. 回归问题二分定位
手动定位
当候选提交很多、单靠补丁难以判断时，可以让 Git 选择中间版本：
git status
git bisect start
git bisect bad lab-bad
git bisect good lab-good
Git 会检出一个待测试提交。运行 python count_tasks.py，结果为 1 时执行 git bisect good，结果为 2 时执行 git bisect bad；每次只执行与实际结果对应的一条。
Git 会继续选择候选，直到报告第一个坏提交。本例应定位到 refactor: simplify task counting。检查该提交补丁后，执行：
git bisect log
git bisect reset
reset 结束二分并回到开始时的位置。二分通常假定所考察区间对这个问题具有从正常到异常的可判定边界；若错误反复出现、环境随机变化或测试不稳定，结果可能不可靠。
不可测试版本
若某个旧提交依赖缺失，不能把“无法运行”直接判作目标故障。可以标记 git bisect skip，说明该点未知。跳过的版本过多，尤其接近边界时，Git 可能只能给出多个候选，不能声称已唯一定位。
自动测试
将下面的 check_tasks.py 放在仓库的父目录，避免检出旧提交时丢失测试脚本：
from pathlib import Path
import runpy
import sys
source = Path("count_tasks.py")
if not source.exists():
sys.exit(125)
try:
namespace = runpy.run_path(str(source))
except (ImportError, SyntaxError):
sys.exit(125)
counter = namespace.get("count_completed")
if not callable(counter):
sys.exit(125)
sample = "[x] Read Git basics\n[ ] Practice branching\n"
actual = counter(sample)
print(f"expected=1 actual={actual}")
sys.exit(0 if actual == 1 else 1)
在仓库根目录先运行一次，确认当前异常版本返回非零，再执行：
git bisect start lab-bad lab-good
git bisect run python ../check_tasks.py
git bisect reset
自动二分中，退出码 0 表示正常，1—127 中除 125 外表示异常，125 表示跳过；其他退出码会中止流程。因而脚本路径错误、依赖错误或命令不存在也可能被误判为异常，应先独立验证测试命令。Git 二分手册给出了退出状态约定。
本例脚本把部分环境问题归为不可测试，函数执行异常仍会导致非零退出。实际项目应根据故障定义设计判据，不能把所有异常都笼统标成目标回归。
定位结果验证
报告第一坏提交后，还应检查它及其前一个版本，并确认同一输入分别得到 2 和 1。修复时保留测试用例，让后续修改能够及时发现同类问题。对于复杂分支历史，可能需要同时查看父提交和合并结果，避免把整合问题误归结为单条源分支修改。
5. 补丁交换与仓库导出
交付形式
| 形式 | 主要内容 | 不包含或限制 |
|---|---|---|
| archive | 指定树的文件快照 | 无提交历史、无未提交修改 |
| diff/apply | 文件差异 | 不自动保留提交作者和说明 |
| format-patch/am | 补丁及作者、说明等信息 | 应用后提交标识通常不同 |
| bundle | 选定引用及其需要的 Git 对象 | 无工作区现场、无一般仓库配置 |
源码快照
git archive --format=zip --output=../task-source.zip lab-good
输出放在仓库外，避免把产物混入下一次提交。archive 适合交付某个版本的源码；导出范围还可能受属性规则影响，验收时应实际检查压缩包。子模块内容和 LFS 实体文件也不能一概假设会自动完整打包，需要单独验证。
差异补丁
git diff --binary --output=../counter.patch lab-good lab-bad -- count_tasks.py
git apply --check ../counter.patch
生成补丁可在当前仓库执行，应用检查则应在处于匹配基线的接收目录执行，例如另一份检出 lab-good 的干净工作区。不要在已经含有相同改动的 lab-bad 上照抄应用。检查通过后，使用 git apply ../counter.patch，再阅读差异、测试和提交。
这里使用 Git 自身的 --output，避免旧版 PowerShell 重定向改变补丁编码。--binary 允许补丁表示二进制差异，但接收方仍需确认路径与基线。
提交补丁与离线仓库
git format-patch -1 <commit> -o ../patches
在接收方匹配的工作区执行 git am <patch-file>。它会创建提交；发生冲突时，编辑并暂存后使用 git am --continue，放弃使用 git am --abort。这与只修改文件的 apply 不同。
需要传输历史时可以创建 bundle：
git bundle create ../task-history.bundle --all
git bundle verify ../task-history.bundle
git clone ../task-history.bundle ../task-history-copy
--all 选择仓库的全部引用范围，但不是整个 .git 目录的原样备份，不包含未提交文件、配置和钩子，也不能保证包含仅在 reflog 中可达的旧对象。增量 bundle 还可能要求接收方已有前置对象，应阅读 verify 的结果。克隆成功后核对分支、标签和文件，再认定交付完成。
6. 扩展功能与仓库维护
子模块管理
子模块适合在父项目中固定另一个 Git 仓库的版本。父仓库记录子仓库提交标识与相关配置，不会自动追随其最新代码。
git clone --recurse-submodules <url>
git submodule update --init --recursive
这两行分别适用于首次递归克隆和补齐已有克隆；不要求连续执行。更新依赖时，应先在子模块中选择并验证目标提交，再回父仓库暂存子模块路径和提交引用变化。发布父仓库前，必须保证目标子提交已推送且协作者有权访问，否则他人无法完整检出项目。
按需获取
| 工具 | 减少的主要范围 | 注意事项 |
|---|---|---|
浅克隆 --depth 1 |
提交历史深度 | 溯源与合并判断可能受限 |
部分克隆 --filter=blob:none |
初始下载的文件内容对象 | 需要服务端支持，后续可能联网取回 |
| 稀疏检出 | 工作区展开的目录 | 不等同于删除仓库中的文件或历史 |
已有浅克隆可通过 git fetch --unshallow 补全历史。大型仓库希望只处理部分目录时，可在支持过滤的服务端使用：
git clone --filter=blob:none --sparse <url> project-subset
cd project-subset
git sparse-checkout set src docs
目录名称应换成项目实际路径。cone 模式还会保留部分顶层及祖先目录文件，不能理解成只留下两个孤立目录。回到完整检出可用 git sparse-checkout disable，并预留磁盘与下载时间。
大文件管理
Git LFS 是独立扩展，用指针文件引用另外存储的大文件内容。环境已安装 LFS 且托管端支持时，最小入口为：
git lfs install
git lfs track "*.psd"
git add .gitattributes
随后正常添加匹配文件并检查 git lfs ls-files。跟踪规则和 .gitattributes 应随项目提交，协作者也需要可用的 LFS 环境与存储权限。新规则不会自动迁移已有历史；历史迁移会涉及重写和重新分发，应另行制定方案。额度与文件限制以实际托管平台为准。
清理与完整性
git clean -nd
git clean -di
前者预览未跟踪文件和目录，后者交互选择。只有确认预览范围可以删除时，才考虑实际清理；-x 还会包含被忽略文件。Git 从未保存过的文件被删除后，不能依赖 reflog 找回。
仓库体积和对象状态可先只读检查：
git count-objects -vH
git fsck
悬空对象提示不必然代表损坏，它可能来自正常的历史改写。真正缺失或损坏的对象需要进一步核对备份与其他克隆。Git 通常会自动维护对象，无需频繁手工 gc；正在尝试恢复不可达提交时，尤其不应先执行激进清理。
命令速查
| 目标 | 命令 |
|---|---|
| 文件补丁历史 | git log -p -- <file> |
| 历史文件内容 | git show <commit>:<path> |
| 行级来源 | git blame -L 1,20 <file> |
| 字符串变化 | git log -S"text" -- <file> |
| 补丁模式搜索 | git log -G"pattern" -- <file> |
| 结束二分 | git bisect reset |
| 清理预览 | git clean -nd |
实践练习
完成五次提交的排查案例，分别用 log -S 与 bisect 定位错误，记录两种方式提供的证据。将正常版本导出为 ZIP，再创建 bundle 并克隆验证。验收时解释：为何 ZIP 能交付源码却无法供他人继续追查全部历史，为什么 bundle 仍不是未提交工作的备份。
参考资料
- git-log、git-diff、git-blame
- git-archive、git-bundle、git-format-patch
- git-submodule、git-sparse-checkout
- Git LFS 项目、git-clean、git-fsck
系列导航：第五篇 / 共五篇 · 上一篇：历史重写与撤销恢复 · 系列导读 · 命令速查