（五）历史与追溯 - git bisect 命令的使用

文章目录

[1. 命令概述](#1. 命令概述)
[2. 命令格式](#2. 命令格式)
[3. 基本用法](#3. 基本用法)
[4. 高级用法](#4. 高级用法)
- [4.1 自动化模式 (git bisect run)](#4.1 自动化模式 (git bisect run))
- [4.2 处理无法测试的提交 (skip)](#4.2 处理无法测试的提交 (skip))
- [4.3 可视化查看二分查找过程](#4.3 可视化查看二分查找过程)
[5. 注意事项](#5. 注意事项)
[6. 补充信息](#6. 补充信息)

1. 命令概述

git bisect 的核心思想是： 在项目的提交历史中，快速定位到第一个引入 Bug 的提交。

想象一下，你的项目在 main 分支的当前版本（HEAD）有一个 Bug，但你知道在之前的某个版本（比如 v1.0）这个 Bug 不存在。提交历史就像一本按时间顺序排列的书，一页就是一个提交。从 v1.0 到 HEAD 可能有成百上千个提交，手动逐个检查效率极低。

git bisect 通过二分查找法自动化这个过程：

你告诉它一个"好"的提交（Bug 不存在）和一个"坏"的提交（Bug 存在）。
Git 会自动检出一个位于"好"与"坏"正中间的提交。
你测试这个提交，并告诉 Git 这个提交是"好"还是"坏"。
Git 根据你的反馈，将搜索范围缩小一半，再检出一个新的中间提交。
重复步骤 3 和 4，直到最终锁定那个引入 Bug 的特定提交。整个过程的时间复杂度是 O(log n)，对于成百上千的提交，通常只需要十几次测试就能找到问题所在。

2. 命令格式

git bisect 是一组子命令的集合，其基本格式为：

bash 复制代码

git bisect <subcommand> [<options>] [<arguments>]

常用的子命令有：

start：开始一次二分查找。
bad [<commit>]：标记当前（或指定）提交为"坏"。
good [<commit>]：标记当前（或指定）提交为"好"。
new [<commit>]：bad 的同义词。
old [<commit>]：good 的同义词。
skip：跳过当前提交（例如无法编译或测试）。
reset：结束二分查找，回到开始前的状态。
log：显示二分查找的日志。
replay：重放一个保存的日志。
run：自动运行二分查找（高级用法）。

3. 基本用法

这是最常见的使用场景。我们通过一个例子来演示：假设我们发现当前 HEAD 有编译错误，但记得在提交 abc123 时一切正常。
步骤 1：启动二分查找

bash 复制代码

git bisect start

步骤 2：标记当前提交为"坏"

通常，当前 HEAD 就是坏的。

bash 复制代码

git bisect bad
# 或者明确指定 HEAD
# git bisect bad HEAD

步骤 3：标记一个已知的"好"提交

我们需要告诉 Git 一个已知的好状态。假设提交 abc123 是好的。

bash 复制代码

git bisect good abc123

执行完这一步后，Git 会输出类似这样的信息：

复制代码

Bisecting: 191 revisions left to test after this (roughly 8 steps)
[commit_hash] 这个提交的提交信息

这意味着 Git 已经自动检出了第一个位于"好"与"坏"之间的中间提交。
步骤 4：测试当前提交

现在，你需要手动测试这个被 Git 检出的提交。例如，编译代码、运行测试套件、或者手动验证 Bug 是否存在。

如果 Bug 存在（即这个提交是"坏"的）：

bash 复制代码

git bisect bad

如果 Bug 不存在（即这个提交是"好"的）：

bash 复制代码

git bisect good

步骤 5：重复步骤 4

每次你标记好坏后，Git 都会自动将范围缩小一半，并检出一个新的提交。你只需要重复测试和标记的过程。
步骤 6：定位到罪魁祸首

最终，Git 会打印出类似以下的结果：

bash 复制代码

<commit_hash> is the first bad commit
commit <commit_hash>
Author: Some Developer <dev@example.com>
Date:   ...        
		This is the commit message that introduced the bug.

恭喜！你已经找到了引入 Bug 的第一个提交。
步骤 7：结束二分查找

非常重要的一步！使用完毕后，你必须退出二分查找状态，回到你开始之前的工作目录。

bash 复制代码

git bisect reset

这会将你的仓库恢复到 git bisect start 之前的状态（通常是 HEAD）。

4. 高级用法

4.1 自动化模式 (git bisect run)

这是 git bisect 最强大的功能。如果你有一个可以判断提交好坏的脚本，就可以让 Git 完全自动地完成整个查找过程。脚本的退出码决定了提交的状态：

退出码 0 ：提交是"好"的 (good)。
退出码 1 到 124（包含） ，但不包括 125 ：提交是"坏"的 (bad)。
退出码 125 ：提交无法测试（相当于 skip，例如代码无法编译）。

**示例：**假设你有一个脚本 test.sh，它能编译项目并运行测试，成功时返回 0，失败时返回 1

bash 复制代码

# 开始并设置好坏范围
git bisect start
git bisect bad HEAD
git bisect good v1.0
# 让 Git 自动运行脚本进行二分查找
git bisect run ./test.sh

Git 会全程自动执行，最终直接告诉你第一个坏提交是什么，然后自动执行 git bisect reset。

4.2 处理无法测试的提交 (skip)

有时，Git 检出的中间提交可能无法编译或者测试（例如，它只是一个不完整的工作提交）。这时你可以使用 skip 命令跳过它。

bash 复制代码

git bisect skip

Git 会尝试在剩余范围内选择一个合适的提交。

4.3 可视化查看二分查找过程

你可以使用 git log 来可视化二分查找的进度，它会显示当前的好、坏边界。

bash 复制代码

git log --oneline --graph --boundary $(git bisect rev-list --bisect-vars | tr ' ' '\n' | grep -E '^(BISECT_START|BISECT_BAD|BISECT_GOOD)')

（这个命令比较复杂，通常使用 git bisect log 查看文本日志就够了）。

5. 注意事项

务必记得 reset ：这是最重要的注意事项。如果你忘记 git bisect reset，你会处于一个分离的 HEAD 状态，可能会导致困惑。
测试必须准确：二分查找的准确性完全依赖于你对每个测试提交的"好/坏"判断。如果标记错误，最终结果也会错误。
选择合适的范围：起始的"好"和"坏"提交范围越大，二分查找需要的时间越长。尽量缩小初始范围。
good 和 bad 是相对的 ：它们不一定指代码功能的好坏。你可以用它们来查找任何"特性"的引入点。例如，用 good 表示"性能慢"，bad 表示"性能快"，来查找性能提升的提交。
自动化是王道 ：手动模式对于简单的 Bug 很有效，但对于复杂的回归测试，花时间编写一个自动化脚本（用于 git bisect run）会极大地提高效率。

6. 补充信息

new 和 old ：如果你查找的不是 Bug，而是一个新特性（比如一个新功能是何时引入的），使用 new（特性已存在）和 old（特性不存在）会比 bad/good 在语义上更清晰。它们在功能上完全等同于 bad/good。
从分支名开始 ：你可以直接用分支名来标记好坏，例如 git bisect bad main git bisect good develop。
查看状态 ：使用 git bisect status 可以查看当前二分查找的进度。
重放日志 ：git bisect log > bisect.log 可以保存日志，之后可以用 git bisect replay bisect.log 来重放整个过程，这对于复现或分享查找过程很有用。