用 git bisect 二分查找,快速定位引入 Bug 的那次提交
一、问题场景
项目跑得好好的,某天突然发现一个功能坏了:上周发版时还正常,现在却报错。中间已经合入了几十次提交,逐个翻看 diff 既费时又容易漏看。这种"以前好、现在坏"的问题,Git 自带的 git bisect 是最省力的工具。它用二分法在提交历史里查找,几十次提交通常只需要测试五六次就能锁定元凶。
二、基本原理
bisect 的思路很简单:你告诉 Git 一个"好"的提交(问题还没出现)和一个"坏"的提交(问题已经出现),Git 会自动检出两者中间的那次提交让你测试。你回答它是好是坏,它再把范围缩小一半。假设中间有 64 次提交,最多 log2(64) = 6 轮就能找到第一次出错的提交。
三、手动二分的完整流程
# 1. 开始一次二分会话
git bisect start
# 2. 标记当前版本是坏的
git bisect bad
# 3. 标记一个已知正常的版本(可以是 tag 或提交号)
git bisect good v1.4.0
执行完第三步,Git 会输出类似 Bisecting: 31 revisions left to test after this (roughly 5 steps) 的提示,并自动切到中间某次提交。这时你运行项目或测试,根据结果输入:
git bisect good # 这个版本没问题
git bisect bad # 这个版本有问题
重复几轮后,Git 会打印出 xxxxxxx is the first bad commit,并附上该提交的作者、时间和改动文件。定位完成后,一定记得退出二分状态,回到原来的分支:
git bisect reset
如果某个中间版本因为别的原因根本编译不过,无法判断好坏,可以用 git bisect skip 跳过它,Git 会换一个相邻提交继续。
四、用脚本全自动二分
手动输入 good/bad 仍然需要人盯着。如果问题能用一个命令判断,就可以交给 git bisect run 全自动完成。规则是:脚本退出码为 0 表示好,1 到 127(125 除外)表示坏,125 表示跳过。
例如一个 Python 项目中,parse_date 函数对某种日期格式返回了错误结果。先写一个最小的检查脚本 check.sh:
#!/bin/sh
python -c "
from app.utils import parse_date
assert parse_date('2026-11-14').day == 14
" || exit 1
然后执行:
git bisect start HEAD v1.4.0
git bisect run sh check.sh
Git 会自动循环检出、运行脚本、根据退出码标记,最后直接给出第一个坏提交。整个过程不需要人工干预,几分钟就结束了。这里有个小技巧:检查脚本最好放在仓库外面,或者确保它不被版本控制,否则切换到旧提交时脚本可能不存在。
如果项目已有单元测试,也可以直接用测试命令:
git bisect run pytest tests/test_utils.py -x -q
五、几个实用细节
- 查看和回放过程:
git bisect log会输出本次二分的全部标记记录,可以保存成文件;之后用git bisect replay 文件名重放,适合中途标错时修正。 - 好坏术语可以自定义:如果你要找的不是 Bug,而是"某个性能变快是从哪次提交开始的",用
git bisect start --term-old=slow --term-new=fast,语义会更清楚。 - 只关心部分目录:
git bisect start -- src/parser/只在改动了该目录的提交中二分,进一步减少测试次数。 - 合并提交较多时:可以加上
--first-parent(Git 2.29 及以上),只沿主线二分,先定位是哪次合并引入的问题,再深入该分支。 - 注意工作区干净:开始前先
git stash保存未提交的改动,避免切换提交时冲突。
六、总结
git bisect 把"在大量提交中找问题"变成了一个机械的二分过程:手动模式适合需要人工观察界面的问题,run 模式适合能用脚本判断的问题。定位到具体提交后,结合 git show 查看改动,修复往往就很直接了。建议在团队里把"写一个最小复现脚本 + bisect run"作为排查回归问题的标准动作,比凭经验猜测要高效得多。
- 点赞
- 收藏
- 关注作者
评论(0)