科技行业

Git Bisect:找到引入错误的提交

Git Bisect: Find the Commit That Introduced a Bug

一个功能昨天正常工作,但今天失效。学习如何使用 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
Illustration of the article's main concept

在这里,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)或构建工具。因环境不兼容而导致测试失败,并不一定表明存在该回归。请确保你的测试环境能够重现相关的历史版本。

Technical workflow illustration

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 命令之一。