git bisect 找到没有阅读500行日志的故障提交

你在这两周内推送了50个提交。其中某个时刻，某个东西出了问题。三周前还能通过的测试现在失败了。 git log --oneline 显示了你不想读的200行内容。

你可以选择：盯着差异看直到眼睛流血， git checkout 手动测试随机提交，或者使用自2007年起就存在于git中的工具，它随每个安装包一同提供。

git bisect 在你的提交历史中进行二分查找。你标记一个提交为故障，一个为正常，它会检出中间的提交——每次将搜索空间减半。在500个提交中找到故障点大约需要9步。大多数开发者从未使用过它。

怎么运行的

整个工作流只需三个命令开始：

git bisect start
git bisect bad                 # current state is broken
git bisect good v2.4.0         # last known-good tag or commit hash

Git检出两个点之间的中间提交。你测试该问题是否存在，然后反馈结果：

git bisect good   # bug is NOT present here
# or
git bisect bad    # bug IS present here

Git将范围减半，并选择下一个中点。重复直到它告诉你 abc1234 is the first bad commit。完成时：

git bisect reset  # returns you to your original branch

没有特殊标志，没有配置，没有插件。适用于任何仓库，适用于你可能安装的任何版本的git。

一次真实的二分查找会话（带注释）

这里是一个完整会话。一个原本返回正确JSON的函数在最近重构后开始返回null——最近提交中没有明显的罪魁祸首：

$ git bisect start
$ git bisect bad HEAD              # current commit is broken
$ git bisect good 3f8a12b          # commit from 2 weeks ago, worked fine

Bisecting: 24 revisions left to test after this (roughly 5 steps)
[c9e41f0] Refactor: extract auth middleware

$ npm test -- --grep "parseResponse"   # ← run your check here
# FAIL
$ git bisect bad

Bisecting: 12 revisions left to test after this (roughly 4 steps)
[a77b2d1] Fix: update retry logic in fetch wrapper

$ npm test -- --grep "parseResponse"
# PASS
$ git bisect good

Bisecting: 6 revisions left to test after this (roughly 3 steps)
[91e0bc3] Refactor: consolidate response handlers

$ npm test -- --grep "parseResponse"
# FAIL
$ git bisect bad

Bisecting: 2 revisions left to test after this (roughly 2 steps)
[b44c19f] Chore: remove deprecated serialization helpers

$ npm test -- --grep "parseResponse"
# FAIL
$ git bisect bad

Bisecting: 1 revision left to test after this (roughly 1 step)
[8d3e77a] Fix: normalize response envelope for new API version

$ npm test -- --grep "parseResponse"
# PASS
$ git bisect good

91e0bc3e1f4d is the first bad commit
commit 91e0bc3e1f4d
Author: Dev <dev@example.com>
Date:   Mon Apr 14 11:23:07 2026

    Refactor: consolidate response handlers

 src/http/response.js | 14 +++---

$ git bisect reset   # ← always do this when done

在50个提交的范围内仅用了5步。那个“合并响应处理器”的提交悄悄移除了一个序列化调用，而下游的某个部分正依赖于它。没有使用二分查找，你可能需要花一小时阅读差异。

自动化操作

如果你能将检查表达为脚本——正常退出码为0，异常为非零——git bisect可以完全自动运行：

git bisect start
git bisect bad HEAD
git bisect good v2.4.0
git bisect run npm test -- --grep "parseResponse"

Git检出每个中点，运行脚本，并报告第一个故障提交。对于运行时间在10秒以内的测试，这快到可以离开并回来得到答案。

运行脚本的退出码语义：

• 0 — 提交正常
• 1–124 — 提交异常
• 125 — 跳过此提交（构建失败，无法测试）

使用 125 当提交无法编译或在该点测试基础设施损坏时——bisect会跳过它并移动到下一个候选提交。

当二分查找胜过git blame时

git blame 告诉你谁最近修改了某一行。当你已经知道哪一行出错时有用。 git bisect 用于当你不知道时——当症状是行为性的，而原因可能出现在任何地方。

使用二分查找的情况：

• 你可以重现回归问题，但无法追溯到特定文件
• 生产行为发生了变化，但近期历史中没有明显的嫌疑者
• "在v2.3版本中可以工作，v2.5版本中出错"，中间有80多个提交
• 一个测试在某个特定日期前后开始持续失败

在二分查找过程中比较两个提交的输出时，将两者粘贴到 文本差异工具中 通常比在终端中阅读统一差异更快——特别是当输出是JSON或序列化对象时。

常见陷阱

别忘了 git bisect reset. 二分查找会检出处于脱离HEAD状态的提交。如果你在会话中途切换分支而没有重置，二分查找状态将变得过时，你可能会感到困惑。找到答案后也一定要重置，永远不要忽略这一点。

合并提交可能会扭曲范围。 如果你的范围包括一个长期存在的功能分支，该分支已被合并，二分查找可能会意外地落在该分支的提交中，顺序不明显。先运行 git log --oneline --no-merges good..bad 来了解范围内的内容。

测试可重现性至关重要。 如果你的检查不稳定——对时间敏感、环境依赖，或调用外部服务——二分查找将给出错误结果。在自动化之前，务必确保测试是确定性的。

二分查找确定的提交是行为发生变化的点，不一定是bug所在的位置。 有时一个正确的重构暴露了其他地方的预先存在的假设。请将结果视为“从这里开始阅读”，而不是“撤销这个提交就完事了”。

如果你定期调试git历史， Git 备忘单 在IO Tools上，bisect、blame、log标志和reflog都集中在一页——下次遇到神秘问题时，值得收藏此页面。

你可能也会喜欢