Git

git-bisect 上次更新于 2.44.0

名称

git-bisect - 使用二分查找来查找引入错误的提交

概要

git bisect <subcommand> <options>

描述

该命令采用各种子命令，并且子命令具有不同的选项

git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
	  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>...]
git bisect terms [--term-(good|old) | --term-(bad|new)]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
git bisect run <cmd> [<arg>...]
git bisect help

此命令使用二分查找算法来查找项目历史记录中引入错误的提交。首先，您需要告诉它一个已知包含错误的“坏”提交，以及一个已知在引入错误之前的“好”提交。然后，git bisect 选择这两个端点之间的提交，并询问您选择的提交是“好”还是“坏”。它继续缩小范围，直到找到引入更改的确切提交为止。

实际上，git bisect 可用于查找更改项目任何属性的提交；例如，修复错误的提交，或导致基准测试性能提高的提交。为了支持这种更通用的用法，可以使用术语“旧”和“新”来代替“好”和“坏”，或者您可以选择自己的术语。有关更多信息，请参见下面的“备用术语”部分。

基本 bisect 命令：start、bad、good

例如，假设您正在尝试查找破坏了已知在项目版本 v2.6.13-rc2 中起作用的功能的提交。您可以按如下方式开始 bisect 会话

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

指定至少一个坏提交和一个好提交后，git bisect 会选择该历史记录范围中间的提交，将其检出，并输出类似于以下内容的内容

Bisecting: 675 revisions left to test after this (roughly 10 steps)

现在，您应该编译检出的版本并对其进行测试。如果该版本工作正常，请键入

$ git bisect good

如果该版本已损坏，请键入

$ git bisect bad

然后，git bisect 将以如下内容进行响应

Bisecting: 337 revisions left to test after this (roughly 9 steps)

继续重复该过程：编译树，对其进行测试，并根据它是好还是坏运行 git bisect good 或 git bisect bad 以请求需要测试的下一个提交。

最终，将没有剩余的修订版本可供检查，并且该命令将打印出第一个坏提交的描述。引用 refs/bisect/bad 将指向该提交。

Bisect 重置

在 bisect 会话之后，要清理二分状态并返回到原始 HEAD，请发出以下命令

$ git bisect reset

默认情况下，这将使您的树返回到在 git bisect start 之前检出的提交。（新的 git bisect start 也会执行此操作，因为它会清理旧的二分状态。）

使用可选参数，您可以返回到其他提交

$ git bisect reset <commit>

例如，git bisect reset bisect/bad 将检出第一个坏修订版本，而 git bisect reset HEAD 将使您停留在当前的二分提交上，并且完全避免切换提交。

备用术语

有时，您不是在寻找引入中断的提交，而是在寻找导致某些其他“旧”状态和“新”状态之间发生更改的提交。例如，您可能正在寻找引入特定修复程序的提交。或者，您可能正在寻找源代码文件名最终全部转换为公司命名标准的第一个提交。或任何其他情况。

在这种情况下，使用术语“好”和“坏”来指代“更改之前的状态”和“更改之后的状态”可能会非常令人困惑。因此，您可以分别使用术语“旧”和“新”来代替“好”和“坏”。（但请注意，在单个会话中，您不能将“好”和“坏”与“旧”和“新”混合使用。）

在这种更通用的用法中，您向 git bisect 提供一个具有某些属性的“新”提交，以及一个没有该属性的“旧”提交。每次 git bisect 检出一个提交时，您都要测试该提交是否具有该属性。如果是，则将提交标记为“新”；否则，将其标记为“旧”。二分完成后，git bisect 将报告哪个提交引入了该属性。

要使用“旧”和“新”代替“好”和“坏”，您必须在没有提交作为参数的情况下运行 git bisect start，然后运行以下命令以添加提交

git bisect old [<rev>]

表示提交在寻求的更改之前，或

git bisect new [<rev>...]

表示它在之后。

要获取当前使用的术语的提醒，请使用

git bisect terms

您可以使用 git bisect terms --term-old 或 git bisect terms --term-good 仅获取旧术语；git bisect terms --term-new 和 git bisect terms --term-bad 可用于了解如何调用比寻求的更改更新的提交。

如果您想使用自己的术语而不是“坏”/“好”或“新”/“旧”，则可以使用您喜欢的任何名称（除了现有的 bisect 子命令，如 reset、start 等），方法是使用以下命令开始二分

git bisect start --term-old <term-old> --term-new <term-new>

例如，如果您正在寻找引入性能回归的提交，则可以使用

git bisect start --term-old fast --term-new slow

或者，如果您正在寻找修复错误的提交，则可以使用

git bisect start --term-new fixed --term-old broken

然后，使用 git bisect <term-old> 和 git bisect <term-new> 代替 git bisect good 和 git bisect bad 来标记提交。

Bisect 可视化/查看

要在 gitk 中查看当前剩余的可疑对象，请在二分过程中发出以下命令（子命令 view 可以用作 visualize 的替代方法）

$ git bisect visualize

Git 通过各种环境变量检测图形环境：DISPLAY，它在 Unix 系统上的 X Window 系统环境中设置。 SESSIONNAME，它在交互式桌面会话中的 Cygwin 下设置。 MSYSTEM，它在 Msys2 和 Git for Windows 下设置。 SECURITYSESSIONID，它可能在交互式桌面会话中的 macOS 上设置。

如果未设置这些环境变量，则使用 git log 代替。您还可以提供命令行选项，例如 -p 和 --stat。

$ git bisect visualize --stat

Bisect 日志和 bisect 回放

在将修订版本标记为好或坏之后，发出以下命令以显示到目前为止已完成的操作

$ git bisect log

如果您发现指定修订版本的状态时犯了错误，则可以将此命令的输出保存到文件中，对其进行编辑以删除不正确的条目，然后发出以下命令以返回到已更正的状态

$ git bisect reset
$ git bisect replay that-file

避免测试提交

如果在二分会话的中间，您知道建议的修订版本不是一个好的测试版本（例如，它无法构建，并且您知道该故障与您正在追踪的错误没有任何关系），则可以手动选择附近的提交并对其进行测试。

例如

$ git bisect good/bad			# previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize			# oops, that is uninteresting.
$ git reset --hard HEAD~3		# try 3 revisions before what
					# was suggested

然后编译并测试所选的修订版本，然后以通常的方式将该修订版本标记为好或坏。

Bisect 跳过

您可以发出以下命令，而不是自己选择附近的提交，而是要求 Git 为您执行此操作

$ git bisect skip                 # Current version cannot be tested

但是，如果您跳过与您正在寻找的提交相邻的提交，则 Git 将无法准确地告诉您这些提交中哪个是第一个坏的。

您还可以使用范围表示法跳过一系列提交，而不仅仅是一个提交。例如

$ git bisect skip v2.5..v2.6

这告诉二分过程，不应测试 v2.5 之后（包括 v2.6）的任何提交。

请注意，如果您还想跳过该范围的第一个提交，则应发出以下命令

$ git bisect skip v2.5 v2.5..v2.6

这告诉二分过程，应跳过 v2.5 和 v2.6 之间的提交（包括这两个提交）。

通过向 bisect start 提供更多参数来减少二分

如果您知道树的哪个部分与您正在追踪的问题有关，则可以通过在发出 bisect start 命令时指定 pathspec 参数来进一步减少试验次数

$ git bisect start -- arch/i386 include/asm-i386

如果您事先知道多个好提交，则可以在发出 bisect start 命令时，通过在坏提交之后立即指定所有好提交来缩小二分空间

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

Bisect 运行

如果您有一个脚本可以判断当前源代码是好还是坏，则可以通过发出以下命令进行二分

$ git bisect run my_script arguments

请注意，如果当前源代码是好的/旧的，脚本（在上面的例子中是my_script）应该以代码 0 退出；如果当前源代码是坏的/新的，则以介于 1 和 127 之间（包括 1 和 127）的代码退出，但 125 除外。

任何其他退出代码都将中止二分查找过程。应该注意的是，通过 exit(-1) 终止的程序会将 $? 设置为 255（参见 exit(3) 手册页），因为该值会被 & 0377 截断。

当当前源代码无法测试时，应使用特殊的退出代码 125。如果脚本以此代码退出，则当前修订将被跳过（参见上面的 git bisect skip）。之所以选择 125 作为用于此目的的最高合理值，是因为 POSIX shell 使用 126 和 127 来表示特定的错误状态（127 表示命令未找到，126 表示命令已找到但不可执行——这些细节并不重要，因为就 bisect run 而言，它们是脚本中的正常错误）。

您通常会发现在二分查找会话期间，您希望对正在测试的修订进行临时修改（例如，在头文件中将 s/#define DEBUG 0/#define DEBUG 1/，或者“不包含此提交的修订需要应用此补丁才能解决此二分查找不感兴趣的另一个问题”）。

为了应对这种情况，在内部 *git bisect* 找到要测试的下一个修订后，脚本可以在编译之前应用补丁，运行真正的测试，然后在之后决定修订（可能包含所需的补丁）是否通过了测试，然后将树倒回到原始状态。最后，脚本应以真实测试的状态退出，以使 git bisect run 命令循环确定二分查找会话的最终结果。

选项

--no-checkout: 在二分查找过程的每次迭代中，不要检出新的工作树。而是仅更新名为 BISECT_HEAD 的引用，使其指向应该测试的提交。

当您在每个步骤中执行的测试不需要检出的树时，此选项可能很有用。

如果存储库是裸存储库，则假定为 --no-checkout。
--first-parent: 在看到合并提交时，仅跟随第一个父提交。

在检测通过合并分支引入的回归时，合并提交将被标识为错误的引入，并且其祖先将被忽略。

当合并的分支包含损坏或不可构建的提交，但合并本身没问题时，此选项尤其有用，可以避免误报。

例子

自动二分查找 v1.2 和 HEAD 之间的损坏构建

$ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
$ git bisect run make                # "make" builds the app
$ git bisect reset                   # quit the bisect session

自动二分查找 origin 和 HEAD 之间的测试失败

$ git bisect start HEAD origin --    # HEAD is bad, origin is good
$ git bisect run make test           # "make test" builds and tests
$ git bisect reset                   # quit the bisect session

自动二分查找损坏的测试用例
```
$ cat ~/test.sh
#!/bin/sh
make || exit 125                     # this skips broken builds
~/check_test_case.sh                 # does the test case pass?
$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run ~/test.sh
$ git bisect reset                   # quit the bisect session
```
在这里，我们使用 test.sh 自定义脚本。在此脚本中，如果 make 失败，我们将跳过当前提交。如果测试用例通过，check_test_case.sh 应该 exit 0，否则应该 exit 1。

如果 test.sh 和 check_test_case.sh 都位于存储库之外，则更安全，可以防止二分查找、make 和测试过程与脚本之间的交互。
使用临时修改（紧急修复）自动进行二分查找
```
$ cat ~/test.sh
#!/bin/sh

# tweak the working tree by merging the hot-fix branch
# and then attempt a build
if	git merge --no-commit --no-ff hot-fix &&
	make
then
	# run project specific test and report its status
	~/check_test_case.sh
	status=$?
else
	# tell the caller this is untestable
	status=125
fi

# undo the tweak to allow clean flipping to the next commit
git reset --hard

# return control
exit $status
```
这会在每次测试运行之前应用来自紧急修复分支的修改，例如，如果您的构建或测试环境发生变化，以至于较旧的修订可能需要较新的修订已经拥有的修复。（确保紧急修复分支基于包含在您正在二分查找的所有修订中的提交，以便合并不会引入太多内容，或者使用 git cherry-pick 而不是 git merge。）

自动二分查找损坏的测试用例

$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
$ git bisect reset                   # quit the bisect session

这表明如果您在一行中编写测试，则可以不用运行脚本。

在损坏的存储库中找到对象图的良好区域

$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
$ git bisect run sh -c '
	GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
	git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
	git pack-objects --stdout >/dev/null <tmp.$$
	rc=$?
	rm -f tmp.$$
	test $rc = 0'

$ git bisect reset                   # quit the bisect session

在这种情况下，当 *git bisect run* 完成时，bisect/bad 将引用一个提交，该提交至少有一个父项，其可到达的图在 *git pack objects* 所需的意义上是完全可遍历的。

在代码中查找修复而不是回归

$ git bisect start
$ git bisect new HEAD    # current commit is marked as new
$ git bisect old HEAD~10 # the tenth commit from now is marked as old

或

$ git bisect start --term-old broken --term-new fixed
$ git bisect fixed
$ git bisect broken HEAD~10

获得帮助

使用 git bisect 获取简短的用法描述，并使用 git bisect help 或 git bisect -h 获取详细的用法描述。

参见

使用 git bisect 消除回归, git-blame[1]。

属于 git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

补丁

调试

邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述