git bisect 实战：用二分查找快速定位回归 bug

上周我在一个维护了很久的“某老项目”里追一个诡异的回归bug头天晚上发版前还好好的第二天一上班同事就跑来说某个核心接口直接崩了。git log一看从上次稳定到崩掉之间有三十多个提交。按我以前的习惯肯定是倒着一个个git checkout回去试那次我试了五个提交就受不了了——每次都要装依赖、重新编译、再跑一遍复现流程一个循环至少十分钟。一上午折腾下来只确认了“问题大概出现在中间某一段”离真正定位还有十万八千里。后来我换成了Git自带的二分查找git bisect同一轮排查四轮检测就把崩溃点锁在了一个具体提交上。我当时就在想这功能这么好用为什么日常项目里很少有人把它当常规工具用我猜一个原因是文档写得干巴巴看起来像是“用来找bug的高级功能”另一个原因是大家习惯了逐提交排查这种笨办法没有意识到一个git bisect就能把复杂度从O(N)降到O(logN)。这篇就想把git bisect怎么用、为什么好用、真实项目里有哪些坑完整地讲一遍。内容不绕弯子直接照着我实际跑过的场景来。1. 一条命令把回归排查从一上午压缩到几轮编译1.1 二分查找在提交历史里是怎么工作的先别急着敲命令理清楚git bisect背后的逻辑比命令本身更重要。假设你的提交历史是一条直线从A肯定没问题的旧提交到G当前有问题的提交A - B - C - D - E - F - G你知道A是好的G是坏的问题铁定是在A到G之间某个提交引入的。最笨的办法是从B开始一个个试。如果这段历史有64个提交最坏情况要试63次平均也要30多次。git bisect的做法不同它先在中间附近挑一个提交给你测假设挑到D。你测完告诉它“D是好的”那A到D这一段就整体被划掉了——因为按“问题一旦引入就再也不会消失”的假设如果一个提交已经是好的那它之前的提交里更不可能引入问题。下次它再在D和G中间挑一个比如E或F继续问你好坏。每测一轮搜索空间就砍掉一半。64个提交的区间6轮必然收敛就算你是在200个提交里找也只要8次检测左右。这就是为什么我把标题写成“二分查找”Git是拿计算二分法的方式帮你在提交历史上做定位。它的准确叫法是二分定位回归提交原理和算法书里的二分查找完全一致只不过比较的对象不是数组元素的大小而是“当前提交是否已经变坏”。1.2 使用bisect前必须满足的两个前提不过git bisect能跑得动依赖两个前提。我在帮别人排查时发现很多人恰恰在这上面出了问题。第一个前提你要能明确说出两个锚点一个确定没问题的旧提交一个确定有问题的当前提交。听起来简单但真实项目里经常有人拍脑袋指了个“我觉得应该没问题的提交”结果那个提交其实是坏的或者压根就编译不过。这样二分从一开始就废了你要么拿一个根因引入前的提交做good锚点要么就别指望它能给出可靠结果。第二个前提历史尽量是线性的、可连续构建的。如果中间有大量“提交时就是坏的其实根本编译不过”的状态二分过程中git checkout到那个提交就可能失败或者无法测试。后文我会讲git bisect skip怎么应对但原则上这个工具最舒服的用武之地是那种“每个提交基本都能构建、只有某一个提交引入了回归”的稳定分支。1.3 什么时候真的值得上bisect有人问是不是每次出现bug都要git bisect不是。我自己是这么判断的提交数量在10个以下直接git log和git diff肉眼对比可能更快。提交数量在10到30个如果你对这个项目很熟也可以先猜几个重点提交试试比如依赖升级、配置变更。提交数量超过30个或者你根本不确定问题范围那无脑上bisect。人肉试错在这种规模下已经不是费时间的问题而是容易漏、容易错。还有一种情况也强烈建议用你深夜改了一堆东西第二天发现坏了但完全不记得自己动了哪块。这时候git bisect能帮你把“记忆模糊的排查”变成“机械而精确的流程”减少情绪消耗。2. 手工二分测试点怎么选、好坏标记怎么给2.1 最基础的一组命令先在实际仓库里走一遍最基本的流程。假设当前HEAD就是坏的那个你确认某个旧提交abc1234是好的。git bisect start git bisect bad # 默认把当前HEAD标记为坏 git bisect good abc1234 # 把指定提交标记为好三条命令敲完Git会立刻检出一个位于好坏区间中间的提交并告诉你类似这样的信息Bisecting: 14 revisions left to test after this (roughly 4 steps)意思是还剩14个提交需要排查按二分大概再测4轮就能收敛。接下来你就在这个被检出的提交上执行你的复现流程# 编译、启动、复现bug make build ./run-demo ./reproduce-bug.sh如果问题还在说明这个提交是坏的git bisect bad如果问题没了说明这个提交是好的git bisect goodGit会继续切到下一个中间提交重复上面的操作。你只需要机械地执行“编译、复现、标记”Git负责在背后挑下一个最优测试点。收敛之后它会打印abc1234 is the first bad commit然后你可以git show那个提交看diff通常一眼就能看出来问题出在哪。最后记得结束会话回到你原来所在的分支git bisect reset2.2 测试到什么程度才算“判定完成”这里有一个很多人容易犯的毛病跑一次发现“哎好像没崩”就急着标记good。我自己吃过亏所以特别提醒一句——判定一个提交是“好”的标准必须严格等于判定“坏”的标准。也就是说如果当前用户报告的bug是“特定参数下接口崩溃”那么你在老提交上要做的不是随便跑一道冒烟测试而是完整跑一遍那个特定参数的复现流程。哪怕只是少传了一个参数都有可能得出“老提交是好的”这种错误结论二分就会定错方向。我的建议是在开始bisect之前先写一个可复现的测试步骤清单。比如启动服务调用/api/foo接口附带固定请求体观察是否返回500且日志出现某异常。然后对每个被检出的提交一律按这三步走。不要中途加戏也不要偷工减料。否则每少测一步都是在给结果埋雷。2.3 测试中途遇到编译失败怎么办真实项目里很少能保证每个历史提交都编译通过。你很可能二分到某个提交时发现它正处于“半成品”状态——依赖没更新、配置文件不完整或者根本不是你熟悉的那套代码。这种时候不能凭感觉说“这应该是好的”或者“这应该是坏的”因为你没跑过测试没有证据。Git提供了一个专门的标记git bisect skip它会跳过这个提交在剩下的区间里重新挑测试点。你可以连着跳过好几个不可测的提交Git会相应调整策略。跳过之后的结果范围可能就不是一个精确的提交而是一个小区间但实际操作中这种损失完全可以接受。如果你跳过太多Git会提示你退一步——此时最可靠的做法是去看一眼这个区间里到底经历了哪些变更缩小范围再重新开始。3. 让脚本替你跑完所有检测git bisect run的正确姿势3.1 先写一个可重复执行的判定脚本手工一轮轮标记在当前提交多的时候也很累尤其要跑十几轮。所以只要条件允许我都会写一个脚本然后扔给git bisect run自动跑。原理很简单Git每切到一个中间提交就执行一次你给的脚本脚本的退出码告诉Git这个提交是好还是坏。脚本怎么写核心就一句话把你手工测试那三步骤原封不动地翻译成shell。一个典型的例子#!/usr/bin/env bash set -e # 编译当前提交 make build # 启动服务跑固定场景的复现脚本 ./run-demo /tmp/service.log 21 SERVICE_PID$! sleep 3 # 执行复现逻辑返回码写在变量里 ./reproduce-bug.sh REPRO_RESULT$? kill $SERVICE_PID 2/dev/null || true wait $SERVICE_PID 2/dev/null || true # 0表示当前提交正常非0表示当前提交已经出现问题 exit $REPRO_RESULT注意set -e在编译失败时会让脚本直接退出。这个行为要分情况看如果编译失败是因为提交本身半成品那退出码往往是1Git会把它当成“坏提交”这就不对了。所以更严谨一点要在脚本里区分“测试失败”坏和“无法测试”跳过。3.2 exit code约定与常见误用Git对git bisect run脚本的退出码有一套默认约定退出码含义对应标记0当前提交正常bug未出现git bisect good1~124当前提交有问题git bisect bad125无法测试该提交git bisect skip126~127脚本不可执行或命令不存在终止bisect128以上脚本被信号终止终止bisect这里最容易犯的错就是把“编译失败”当“测试失败”。前者应该返回125后者返回1或124。我见过有人的脚本长这样make build ./reproduce-bug.sh如果make build失败sh默认继续跑下一行然后./reproduce-bug.sh因为没有对应文件又返回1最后bisect就把“编译不过的提交”定成“第一个坏提交”。定位结果完全跑偏。正确的写法至少要像这样#!/usr/bin/env bash if ! make build; then echo SKIP: build failed at $(git rev-parse --short HEAD) exit 125 fi ./reproduce-bug.sh exit $?这样一来只有真正跑完复现逻辑并且确实出bug的提交才会被标记成bad。3.3 run跑到一半挂掉怎么恢复git bisect run最大的特点是不可交互——脚本失败比如中间崩了、网络超时、编译太久被CI杀掉就会整个停在那当前HEAD停在某个中间提交。你不要慌也不要乱checkout先看一下状态git bisect log这个命令会把整个会话的标记历史打印出来。它会显示已经标记了多少good多少bad。如果你想接着玩重新跑git bisect run ./test.sh它会从上一次中断的位置继续。如果某个标记你怀疑给错了想推翻重来可以用git bisect replay (git bisect log)先把log保存到文件里再replay也行。还有一个更粗暴的做法——想彻底清空会话重新开始git bisect reset git bisect start我在实际使用中会习惯性把git bisect log的每次输出存一份因为万一跑了一整晚、中途挂掉至少有记录可以追溯不至于白白浪费之前做的十几轮标记。4. 真实项目里绕不开的三种场景merge、rebase与超长构建4.1 merge提交会被选中吗要不要用--first-parent二分定位的默认逻辑是基于提交图的。如果你的历史里有merge提交Git的处理方式和我们直觉不太一样它会把提交图当作一棵树默认沿着“能最快缩小搜索范围”的路径去挑提交这可能导致它选中某个merge提交本身。merge提交值得测吗取决于你的策略。如果团队习惯用Git Flowfeature分支合回主干时产生的merge提交通常本身不包含实质性改动它只是把两边历史拼在一起。这时候测merge提交意义不大还容易让人疑惑“合过来的两边看起来都没问题为什么merge后坏了”。解决方案是git bisect的新版参数--first-parentgit bisect start --first-parent这个选项让Git只沿着主干的第一个父提交链做二分完全忽略merge引入的分支节点。它适用于“主干合入某个功能后开始出现问题但你想定位的是合入行为本身哪一步导致”的场景。副作用是收敛速度稍微慢一点因为搜索空间变大了但这总比在一堆merge节点里迷路好。不过也要提醒一句如果bug是真的在某个feature分支里引入的而合入主干merge本身没问题那用--first-parent反而会错过真正的根因——因为你根本不检查分支内部的提交。这时候更适合先看一下merge引入了哪些文件用git log -m、git show去追分支内部的内容。所以这个选项不是无脑开的要结合你对问题的判断。4.2 历史被改写后bisect还能不能用这是个高频问题。很多人经历过git rebase或者git push -f之后之前记下的commit hash全变了就开始担心bisect没法用了。答案是能用但锚点必须基于当前的提交ID。git bisect只认提交ID不认注释和分支名。如果你的历史经历过rebase老的“某个版本”哈希可能已经不存在了你必须重新找一个在当前历史上“确定是好”的提交作为good锚点。实际操作中有一个稳妥做法如果你知道“今天早上还好的”就去git reflog里找今天早上那个分支顶点的提交哈希哪怕后来被rebase了reflog里也通常还能看到它。把这个哈希作为good锚点往往比瞎猜一个旧提交可靠得多。如果你的问题区间跨过一次大规模rebase——比如几百个提交被打平合并成几个——那二分的结果只会精确到“rebase后的某个提交”而不会定位到“rebase前的原始提交”。这时候你要再往下钻一层用git log看那个提交里具体动了哪些文件再做二次判断。4.3 构建时间太长的几条缓解思路最现实的问题来了项目编译一次要5分钟二轮检测跑下来就是半小时起步。这是很多人放弃git bisect的直接原因。我有三个缓解办法按性价比排序第一尽量复用构建缓存。如果你用的是有缓存的构建系统git bisect切换提交后很多编译产物其实可以增量复用。前提是构建目录不要被git clean掉也不要每次全量build。我一般这样起会话git bisect start git bisect bad git bisect good old-commit在后续每个测试点执行make build时会自动走增量编译只会重新编译改动过的部分速度能快一个数量级。第二把“构建”和“测试”分成两个脚本。git bisect run可以接受一个复合命令比如git bisect run ./build-and-test.sh但更经济的做法是在build-and-test.sh里先判断“这次切换的提交和上次构建的提交差异有多大”如果只是改了几个文档或配置文件可以直接跳过编译跑测试如果连依赖清单都变了再全量构建。注意增量编译有风险。如果你切换提交跨度比较大增量编译偶尔会产生“脏缓存”导致编译结果不准。稳妥起见构建脚本里最好加一句检测发现当前提交和缓存标记不一致就强制清掉关键产物重编。第三减少要检测的区间。如果问题明确只涉及某个模块你可以先看一下git log --oneline old..bad -- path/to/module把没动过目标模块的提交提前排掉或者用git bisect skip跳过那些明显不相关的提交。这个操作要谨慎跳过太多会让结果变成“一个区间”而不是“一个提交”。5. 实战中我踩过的坑和留下的习惯5.1 测试对象漂移与不干净的工作区有一次我正在某项目里跑bisect刚开始的三轮都很正常到第四轮突然全是“坏”的结果。我一度以为是代码真的在某个提交彻底崩了直到我发现git bisect切换提交后我的工作区还保留着一个没提交的临时配置文件——那个文件是我调试时留下的老提交的代码逻辑根本不会读它但它却影响了测试脚本的执行路径。从那以后我给自己定了一个规矩开始bisect之前先保证工作区干净。git status --short如果看到任何本地修改、未跟踪文件先stash或者提交掉再开始bisect。因为git bisect切换提交时不会替你处理这些本地改动它只切换仓库里已跟踪的代码其他残留都会成为变量。说白了bisect的整个逻辑建立在“每次测试的代码状态都严格等于仓库里某个提交的状态”这一假设上。任何多余的文件、环境变量、甚至是后台残留的旧进程都有可能让测试结果失真。5.2 非确定性测试双跑、三跑与“多数判定”另一个让我深恶痛绝的问题是“这个测试时好时坏”。比如某个并发场景的复现脚本第一次跑崩了第二次跑又过了。这种情况下你真不知道二分该标记什么。我的处理方式是**不要单次测试就下结论同一个提交至少要跑两遍最好三遍按多数结果判定。**如果三遍有两遍是坏的就标bad三遍有两遍是好的就标good。如果跑出来的结果乱七八糟完全没有规律那说明这个bug可能根本不在“引入回归”的范畴里而是环境可靠性问题——此时应该先修测试稳定性再谈bisect。这个“多数判定”逻辑如果写进bisect run脚本里也完全可行就是稍微繁琐一些#!/usr/bin/env bash PASS0 FAIL0 for i in 1 2 3; do if ./reproduce-bug.sh /dev/null 21; then PASS$((PASS1)) else FAIL$((FAIL1)) fi done if [ $FAIL -ge 2 ]; then exit 1 # 多数失败 - 坏 fi exit 0代价是检测时间翻三倍但换来的是结论可靠。遇到那种偶然性的崩溃值得。5.3 把判定脚本提交进仓库作为团队资产最后想分享一个我一直在用的习惯**好的bisect判定脚本不要写完就丢提交进仓库里保存。**路径可以放在scripts/bisect/或者tools/下面命名尽量描述清楚比如check-regression.sh。这样做的理由很实际同一个回归问题可能过段时间又出现到时候你只需要两条命令git bisect start git bisect run ./scripts/bisect/check-regression.sh整个团队都能复用不用每个人重新踩一遍“编译失败算不算坏”这种坑。而且脚本写得好本身就是一份活的测试文档写明了一个已知问题最精确的复现路径。我自己现在遇到回归类问题第一反应已经不是翻git log猜代码了而是先想“我有没有一个能稳定复现它的脚本”。如果有直接上git bisect如果没有先花十分钟把复现步骤固化成脚本再开始定位。这个习惯看起来绕了远路实际上才是效率最高的那条路。