Git bisect把自动测试接入二分定位的实现方法

当一个回归藏在几十个提交之间，逐个 checkout 再手工点测试既慢又容易把结论记错。Git bisect 可以把提交范围不断折半；再接入一个只返回退出码的自动测试脚本，Git 就能循环判断每个候选提交，最后定位首个异常提交。本文只处理 good、bad、skip 判定脚本，不展开具体项目的测试框架配置。

官方地址：https://git-scm.com/docs/git-bisect

先准备一个只负责判定的测试脚本

打开 Git 图形客户端的“仓库文件”或“工作区设置”，确认仓库干净；然后从底部的“终端 / Terminal”面板新建脚本。脚本最好放在仓库外，避免二分 checkout 时被切换的文件覆盖。下面用一个可替换的测试入口演示退出码约定，run-regression-test 代表项目自己的构建和测试命令。

#!/bin/sh
# 先构建当前提交；构建失败通常不能直接说明回归，返回 125 让 bisect 跳过。
run-regression-test --build || exit 125

# 测试通过返回 0，断言失败返回 1 到 124。
run-regression-test --case checkout-regression
status=$?
if [ "$status" -eq 0 ]; then
  exit 0
fi
exit 1

脚本的关键不是命令名称，而是退出码稳定。Git 官方约定 0 是 good/old，1 到 127（不含 125）是 bad/new，125 专门表示无法测试并跳过当前提交；其他退出码会中止流程。先在当前提交上从“终端面板 → 脚本文件 → 运行”执行一次，看到明确的返回状态后再进入二分。

在集成终端建立 good 和 bad 的范围

在 Git 客户端中沿着“仓库窗口 → 底部终端 → 当前工作区”打开命令行。先确认当前提交确实异常，再指定一个已知正常的基线。例如 HEAD 是 bad，v1.2.0 是 good：

# 清理上一次可能残留的二分状态，避免旧边界影响本轮。
git bisect reset

# 创建二分会话，并声明当前版本异常、旧版本正常。
git bisect start HEAD v1.2.0 --

# 查看 Git 当前挑选的候选提交和预计轮数。
git status
git bisect log

成功后终端通常会显示类似“Bisecting: … revisions left to test”的提示。此时不要在图形客户端里随意切换分支；每次由 Git 选出的候选提交都必须交给同一个判定脚本，否则二分前提会被破坏。

用 git bisect run 让测试自动循环

回到“终端 → 仓库根目录”，执行脚本。若脚本不在当前仓库，使用绝对路径或客户端允许的固定工具目录；命令本身不要把测试结果写死。

# 让 Git 在每个候选提交运行同一个判定脚本。
git bisect run /opt/tools/run-regression-test.sh

# 二分结束后查看 Git 认定的首个异常提交。
git show --stat refs/bisect/bad

每轮运行后，Git 会根据退出码选择下一半提交：0 继续把候选推向更早的边界，1 到 124 把当前提交视为 bad，125 跳过当前提交。如果构建环境缺失或测试数据不完整，必须返回 125，而不是把“无法测试”误报为 bad。图形客户端的“提交历史”面板可以用来查看当前候选，但不要把面板上的视觉状态当成测试结果，真正的判定来源仍是脚本退出码。

保存日志、修正误判并退出二分会话

看到首个异常提交后，先在“终端 → 二分记录”执行 git bisect log，把判定过程保存到项目外的记录文件。若发现某一轮误标，修正日志后 reset，再 replay 让 Git 重建边界：

# 保存本轮 good/bad/skip 记录，便于审阅或交接。
git bisect log > /tmp/bisect-session.log

# 只有确认记录需要修正时，才重放修正后的日志。
git bisect reset
git bisect replay /tmp/bisect-session.log

# 复核完成后退出二分，回到启动前的分支位置。
git bisect reset

最后在图形客户端检查“当前分支 / HEAD”是否回到二分前位置，再打开提交历史确认目标提交已被记录。若希望保留现场分析，可先用 git show refs/bisect/bad 导出变更，再 reset；不要把 refs/bisect/bad 当作永久分支。

常见问题：自动判定为什么会中断

脚本返回 125 会不会把提交判成 bad？

不会。125 是 Git bisect run 的特殊跳过码，表示当前提交无法测试；但如果相邻提交也被跳过，Git 可能只能给出一个范围，不能保证精确到单个首坏提交。

为什么测试脚本明明失败，二分却没有继续？

检查脚本是否返回了 126、127 或 255 等其他退出码，也检查构建命令是否提前退出。只有 1 到 124（不含 125）会被当作 bad，其余值可能让流程中止。

二分结束后工作区为什么不是原来的版本？

二分过程中 Git 会反复切换候选提交。完成定位后执行 git bisect reset，它默认回到 git bisect start 前的提交。

最终确认清单

这样接入后，自动测试负责给出稳定的事实信号，Git bisect 负责缩小提交范围。真正需要人工判断的只剩下边界选择、无法测试的提交和最终修复方案。