Git bisect 实用教程：快速定位引入 Bug 的提交

前言

开发项目时，有时会遇到比较难排查的问题：上周某个功能还能正常使用，这周突然出错了，但最近已经合并了几十次提交，很难确定是哪次修改引起的。

如果逐个查看提交记录或者手动回退版本，排查起来比较耗时。

Git 自带的 bisect 命令可以通过二分查找，逐步缩小问题范围，最终定位最早引入 Bug 的提交。

一、git bisect 的基本原理

假设一个项目最近有 100 次提交，最新版本存在 Bug，而较早的某个版本可以正常运行。

最直接的排查方式是从最新版本往前逐个测试，最坏可能需要检查很多次。

git bisect 则会先选择中间的提交，让我们判断这个版本有没有问题：

• 如果功能正常，说明问题出现在更晚的提交中。
• 如果功能异常，说明问题在这个提交或更早的时候已经存在。

Git 会根据测试结果继续缩小搜索范围。

对于大约 100 个线性提交，理想情况下只需要进行约 7 次测试，就能定位问题所在的提交。

二、开始之前先确定两个版本

使用 bisect 需要先知道：

1. 一个确定存在问题的版本，称为 bad。
2. 一个确定功能正常的版本，称为 good。

例如，当前 HEAD 已经出现 Bug，而之前发布的 v1.2.0 版本正常。

首先查看工作区状态：

git status

最好在工作区干净的情况下操作，因为 bisect 会不断检出不同的历史提交。如果还有未提交的修改，建议先提交或妥善保存。

接着开始二分查找：

git bisect start
git bisect bad HEAD
git bisect good v1.2.0

这里的 v1.2.0 只是示例，需要替换成自己项目中实际存在、并且确认没有问题的提交或标签。

执行后，Git 会自动检出搜索区间中间的一个提交。

三、手动判断每个版本

Git 切换到一个历史提交后，就可以测试原来出现问题的功能。

例如，某个项目最近出现了登录失败的问题，可以在当前检出的版本中启动项目，检查登录流程是否正常。

如果功能正常，执行：

git bisect good

如果功能仍然异常，执行：

git bisect bad

每次执行后，Git 都会自动选择下一个需要测试的提交。

不断重复这个过程，直到输出类似：

abc1234 is the first bad commit

这里的提交哈希仅作为示例。

这表示 Git 已经根据前面的测试结果，定位到搜索范围内第一个出现问题的提交。

随后可以查看具体修改：

git show abc1234

需要注意，找到提交不代表已经找到真正的代码错误。还需要检查这次提交的修改内容，以及是否与当前问题有关。

四、遇到无法测试的提交怎么办？

实际开发中，历史版本不一定都能正常构建。

例如，某次提交恰好调整了依赖配置，导致旧版本在当前环境中无法启动。这时无法判断目标 Bug 是否存在。

不要把这种情况直接标记为 bad，否则可能误导二分查找。

可以执行：

git bisect skip

这样 Git 会跳过当前无法测试的提交，继续寻找其他候选版本。

不过，如果被跳过的提交恰好位于问题发生的边界附近，最终可能无法唯一确定是哪一次提交引入了问题。

因此，能正常测试时还是尽量给出明确的 good 或 bad 结果。

五、使用自动化测试

如果项目已经有自动化测试，bisect 还可以自动执行判断过程。

例如，一个 Node.js 项目可以通过下面的命令运行测试：

npm test

如果这条命令能稳定判断目标问题是否存在，就可以使用：

git bisect start HEAD v1.2.0
git bisect run npm test

Git 会在每次检出历史提交后自动执行测试，再根据退出码决定下一步。

这里需要了解几个退出码：

• 0：测试通过，标记为 good。
• 1～127（不包括 125）：测试失败，标记为 bad。
• 125：当前提交无法测试，跳过。
• 其他退出码：可能导致二分过程中止。

这里的关键是测试命令必须能准确判断正在排查的问题。

例如，只是某个登录功能出错，但整个项目还有其他不稳定测试，那么直接运行全部测试可能得到错误结论。最好针对目标 Bug 编写一个能够稳定复现的测试。

对于不同历史提交，测试依赖和构建方式也可能变化，需要注意环境兼容性。

六、如何退出 bisect？

二分查找期间，Git 会临时切换到不同的历史提交。

无论是已经找到问题，还是决定中途退出，最后都应该执行：

git bisect reset

这条命令会结束当前二分查找，并默认恢复到开始 bisect 前的检出位置。

它不会自动撤销已经提交到项目历史中的代码修改，也不是用于删除错误提交的命令。

如果希望查看这次二分查找的判断记录，可以在退出前执行：

git bisect log

这样可以检查之前标记了哪些 good 和 bad 提交。

七、几个实际使用中的注意事项

1. 确保问题能够稳定复现

如果同一个提交有时正常、有时异常，二分查找就可能得到错误结果。

对于网络偶发故障、并发问题等，最好先找到稳定的复现条件。

2. 不要把构建失败直接等同于目标 Bug

某个历史版本无法构建，可能只是依赖版本不兼容，不能据此认定它包含正在查找的问题。

3. 注意数据库和外部状态

如果测试需要修改数据库、执行迁移或者调用外部服务，切换历史提交并不意味着这些外部状态会自动恢复。

应尽量使用隔离的测试环境，避免旧版本测试影响实际业务数据。

4. 提交历史复杂时，搜索结果不一定完全唯一

对于存在大量合并提交、部分版本无法测试的项目，二分查找可能需要更多测试，或者只能给出若干候选提交。

找到结果后仍然需要结合代码变更进行确认。

总结

git bisect 特别适合解决“之前正常，现在出错，但不知道从哪次提交开始出问题”的情况。

日常使用时，只需要记住这几个命令：

git bisect start
git bisect bad HEAD
git bisect good v1.2.0

# 测试当前版本后选择其一
git bisect good
git bisect bad
git bisect skip

# 最后退出
git bisect reset

如果项目已经具备稳定的自动化测试，还可以通过 git bisect run 自动完成整个查找过程。

相比一条条检查提交记录，bisect 最大的优势就是能够快速缩小范围，把排查时间更多地用在真正可能引入问题的代码上。