如果你经历过“这个功能之前明明好好的怎么突然就不行了”的时刻那你一定明白对着git log一行行翻屏的绝望。眼见着复盘群里消息越刷越多你从最近一天的提交开始往旧里捋眼睛都快看瞎了还是想不出来到底是谁的提交埋了雷。Git Bisect二分查找就是为这种场景而生的Git 自动把你的可疑提交范围对半切开每测一次排除一半候选几百上千个提交的搜索空间十几步就能锁定引入问题的那个 commit。我这次就用一个模拟案例完整走一遍从手工标记到git bisect run自动化判定的流程把原理和实操技巧一次讲透。1. 二分查找理念与应用场景拆解1.1 从人肉排查到机器排除为什么要用二分先说一个非常扎心的排查场景。你的项目最近一个月合入了 200 个提交昨天线上接口突然超时。正常的排查路径是什么先看监控和日志锁定大概改动的模块然后git log --oneline找相关提交。如果运气好commit message 写得特别清楚一眼就能看到“优化了 XX 缓存”点进去一看缓存 key 写错了5 分钟搞定。可现实往往是改动不直接、消息含糊、重构和修复混在一起、动不动还有一个“Merge branch”占掉半屏。我以前遇到这种问题最笨的办法就是一个一个 checkout 历史提交重新构建复现一下不行再换下一个。说实话试到第二个第三个就开始烦躁了。为啥费劲因为这种线性排查完全没有利用提交之间的次序关系。你明明知道现在这个提交是坏的某个旧提交是好的中间这一长串提交里一定存在最早引入问题的那个边界提交。要找的是边界不是挨个翻。git bisect的核心思路就是把这个“找边界”的过程交给算法。它每次挑出候选区间的中间提交让你判断“这个中间提交是好是坏”然后根据你的回答排除掉一半提交。如此反复最终留下唯一一个提交就是“从好变坏”的转折点。这里最重要的前提是提交状态是单调变化的也就是说一旦某一个提交引入了问题从它往后一直到坏提交问题应该都存在。这个前提听起来苛刻但对大部分回归 bug 和性能回退都成立这也是为什么 bisect 在实际开发中这么好用。1.2 复杂度账本十几步定位 vs 几百次试探纠结二分到底省不省时间的人建议先看这张表。它对比的是候选提交数量、线性尝试的平均次数以及二分查找需要判定的次数候选提交数线性尝试平均次数二分尝试次数10541005071,0005001010,0005,00014二分的尝试次数约等于log2(N)N 每翻一倍只是多一次判定。这个收益在提交数量大的时候特别夸张一万个提交理论上人肉 checkout 要平均试五千次而 bisect 只需要十四次。哪怕每次判定要重新构建、跑测试耗掉五分钟十四次也就是一个多小时的事人肉翻可能要搭进去一整天。不过这里我要说句实话复杂度账只是理想情况。实际项目中每次判定可能不是“稳定复现”或“完全正常”两种干净结果还有构建环境问题、偶发测试失败、一半提交压根编译不过等情况。所以二分给出的不是“免罚金牌”而是把问题的规模实实在在降下来。只要你补上可靠的判定手段找到 bug 就只是时间问题。1.3 哪些问题适合 bisect哪些不适合适合用 bisect 的很典型回归 bug某功能之前正常现在挂了并且你能稳定复现。性能回退接口响应时间从 100ms 涨到 2s能通过压测或一段脚本判断好坏。测试红绿灯旧的测试用例原本全绿某天开始红了但不知道是哪次提交引入的。构建产物异常比如镜像尺寸暴涨、生成的文件出现不明差异。不适合的情况也不少。最典型的是整个项目一直没有好的版本bug 从一开始就存在没有 good 基线二分无从谈起。另一种是区间内状态忽好忽坏比如 bug 修过一次又在后面复发中间段的“好”和“坏”并不是单调分布的直接跑 bisect 可能会得出错误结论。这类场景我会在第四部分专门讲怎么处理。2. 手工二分流程全记录2.1 开始前的三个准备动作跑 bisect 之前我强烈建议先做三个准备动作能帮你少踩很多坑。第一确认当前工作区是干净的。git bisect会不断切换分支和提交如果工作区里有未提交的修改轻则冲突提示、重则把没保存的代码卷进候选提交里。我习惯在执行之前先git status看一眼有改动就 commit 或者 stash 起来。第二明确两个锚点一个已知坏的提交一个已知好的提交。坏的通常是当前 HEAD 或者线上出问题的那个版本好的可以是一个 tag、一个发布哈希或者你记忆里最后一个正常版本。很多人忽略的是bad 和 good 不要选得太近。如果两个提交之间只有两三个提交二分几下就结束了没错但也说明你对问题范围根本没缩小多少这时候更适合用git log -S这类工具直接找。第三想好“怎么判定好坏”。最理想的是有一条命令能输出明确的退出码0 代表好非 0 代表坏。如果没有现成的测试命令至少把复现步骤写在纸上人工判断起来才不会手忙脚乱。2.2 完整命令流程与状态信息解读标准的流程特别简单三条命令入场git bisect start git bisect bad HEAD git bisect good v1.2.0第一条start是进入二分模式后两条分别告诉 Git“当前是坏的”和“这个版本是好的”。Git 收到信息后会立刻自动切到中间那个提交然后给你一段提示类似这样Bisecting: 43 revisions left to test after this (roughly 6 steps)这句提示的意思是我还剩 43 个提交要排除理论上大约还要走 6 步。很多人第一次看到“6 steps”会以为要重复六次嫌麻烦但你仔细算算43 个提交如果不是二分平均要试二十多次这已经省太多了。接下来就是循环测试当前检出的这个提交根据结果告诉 Git。如果问题复现了说明这个提交是坏的执行git bisect bad如果问题没复现说明这个提交是好的执行git bisect good每次标记完Git 又会自动切到新的中间提交重新输出剩余次数。重复三四次之后你大概会看到这样的最终结果c3f2a1b9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4 is the first bad commit这句话就是整个流程的答案c3f2a1b这个提交是“从好变坏”的第一个提交bug 大概率就是它引入的。2.3 结束后的 reset 与工作区保护找到目标提交后千万别直接切走。当前仓库还停在 bisect 状态如果这时候直接git checkout master再做一些操作很容易把状态弄乱。正确做法是git bisect reset这条命令会把 HEAD 恢复到git bisect start之前的位置退出二分模式。工作区里有未提交改动的话也会保留不会因为检出中间提交而弄丢。还有一个很容易被忽视的细节在 bisect 过程中bisect检出的提交是一个“游离 HEAD”状态你可以在里面做任何验证但不要顺手在这里面 commit 代码。万一你在这个中间提交上提交了垃圾修改回到正常分支后还得费力处理。我的习惯是bisect 期间所有验证都只读不做任何写操作。3. git bisect run 自动化判定的脚本化实践3.1 自动化判定的核心退出码手工二分最大的问题是人容易不耐烦而且每次测试都要人在终端前守着。一旦判定规则可以写成命令就应该让 Git 自己跑。git bisect run就是干这个的。它的机制一句话概括你给 bisect 一条命令Git 自动在选中的提交上执行这条命令并根据命令的退出码来帮你做 good/bad 判断。退出码的语义需要严格记住退出码含义bisect 行为0提交是好的标记为 good继续搜索1~127提交是坏的标记为 bad继续缩小范围125无法判断跳过这个提交继续搜索128 及以上脚本或环境异常终止整个 bisect 流程注意125是个很讲究的码。它对应的是“当前提交没法判定好坏”的情况比如编译直接失败、测试环境连不上、缺少某个依赖文件。这种情况下如果把它当成 bad会污染搜索区间得出错误结论如果直接终止流程又太浪费。跳过是更合理的选择。3.2 一个可复用的判定脚本模板以 Node.js 项目为例我常用的判定脚本长这样#!/bin/bash # is-good.sh返回 0 表示提交正常返回非 0 表示提交有问题 # 先把构建跑通编译失败说明这个提交本身不完整跳过去 if ! npm run build --silent; then exit 125 fi # 跑一个能稳定复现 bug 的最小测试 node test/reproduce-bug.js这个脚本的逻辑很清晰先构建构建失败直接 125 跳过构建成功后跑复现脚本脚本退出码非 0 就说明 bug 存在脚本自然返回非 0bisect 会把它当成 bad。写脚本的时候有一个很关键的经验不要加set -e至少不能无脑加。因为set -e会让脚本在构建失败时直接退出但退出码可能被 shell 改写后面想控制 125 这个语义就费劲了。我更习惯用显式的if判断控制流程让每个分支的退出码都在自己掌控中。写好后执行命令就一行git bisect run bash is-good.shGit 会自己开始循环检出一个中间提交、执行脚本、看退出码、标记、继续。执行过程中的每一步进度都会打印在终端里。结束后会停留在最终定位到的“第一个坏提交”上然后你手动执行git bisect reset收尾。3.3 run 模式的注意事项与经验用 run 模式跑过几次后我给几个非常实用的建议。第一脚本一定要幂等。一个常见的反面教材是测试脚本依赖上一次跑出来的临时文件、端口、进程或者测试数据库状态被前一个提交污染了。第二个提交跑的时候结果就不准了bisect 立刻跑偏。我一般会要求脚本先清理自己的临时文件测试数据库也尽量用内存库或临时库确保每次执行都在干净状态里。第二正式跑之前一定要先手动验证脚本的准确性。最靠谱的做法是挑两个已知好和已知坏的提交手动 checkout 后分别执行一次判定脚本确认脚本对好提交返回 0、对坏提交返回非 0。这一步只需要几分钟但能防止脚本本身自带 bug 导致定位结果完全不可信。第三脚本里尽量避免写入仓库目录。有些测试会在运行时生成快照或者日志文件这些文件一旦留在工作区会污染下一次检出的状态。我的做法是全部写到/tmp或系统临时目录必要时在脚本开头清理上次遗留文件。git bisect run最适合的场景是那种判定逻辑非常明确的回归测试。如果你的 bug 需要人工观看页面、操作界面才能判断那确实不适合自动化继续用人工模式就好。4. 实战进阶大仓库、多分支与不稳定提交的处理4.1 直接指定 bad/good 区间标准流程是进入 bisect 状态后分别标 bad 和 good。其实还有一种更直接的方式在start这一步就把区间传进去git bisect start bad-commit-hash good-commit-hash这样等价于start之后立刻执行bad和good少敲两行命令。两个提交的位置没有严格要求Git 会自动把较新的当 bad、较旧的当 good 方向处理但为了可读性我还是习惯把坏的写在前面。当区间比较大的时候我还会额外看一眼这个区间里大概有多少个提交git log --oneline good..bad | wc -l这样能对“大概要跑几步”有个心理预期。如果区间里有几百个提交起步就要九到十步但如果你先用git log -S关键词把范围缩小到几十个提交可能四五步就出结果。4.2 遇到无法判定的提交skip 与 125开发中最常见的坑是中间某个历史提交因为依赖版本变化无法编译或者代码库结构还没成型测试脚本干脆跑不起来。这样的提交没有“好坏”可言硬判断只会污染二分结果。正确做法是人工模式下执行git bisect skip自动化模式下则让脚本返回 125。Git 会跳过这个提交然后继续在其他候选里做二分。即使中途跳过了几个只要剩下的提交仍然保持单调变化最后结论依然可靠。这里有个经验问题如果跳过太多bisect 最终可能给出一个“不精确”的结果甚至提示找不到明确边界。我遇到这种情况会先检查整个搜索区间是不是压根就没有连续的“好坏交界”。比如项目经历过一次大规模重构重构前后代码结构完全不同很多中间的 squash 提交没法独立构建这时候强行二分不现实。这种场景我会放弃全自动改用“先人工标出重构开始和结束的提交再分别对重构前后两个阶段做定位”。4.3 非单调变化的特殊场景我之前提到过二分查找成立的前提是提交状态单调。但现实中还有一种很磨人的情况这个 bug 在 A 提交引入B 提交修了一半C 提交又复发D 提交彻底修复然后 E 提交因为一次合并又把它带回来了。整套历史看起来就是“坏好坏好坏”反复横跳直接跑 bisect 很容易定位到错误的提交。怎么处理我的经验是分两步。先用git log -S或git log -G搜索和 bug 相关的关键词找到历史上最后一次修复它的提交把那个提交当作新的 good 起点把最后复发的那次提交之后的某个状态当作 bad 终点。这样就把一个“反复横跳”的问题重构成一个相对单调的子区间再跑 bisect 就靠谱得多。另一个思路是把判定脚本写得更“苛刻”一点让它在检测到任何轻微的问题迹象时都返回 bad。比如一个性能小回退你要判断的不是“能不能工作”而是“响应时间是否超过阈值”。这种严格判定能帮你打断“时好时坏”的幻觉让状态分布更接近单调。4.4 与 git log -S、git blame 配合定位git bisect不是万能的灵药它擅长的是“确定边界”。有些时候先用别的命令做粗筛能显著缩小 bisect 的搜索范围。如果你已经能大致猜到 bug 和某个字符串相关比如某个配置项丢了、某个方法名变了可以直接用git log -SconnectionTimeout --oneline -- src/main/resources这个命令会列出所有新增或删除过该字符串的提交。比如它告诉你这个字符串在两个提交里出现过变化那你可以直接看这两个提交是不是就是问题的根源或者至少把 bisect 的区间限定到这两个提交之间几步就能收尾。git blame也有它的价值但我要提醒一句blame 只告诉你某一行代码最后一次被谁改动那个提交不一定是引入 bug 的提交。项目经历过格式化、重构、文件移动之后blame 指向往往是最表面的那次改动真正的问题在更早的地方。这时候不要盲目信任 blame 的结果更应该用 bisect 从行为层面去验证。5. 常见问题与排查技巧速查5.1 高频问题速查表我整理了一份自己在实际使用中遇到的高频问题列表现象原因处理方式fatal: You are in the middle of a bisect之前进入 bisect 状态没有 reset执行git bisect reset退出bisect 过程中工作区冲突有未提交的修改或子模块状态不干净先git stash结束后再恢复结果定位到的提交看起来没问题判定脚本不稳定或区间状态非单调复查脚本用git bisect log导出重放bad 和 good 选得太近范围太小二分没有意义用git log -S或git log -G先扩大线索脚本返回 125 的提交太多历史提交无法独立构建考虑缩小区间或放弃全自动标记错了某个提交人工误判git bisect log查看过程用git bisect replay重放或直接 reset 重来5.2 误操作后的恢复手段很多人第一次被 bisect 卡住不是因为找 bug 难而是因为它把仓库状态搞成了一个“不知道自己在哪”的局面。比如自动切换提交后你发现当前 HEAD 指向一个奇怪的 hash想回 master 又怕丢东西。这时候记牢两句话不要慌git bisect reset可以解百忧。git bisect log也是被低估的命令。它会完整打印出你每一步标记了什么提交、标成 good 还是 bad。如果你发现自己中间误标了一两次但又不想从头开始可以把输出保存下来git bisect log bisect.log然后根据自己的判断手动编辑这个日志文件去掉错误的标记步骤再执行git bisect reset git bisect replay bisect.log就能按照修正后的步骤重新走一遍。当然大多数时候重新 start 成本更低误标一步也不至于导致整个定位无法挽回这个技巧属于锦上添花。5.3 我的几个独家调试习惯最后分享几个我自己长期使用后沉淀下来的调试习惯。接到回归 bug 的第一件事不是马上跑 git log而是先判断“这个 bug 是外部因素还是代码变更导致的”。如果是服务器环境变化、第三方接口超时、数据源问题跑 bisect 纯属浪费时间。我会先确认同一个代码版本在另一个环境能跑通再考虑是不是某次提交引入的。确认要跑 bisect 后我会先给当前状态打一个 tag 或者记住 hash。万一中途发现 bad 状态标错了至少有一个明确的重置锚点。发布流程健全的项目每次发布打 tag 这个习惯尤其重要——没有 tag会很难找到一个“确定正常”的 good 基线。判定脚本一定要提前打磨。我见过太多同事脚本里直接写“跑完整套测试套件”结果每次 bisect 跑半个多小时还因为套件里偶发挂掉的用例得出错误结论。我的原则是判定脚本只包含和这个 bug 相关的最小复现范围越小越稳定结果越可信。等脚本固定下来后面再遇到同类问题直接把参数换一换就能复用。用git bisect这几年我最大的体会是它最值钱的不是省下那几分钟而是逼着我把“出问题时到底什么状态”想清楚。想清楚之后定位 bug 从“碰运气”变成了“走流程”。以后如果你深夜被线上回归 bug 拉起来别慌先找好 good 和 bad写一条能稳定复现的判定命令剩下的交给 Git 的二分查找。相信我一旦用顺了你就真的回不去人肉翻 git log 的日子了。 
长河君 · 2026/10/9 3:28:36 · 阅读 1.2k Git Bisect二分查找：快速定位引入Bug的提交
如果你经历过“这个功能之前明明好好的怎么突然就不行了”的时刻那你一定明白对着git log一行行翻屏的绝望。眼见着复盘群里消息越刷越多你从最近一天的提交开始往旧里捋眼睛都快看瞎了还是想不出来到底是谁的提交埋了雷。Git Bisect二分查找就是为这种场景而生的Git 自动把你的可疑提交范围对半切开每测一次排除一半候选几百上千个提交的搜索空间十几步就能锁定引入问题的那个 commit。我这次就用一个模拟案例完整走一遍从手工标记到git bisect run自动化判定的流程把原理和实操技巧一次讲透。1. 二分查找理念与应用场景拆解1.1 从人肉排查到机器排除为什么要用二分先说一个非常扎心的排查场景。你的项目最近一个月合入了 200 个提交昨天线上接口突然超时。正常的排查路径是什么先看监控和日志锁定大概改动的模块然后git log --oneline找相关提交。如果运气好commit message 写得特别清楚一眼就能看到“优化了 XX 缓存”点进去一看缓存 key 写错了5 分钟搞定。可现实往往是改动不直接、消息含糊、重构和修复混在一起、动不动还有一个“Merge branch”占掉半屏。我以前遇到这种问题最笨的办法就是一个一个 checkout 历史提交重新构建复现一下不行再换下一个。说实话试到第二个第三个就开始烦躁了。为啥费劲因为这种线性排查完全没有利用提交之间的次序关系。你明明知道现在这个提交是坏的某个旧提交是好的中间这一长串提交里一定存在最早引入问题的那个边界提交。要找的是边界不是挨个翻。git bisect的核心思路就是把这个“找边界”的过程交给算法。它每次挑出候选区间的中间提交让你判断“这个中间提交是好是坏”然后根据你的回答排除掉一半提交。如此反复最终留下唯一一个提交就是“从好变坏”的转折点。这里最重要的前提是提交状态是单调变化的也就是说一旦某一个提交引入了问题从它往后一直到坏提交问题应该都存在。这个前提听起来苛刻但对大部分回归 bug 和性能回退都成立这也是为什么 bisect 在实际开发中这么好用。1.2 复杂度账本十几步定位 vs 几百次试探纠结二分到底省不省时间的人建议先看这张表。它对比的是候选提交数量、线性尝试的平均次数以及二分查找需要判定的次数候选提交数线性尝试平均次数二分尝试次数10541005071,0005001010,0005,00014二分的尝试次数约等于log2(N)N 每翻一倍只是多一次判定。这个收益在提交数量大的时候特别夸张一万个提交理论上人肉 checkout 要平均试五千次而 bisect 只需要十四次。哪怕每次判定要重新构建、跑测试耗掉五分钟十四次也就是一个多小时的事人肉翻可能要搭进去一整天。不过这里我要说句实话复杂度账只是理想情况。实际项目中每次判定可能不是“稳定复现”或“完全正常”两种干净结果还有构建环境问题、偶发测试失败、一半提交压根编译不过等情况。所以二分给出的不是“免罚金牌”而是把问题的规模实实在在降下来。只要你补上可靠的判定手段找到 bug 就只是时间问题。1.3 哪些问题适合 bisect哪些不适合适合用 bisect 的很典型回归 bug某功能之前正常现在挂了并且你能稳定复现。性能回退接口响应时间从 100ms 涨到 2s能通过压测或一段脚本判断好坏。测试红绿灯旧的测试用例原本全绿某天开始红了但不知道是哪次提交引入的。构建产物异常比如镜像尺寸暴涨、生成的文件出现不明差异。不适合的情况也不少。最典型的是整个项目一直没有好的版本bug 从一开始就存在没有 good 基线二分无从谈起。另一种是区间内状态忽好忽坏比如 bug 修过一次又在后面复发中间段的“好”和“坏”并不是单调分布的直接跑 bisect 可能会得出错误结论。这类场景我会在第四部分专门讲怎么处理。2. 手工二分流程全记录2.1 开始前的三个准备动作跑 bisect 之前我强烈建议先做三个准备动作能帮你少踩很多坑。第一确认当前工作区是干净的。git bisect会不断切换分支和提交如果工作区里有未提交的修改轻则冲突提示、重则把没保存的代码卷进候选提交里。我习惯在执行之前先git status看一眼有改动就 commit 或者 stash 起来。第二明确两个锚点一个已知坏的提交一个已知好的提交。坏的通常是当前 HEAD 或者线上出问题的那个版本好的可以是一个 tag、一个发布哈希或者你记忆里最后一个正常版本。很多人忽略的是bad 和 good 不要选得太近。如果两个提交之间只有两三个提交二分几下就结束了没错但也说明你对问题范围根本没缩小多少这时候更适合用git log -S这类工具直接找。第三想好“怎么判定好坏”。最理想的是有一条命令能输出明确的退出码0 代表好非 0 代表坏。如果没有现成的测试命令至少把复现步骤写在纸上人工判断起来才不会手忙脚乱。2.2 完整命令流程与状态信息解读标准的流程特别简单三条命令入场git bisect start git bisect bad HEAD git bisect good v1.2.0第一条start是进入二分模式后两条分别告诉 Git“当前是坏的”和“这个版本是好的”。Git 收到信息后会立刻自动切到中间那个提交然后给你一段提示类似这样Bisecting: 43 revisions left to test after this (roughly 6 steps)这句提示的意思是我还剩 43 个提交要排除理论上大约还要走 6 步。很多人第一次看到“6 steps”会以为要重复六次嫌麻烦但你仔细算算43 个提交如果不是二分平均要试二十多次这已经省太多了。接下来就是循环测试当前检出的这个提交根据结果告诉 Git。如果问题复现了说明这个提交是坏的执行git bisect bad如果问题没复现说明这个提交是好的执行git bisect good每次标记完Git 又会自动切到新的中间提交重新输出剩余次数。重复三四次之后你大概会看到这样的最终结果c3f2a1b9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4 is the first bad commit这句话就是整个流程的答案c3f2a1b这个提交是“从好变坏”的第一个提交bug 大概率就是它引入的。2.3 结束后的 reset 与工作区保护找到目标提交后千万别直接切走。当前仓库还停在 bisect 状态如果这时候直接git checkout master再做一些操作很容易把状态弄乱。正确做法是git bisect reset这条命令会把 HEAD 恢复到git bisect start之前的位置退出二分模式。工作区里有未提交改动的话也会保留不会因为检出中间提交而弄丢。还有一个很容易被忽视的细节在 bisect 过程中bisect检出的提交是一个“游离 HEAD”状态你可以在里面做任何验证但不要顺手在这里面 commit 代码。万一你在这个中间提交上提交了垃圾修改回到正常分支后还得费力处理。我的习惯是bisect 期间所有验证都只读不做任何写操作。3. git bisect run 自动化判定的脚本化实践3.1 自动化判定的核心退出码手工二分最大的问题是人容易不耐烦而且每次测试都要人在终端前守着。一旦判定规则可以写成命令就应该让 Git 自己跑。git bisect run就是干这个的。它的机制一句话概括你给 bisect 一条命令Git 自动在选中的提交上执行这条命令并根据命令的退出码来帮你做 good/bad 判断。退出码的语义需要严格记住退出码含义bisect 行为0提交是好的标记为 good继续搜索1~127提交是坏的标记为 bad继续缩小范围125无法判断跳过这个提交继续搜索128 及以上脚本或环境异常终止整个 bisect 流程注意125是个很讲究的码。它对应的是“当前提交没法判定好坏”的情况比如编译直接失败、测试环境连不上、缺少某个依赖文件。这种情况下如果把它当成 bad会污染搜索区间得出错误结论如果直接终止流程又太浪费。跳过是更合理的选择。3.2 一个可复用的判定脚本模板以 Node.js 项目为例我常用的判定脚本长这样#!/bin/bash # is-good.sh返回 0 表示提交正常返回非 0 表示提交有问题 # 先把构建跑通编译失败说明这个提交本身不完整跳过去 if ! npm run build --silent; then exit 125 fi # 跑一个能稳定复现 bug 的最小测试 node test/reproduce-bug.js这个脚本的逻辑很清晰先构建构建失败直接 125 跳过构建成功后跑复现脚本脚本退出码非 0 就说明 bug 存在脚本自然返回非 0bisect 会把它当成 bad。写脚本的时候有一个很关键的经验不要加set -e至少不能无脑加。因为set -e会让脚本在构建失败时直接退出但退出码可能被 shell 改写后面想控制 125 这个语义就费劲了。我更习惯用显式的if判断控制流程让每个分支的退出码都在自己掌控中。写好后执行命令就一行git bisect run bash is-good.shGit 会自己开始循环检出一个中间提交、执行脚本、看退出码、标记、继续。执行过程中的每一步进度都会打印在终端里。结束后会停留在最终定位到的“第一个坏提交”上然后你手动执行git bisect reset收尾。3.3 run 模式的注意事项与经验用 run 模式跑过几次后我给几个非常实用的建议。第一脚本一定要幂等。一个常见的反面教材是测试脚本依赖上一次跑出来的临时文件、端口、进程或者测试数据库状态被前一个提交污染了。第二个提交跑的时候结果就不准了bisect 立刻跑偏。我一般会要求脚本先清理自己的临时文件测试数据库也尽量用内存库或临时库确保每次执行都在干净状态里。第二正式跑之前一定要先手动验证脚本的准确性。最靠谱的做法是挑两个已知好和已知坏的提交手动 checkout 后分别执行一次判定脚本确认脚本对好提交返回 0、对坏提交返回非 0。这一步只需要几分钟但能防止脚本本身自带 bug 导致定位结果完全不可信。第三脚本里尽量避免写入仓库目录。有些测试会在运行时生成快照或者日志文件这些文件一旦留在工作区会污染下一次检出的状态。我的做法是全部写到/tmp或系统临时目录必要时在脚本开头清理上次遗留文件。git bisect run最适合的场景是那种判定逻辑非常明确的回归测试。如果你的 bug 需要人工观看页面、操作界面才能判断那确实不适合自动化继续用人工模式就好。4. 实战进阶大仓库、多分支与不稳定提交的处理4.1 直接指定 bad/good 区间标准流程是进入 bisect 状态后分别标 bad 和 good。其实还有一种更直接的方式在start这一步就把区间传进去git bisect start bad-commit-hash good-commit-hash这样等价于start之后立刻执行bad和good少敲两行命令。两个提交的位置没有严格要求Git 会自动把较新的当 bad、较旧的当 good 方向处理但为了可读性我还是习惯把坏的写在前面。当区间比较大的时候我还会额外看一眼这个区间里大概有多少个提交git log --oneline good..bad | wc -l这样能对“大概要跑几步”有个心理预期。如果区间里有几百个提交起步就要九到十步但如果你先用git log -S关键词把范围缩小到几十个提交可能四五步就出结果。4.2 遇到无法判定的提交skip 与 125开发中最常见的坑是中间某个历史提交因为依赖版本变化无法编译或者代码库结构还没成型测试脚本干脆跑不起来。这样的提交没有“好坏”可言硬判断只会污染二分结果。正确做法是人工模式下执行git bisect skip自动化模式下则让脚本返回 125。Git 会跳过这个提交然后继续在其他候选里做二分。即使中途跳过了几个只要剩下的提交仍然保持单调变化最后结论依然可靠。这里有个经验问题如果跳过太多bisect 最终可能给出一个“不精确”的结果甚至提示找不到明确边界。我遇到这种情况会先检查整个搜索区间是不是压根就没有连续的“好坏交界”。比如项目经历过一次大规模重构重构前后代码结构完全不同很多中间的 squash 提交没法独立构建这时候强行二分不现实。这种场景我会放弃全自动改用“先人工标出重构开始和结束的提交再分别对重构前后两个阶段做定位”。4.3 非单调变化的特殊场景我之前提到过二分查找成立的前提是提交状态单调。但现实中还有一种很磨人的情况这个 bug 在 A 提交引入B 提交修了一半C 提交又复发D 提交彻底修复然后 E 提交因为一次合并又把它带回来了。整套历史看起来就是“坏好坏好坏”反复横跳直接跑 bisect 很容易定位到错误的提交。怎么处理我的经验是分两步。先用git log -S或git log -G搜索和 bug 相关的关键词找到历史上最后一次修复它的提交把那个提交当作新的 good 起点把最后复发的那次提交之后的某个状态当作 bad 终点。这样就把一个“反复横跳”的问题重构成一个相对单调的子区间再跑 bisect 就靠谱得多。另一个思路是把判定脚本写得更“苛刻”一点让它在检测到任何轻微的问题迹象时都返回 bad。比如一个性能小回退你要判断的不是“能不能工作”而是“响应时间是否超过阈值”。这种严格判定能帮你打断“时好时坏”的幻觉让状态分布更接近单调。4.4 与 git log -S、git blame 配合定位git bisect不是万能的灵药它擅长的是“确定边界”。有些时候先用别的命令做粗筛能显著缩小 bisect 的搜索范围。如果你已经能大致猜到 bug 和某个字符串相关比如某个配置项丢了、某个方法名变了可以直接用git log -SconnectionTimeout --oneline -- src/main/resources这个命令会列出所有新增或删除过该字符串的提交。比如它告诉你这个字符串在两个提交里出现过变化那你可以直接看这两个提交是不是就是问题的根源或者至少把 bisect 的区间限定到这两个提交之间几步就能收尾。git blame也有它的价值但我要提醒一句blame 只告诉你某一行代码最后一次被谁改动那个提交不一定是引入 bug 的提交。项目经历过格式化、重构、文件移动之后blame 指向往往是最表面的那次改动真正的问题在更早的地方。这时候不要盲目信任 blame 的结果更应该用 bisect 从行为层面去验证。5. 常见问题与排查技巧速查5.1 高频问题速查表我整理了一份自己在实际使用中遇到的高频问题列表现象原因处理方式fatal: You are in the middle of a bisect之前进入 bisect 状态没有 reset执行git bisect reset退出bisect 过程中工作区冲突有未提交的修改或子模块状态不干净先git stash结束后再恢复结果定位到的提交看起来没问题判定脚本不稳定或区间状态非单调复查脚本用git bisect log导出重放bad 和 good 选得太近范围太小二分没有意义用git log -S或git log -G先扩大线索脚本返回 125 的提交太多历史提交无法独立构建考虑缩小区间或放弃全自动标记错了某个提交人工误判git bisect log查看过程用git bisect replay重放或直接 reset 重来5.2 误操作后的恢复手段很多人第一次被 bisect 卡住不是因为找 bug 难而是因为它把仓库状态搞成了一个“不知道自己在哪”的局面。比如自动切换提交后你发现当前 HEAD 指向一个奇怪的 hash想回 master 又怕丢东西。这时候记牢两句话不要慌git bisect reset可以解百忧。git bisect log也是被低估的命令。它会完整打印出你每一步标记了什么提交、标成 good 还是 bad。如果你发现自己中间误标了一两次但又不想从头开始可以把输出保存下来git bisect log bisect.log然后根据自己的判断手动编辑这个日志文件去掉错误的标记步骤再执行git bisect reset git bisect replay bisect.log就能按照修正后的步骤重新走一遍。当然大多数时候重新 start 成本更低误标一步也不至于导致整个定位无法挽回这个技巧属于锦上添花。5.3 我的几个独家调试习惯最后分享几个我自己长期使用后沉淀下来的调试习惯。接到回归 bug 的第一件事不是马上跑 git log而是先判断“这个 bug 是外部因素还是代码变更导致的”。如果是服务器环境变化、第三方接口超时、数据源问题跑 bisect 纯属浪费时间。我会先确认同一个代码版本在另一个环境能跑通再考虑是不是某次提交引入的。确认要跑 bisect 后我会先给当前状态打一个 tag 或者记住 hash。万一中途发现 bad 状态标错了至少有一个明确的重置锚点。发布流程健全的项目每次发布打 tag 这个习惯尤其重要——没有 tag会很难找到一个“确定正常”的 good 基线。判定脚本一定要提前打磨。我见过太多同事脚本里直接写“跑完整套测试套件”结果每次 bisect 跑半个多小时还因为套件里偶发挂掉的用例得出错误结论。我的原则是判定脚本只包含和这个 bug 相关的最小复现范围越小越稳定结果越可信。等脚本固定下来后面再遇到同类问题直接把参数换一换就能复用。用git bisect这几年我最大的体会是它最值钱的不是省下那几分钟而是逼着我把“出问题时到底什么状态”想清楚。想清楚之后定位 bug 从“碰运气”变成了“走流程”。以后如果你深夜被线上回归 bug 拉起来别慌先找好 good 和 bad写一条能稳定复现的判定命令剩下的交给 Git 的二分查找。相信我一旦用顺了你就真的回不去人肉翻 git log 的日子了。