Git Bisect:找到引入错误的提交
一个功能昨天正常工作,但今天失效。学习如何使用 Git bisect 精确定位导致回归的提交,自动测试修订,并安全地调查结果。
Git Bisect:找出引入 Bug 的提交
某个网站上周还能正常工作。而今天,某个结账计算出现了错误,某个 JavaScript 组件不再响应,或者某个 PHP 接口返回了意外的数据。
你知道这个 Bug 是在 Git 历史中的某个地方出现的,但自从上一个可正常工作的版本以来,仓库里已经有了几十甚至上百个提交。逐个打开每个提交并阅读每处差异,很少是最快的解决方案。
Git 内置了一个专为此类情况设计的工具:git bisect。它不再检查每一个提交,而是使用二分查找来定位首次引入该问题的修订版本。只要有一个可靠的测试,你就能把调查过程自动化。
在本教程中,你将创建一个小型 PHP 项目,故意引入一个回归(regression),用 Git bisect 定位它,并学会如何将同样的技术应用到真实的项目中。
1. Git bisect 的工作原理
设想你的应用在提交 A 处能正常工作,但在提交 H 处失效。Git bisect 需要两个参考点:一个好提交(good commit),即该功能确定能正常工作的位置,以及一个坏提交(bad commit),即该 Bug 确定存在的位置。
它会检出一个中间修订版本。你对它进行测试,报告它是否能正常工作,然后 Git 缩小剩余的搜索范围。对于大约 128 个候选提交,二分查找通常只需要大约七次测试,而不是检查全部 128 个,前提是该行为能够被一致地分类判断。
官方 Git 文档描述了这一过程及其局限性。
2. 创建一个可复现的 PHP 回归
我们将构建一个极小的价格计算函数。不需要框架、数据库、Composer 包或 Web 服务器。你需要安装 Git 和 PHP CLI,并且 Git 必须已配置好用于提交的作者姓名和电子邮件。
创建一个目录并初始化一个仓库:
mkdir git-bisect-demo
cd git-bisect-demo
git init
创建 price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
预期行为很直接:finalPrice(100, 20) 返回 80。
提交这个可正常工作的版本:
git add price.php
git commit -m "Add working price calculation"
接下来,创建一个不相关的改动:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
最后,通过修改 price.php 中的计算来引入一个 Bug:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
提交这个损坏的版本:
git add price.php
git commit -m "Refactor price calculation"
现在这个项目有三个提交,最后一个提交中有一个刻意的回归。
3. 手动查找回归
首先确认你的工作树是干净的:
git status --short
该命令应该不产生任何输出。如果你有未提交的工作,请在开始之前恰当地提交它或将其暂存(stash)。
现在启动 Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

在这里,HEAD 是损坏的修订版本,而 HEAD~2 指向第一个可正常工作的提交。Git 会检出中间的提交。
测试这个计算:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
如果输出是 80,将该修订版本标记为好:
git bisect good
如果输出是 120,将其标记为坏:
git bisect bad
Git 会继续选择提交,直到确定第一个坏的修订版本。在这个三提交的演示中,只需测试一个中间修订版本。
完成后,恢复你原来的分支:
git bisect reset
在 bisect 期间,Git 通常会以分离 HEAD(detached HEAD)状态检出历史修订版本。git bisect reset 会让你返回到调查之前所使用的修订版本。
4. 用 git bisect run 自动化调查
当某个 Bug 需要肉眼检查时,手动测试很有用。但如果某种行为可以通过命令来检查,那么自动化会更高效。
Git 支持 git bisect run <command>。该命令使用退出码(exit code)来传达其结果:
| 退出码 | 含义 |
|---|---|
0 |
好的修订版本 |
1–124 或 126–127 |
坏的修订版本 |
125 |
无法测试此修订版本 |
| 其他值 | 中止调查 |
这些规则来自 官方 Git bisect 手册。
创建一个位于仓库之外的测试脚本,例如 ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
该脚本假定项目文件夹名为 git-bisect-demo,并且与 check-price.php 位于同一层级。请从项目文件夹内部运行这些命令:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git 会在选定的历史修订版本上运行测试,直到确定第一个坏提交。由于测试脚本位于仓库之外,检出较旧的修订版本不会将其删除。
对于真实项目,请使用一个稳定的测试命令,或者一个能够与被调查的历史修订版本协同工作的外部测试脚本。
5. 将技术应用到真实的 Web 项目
同样的工作流程适用于 WordPress 插件、Joomla 扩展、JavaScript 应用或 PHP 库。
假设某个结账功能在最新版本中损坏了,但它在 v1.4.0 版本中是可用的。首先验证该版本确实是好的,然后开始:
git bisect start HEAD v1.4.0
如果项目有一个能在选定修订版本范围内正常运行的 PHPUnit 测试,你可以手动运行它:
vendor/bin/phpunit tests/CheckoutTest.php
每次测试后,报告 git bisect good 或 git bisect bad。
当测试被可靠地自动化之后:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
历史提交可能需要不同的 PHP 版本、依赖项、数据库架构(schema)或构建工具。因环境不兼容而导致测试失败,并不一定表明存在该回归。请确保你的测试环境能够重现相关的历史版本。

6. 如果某个旧提交无法被测试怎么办?
有时某个历史修订版本会因为一个无关的原因而无法构建。不要自动将其标记为坏。
使用:
git bisect skip
Git 会尝试另一个候选提交。对于自动化测试,退出码 125 会告诉 Git 跳过该修订版本。
跳过太多提交会降低精确度。如果一个无法测试的提交正好紧邻该回归,Git 可能会报告多个可能的罪魁祸首,而不是一个确切的提交。
一个不错的长期做法是:维护可复现的开发环境、锁定依赖项版本,并让关键的回归测试独立于无关的基础设施。
7. 检查引入 Bug 的提交
一旦 Git 确定了第一个坏提交,就检查它:
git show <commit-hash>
要查看哪些文件发生了改动:
git show --stat <commit-hash>
要检查某个特定文件:
git show <commit-hash> -- price.php
第一个坏提交不一定是该 Bug 的唯一原因。 一个提交可能会暴露一个此前隐藏的问题、与另一个改动产生交互,或者依赖于某个此后已发生变化的服务。
使用所确定的提交来调查根本原因,而不是把它当作该提交中每一行都必然有误的自动证明。
8. 常见问题与解决方案
Bug 出现得不一致
如果一个测试在同一个修订版本上有时通过、有时失败,那么 bisect 的结果就变得不可靠。多次运行该测试,尽可能移除对时间的依赖,并控制外部输入。重复测试能提高可信度,但会增加调查时间。
测试在每个历史修订版本上都失败
确认你已知的好提交确实是好的。单独检出该修订版本,在开始一次新的 bisect 会话之前先运行测试。如果它在那里也失败,那么你的测试或环境可能有误。
Git 拒绝切换修订版本
未提交的改动可能会阻止检出。检查 git status 并在重新启动之前保留你的改动。避免诸如 git reset --hard 之类的破坏性命令,除非你完全清楚它们会丢弃什么。
历史中包含大量合并提交
对于复杂的仓库,Git 支持:
git bisect start --first-parent HEAD v1.4.0
这会遵循 first-parent(第一父级)历史,并有助于调查通过合并引入的回归。它会改变被视为考虑对象的提交,因此它并不是普通 bisect 的通用替代品。
Bug 依赖于生产数据
绝不要针对一个在线的生产数据库运行历史应用代码。使用一个带有经过脱敏处理的测试数据(fixture)和可复现架构的隔离测试环境。较旧的修订版本可能包含与生产环境不兼容的迁移或假设。
9. 一份实用的调试清单
- 确认该 Bug 是可复现的。
- 确定一个已知可工作的修订版本和一个已知会失败的修订版本。
- 保留未提交的工作。
- 定义一个具有明确通过/失败结果的可靠测试。
- 让外部服务和测试数据保持一致。
- 对于确实无法测试的修订版本,使用
git bisect skip。 - 检查所确定的提交并核实根本原因。
- 以
git bisect reset收尾。
结论
Git bisect 把一项不确定的调试任务变成了一次结构化的调查。你不必再猜测最近哪个改动破坏了应用,而是确定一个可工作的修订版本、一个损坏的修订版本,然后让 Git 逐步缩小历史范围。
当与自动化测试结合时,这项技术会变得格外强大。隐藏在上百个提交之间的某个回归,往往只需 handful 次的检查就能被定位。
对于维护长期存在的 PHP 项目、WordPress 插件、Joomla 扩展或 JavaScript 应用的开发者来说,除了日常的建分支和合并之外,git bisect 是最有用的 Git 命令之一。