How to use git bisect?

I have read some articles saying that git bisect is awesome. However, I'm not a native speaker and I can't understand why it's awesome.

Could someone please demonstrate with some code sample:

1. How to use it?
2. Is it just like svn blame?

The idea behind git bisect is to perform a binary search in the history to find a particular regression. Imagine that you have the following development history:

... --- 0 --- 1 --- 2 --- 3 --- 4* --- 5 --- current

You know that your program is not working properly at the current revision, and that it was working at the revision 0. So the regression was likely introduced in one of the commits 1, 2, 3, 4, 5, current.

You could try to check out each commit, build it, check if the regression is present or not. If there is a large number of commits, this can take a long time. This is a linear search. We can do better by doing a binary search. This is what the git bisect command does. At each step it tries to reduce the number of revisions that are potentially bad by half.

You'll use the command like this:

$ git stash save
$ git bisect start
$ git bisect bad
$ git bisect good 0
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[< ... sha ... >] 3

After this command, git will checkout a commit. In our case, it'll be commit 3. You need to build your program, and check whether or not the regression is present. You'll also need to tell git the status of this revision with either git bisect bad if the regression is present, or git bisect good if it is not.

Let's suppose that the regression was introduced in commit 4. Then the regression is not present in this revision, and we tell it to git.

$ make
$ make test
... ... ...
$ git bisect good
Bisecting: 0 revisions left to test after this (roughly 1 step)
[< ... sha ... >] 5

It will then checkout another commit. Either 4 or 5 (as there are only two commits). Let's suppose it picked 5. After a build we test the program and see that the regression is present. We then tell it to git:

$ make
$ make test
... ... ...
$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[< ... sha ... >] 4

We test the last revision, 4. And since it is the one that introduced the regression, we tell it to git:

$ make
$ make test
... ... ...
$ git bisect bad
< ... sha ... > is the first bad commit
< ... commit message ... >

In this simple situation, we only had to test 3 versions (3, 4, 5) instead of 4 (1, 2, 3, 4). This is a small win, but this is because our history is so small. If the search range is of N commits, we should expect to test 1 + log2 N commits with git bisect instead of roughly N / 2 commits with a linear search.

Once you've found the commit that introduced the regression, you can study it to find the issue. Once this is done, you use git bisect reset to put everything back on the original state before using git bisect command.

git bisect run automatic bisect

If you have an automated ./test script that has exit status 0 iff the test is OK, you can automatically find the bug with bisect run:

git checkout KNOWN_BAD_COMMIT
git bisect start

# Confirm that our test script is correct, and fails on the bad commit.
./test
# Should output != 0.
echo $?
# Tell Git that the current commit is bad.
git bisect bad

# Same for a known good commit in the past.
git checkout KNOWN_GOOD_COMMIT
./test
# Should output 0.
echo $?
# After this, git automatically checks out to the commit
# in the middle of KNOWN_BAD_COMMIT and KNOWN_GOOD_COMMIT.
git bisect good

# Bisect automatically all the way to the first bad or last good rev.
git bisect run ./test

# End the bisect operation and checkout to master again.
git bisect reset

This supposes of course that if the test script ./test is git tracked, that it does not disappear on some earlier commit during bisection.

I have found that very often you can get away by just copying the in-tree script out of tree, and possibly playing with PATH-like variables, and running it from there instead.

Of course, if the test infrastructure on which test depends breaks on older commits, then there is no solution, and you will have to do things manually, deciding how to test commits one by one.

I have found however that using this automation often works, and can be a huge time saver for slower tests lying in your backlog of tasks, where you can just let it run overnight, and possibly have your bug identified by next morning, it is worth the try.

More tips

Stay on the first failing commit after bisect instead of going back to master:

git bisect reset HEAD

start + initial bad and good in one go:

git bisect start KNOWN_BAD_COMMIT KNOWN_GOOD_COMMIT~

is the same as:

git checkout KNOWN_BAD_COMMIT
git bisect start
git bisect bad
git bisect good KNOWN_GOOD_COMMIT

See what has been tested so far (by manual good and bad or run):

git bisect log

Sample output:

git bisect log
git bisect start
# bad: [00b9fcdbe7e7d2579f212b51342f4d605e53253d] 9
git bisect bad 00b9fcdbe7e7d2579f212b51342f4d605e53253d
# good: [db7ec3d602db2d994fe981c0da55b7b85ca62566] 0
git bisect good db7ec3d602db2d994fe981c0da55b7b85ca62566
# good: [2461cd8ce8d3d1367ddb036c8f715c7b896397a5] 4
git bisect good 2461cd8ce8d3d1367ddb036c8f715c7b896397a5
# good: [8fbab5a3b44fd469a2da3830dac5c4c1358a87a0] 6
git bisect good 8fbab5a3b44fd469a2da3830dac5c4c1358a87a0
# bad: [dd2c05e71c246f9bcbd2fbe81deabf826c54be23] 8
git bisect bad dd2c05e71c246f9bcbd2fbe81deabf826c54be23
# bad: [c536b1b7242d5fcf92cd87e9a534bedb1c0c9c05] 7
git bisect bad c536b1b7242d5fcf92cd87e9a534bedb1c0c9c05
# first bad commit: [c536b1b7242d5fcf92cd87e9a534bedb1c0c9c0

Show good and bad refs on git log to get a better notion of time:

git log --decorate --pretty=fuller --simplify-by-decoration master

This only shows commits with a corresponding ref, which reduces the noise grealy, but does include autogenerated refs of type:

refs/bisect/good*
refs/bisect/bad*

which tell us which commits we marked as good or bad.

Consider this test repo if you want to play around with the command.

Failure is fast, success is slow

Sometimes:

• failure happens fast, e.g. one of the first tests breaks
• success takes a while, e.g. the broken test passes, and all other tests we don't care about follow

For those cases, e.g. supposing the failure always happens withing 5 seconds, and if we are lazy to make the test more specific as we really should, we can use timeout as in:

#!/usr/bin/env bash
timeout 5 test-command
if [ $? -eq 1 ]; then
  exit 1
fi

This works since timeout exits 124 while the failure of test-command exits 1.

Magic exit statuses

git bisect run is a bit picky about exit statuses:

• anything above 127 makes the bisection fail with something like:

  git bisect run failed:
  exit code 134 from '../test -aa' is < 0 or >= 128
  

  In particular, a C assert(0) leads to a SIGABRT and exits with status 134, very annoying.

• 125 is magic and makes the run be skipped with git bisect skip.

  The intention of this is to help skip broken builds due to unrelated reasons.

See man git-bisect for the details.

So you might want to use something like:

#!/usr/bin/env bash
set -eu
./build
status=0
./actual-test-command || status=$?
if [ "$status" -eq 125 ] || [ "$status" -gt 127 ]; then
  status=1
fi
exit "$status"

Tested on git 2.16.1.

TL;DR

Start:

$ git bisect start
$ git bisect bad
$ git bisect good <goodcommit>

Or

$ git bisect start
$ git bisect good
$ git bisect bad <badcommit>

Bisecting: X revisions left to test after this (roughly Y steps)

Repeat:

Issue still exists?

• Yes: $ git bisect bad
• No: $ git bisect good

Result:

<abcdef> is the first bad commit

When Done:

git bisect reset

Just to add a further point:

We can specify a file name or path to git bisect start in case we know that the bug has come from particular files. For example, Suppose we knew that the changes that caused the regression were in the com/workingDir directory then we can run git bisect start com/workingDir This means that only the commits that changed the contents of this directory will be checked, and this makes things even faster.

Also,If it’s difficult to tell if a particular commit is good or bad, you can run git bisect skip, which will ignore it. Given there are enough other commits, git bisect will use another to narrow the search instead.

$ git bisect .. bascically a Git tool for debugging. 'Git Bisect' debugs by going through the previous commits since your last (known) working commit. It uses binary search to go through all those commits, to get to the one which introduced the regression/bug.

$ git bisect start # Starting bisect

$ git bisect bad # stating that the current commit (v1.5) has the regression/ setting 'bad' point

$ git bisect good v1.0 # mentioning it the last good working commit (without regression)

This mentioning of 'bad' and 'good' points will help git bisect (binary search) pick the middle element (commit v1.3). If the regression is there at commit v1.3, you'll set it as the new 'bad' point i.e. (Good -> v1.0 and Bad -> v1.3)

$ git bisect bad

or similarly if the commit v1.3 is bug-free you'll set it as the new 'Good point' i.e. (*Good -> v1.3 and Bad -> v1.6).

$ git bisect good

Note: the terms good and bad are not the only ones you can use for marking a commit with or without a certain property.

Git 2.7 (Q4 2015) introduced new git bisect options.

 git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>]
                  [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]

With documentation adding:

> Sometimes you are not looking for the commit that introduced a breakage, but rather for a commit that caused a change between some other "old" state and "new" state.

> For example, you might be looking for the commit that introduced a particular fix.
Or you might be looking for the first commit in which the source-code filenames were finally all converted to your company's naming standard. Or whatever.

> In such cases it can be very confusing to use the terms "good" and "bad" to refer to "the state before the change" and "the state after the change".

> So instead, you can use the terms "old" and "new", respectively, in place of "good" and "bad".
(But note that you cannot mix "good" and "bad" with "old" and "new" in a single session.)

> In this more general usage, you provide git bisect with a "new" commit has some property and an "old" commit that doesn't have that property.

> Each time git bisect checks out a commit, you test if that commit has the property:
If it does, mark the commit as "new"; otherwise, mark it as "old".

> When the bisection is done, git bisect will report which commit introduced the property.

---

See commit 06e6a74, commit 21b55e3, commit fe67687 (29 Jun 2015) by Matthieu Moy (moy).
See commit 21e5cfd (29 Jun 2015) by Antoine Delaite (CanardChouChinois).
^{(Merged by Junio C Hamano -- gitster -- in commit 22dd6eb, 05 Oct 2015)}

git bisect exit status

Ciro Santilli's 2014 answer refer to them as "magic exit status"

They will be used slightly differently with Git 2.36 (Q2 2022): a not-so-common mistake is to write a script to feed "git bisect"^(man) run without making it executable, in which case all tests will exit with 126 or 127 error codes, even on revisions that are marked as good.

Try to recognize this situation and stop iteration early.

See commit 48af1fd, commit ba5bb81, commit 8efa2ac, commit 80c2e96 (18 Jan 2022) by René Scharfe (rscharfe).
^{(Merged by Junio C Hamano -- gitster -- in commit e828747, 06 Mar 2022)}

> ## bisect--helper: double-check run command on exit code 126 and 127
> ^{Signed-off-by: René Scharfe}

> When a run command cannot be executed or found, shells return exit code 126 or 127, respectively.
> Valid run commands are allowed to return these codes as well to indicate bad revisions, though, for historical reasons.
> > This means typos can cause bogus bisect runs that go over the full distance and end up reporting invalid results.
> > The best solution would be to reserve exit codes 126 and 127, like 71b0251 (Bisect run: , 2007-10-26, Git v1.5.4-rc0 -- merge) (Bisect run: "skip" current commit if script exit code is 125., 2007-10-26) did for 125, and abort bisect run when we get them.
> That might be inconvenient for those who relied on the documentation stating that 126 and 127 can be used for bad revisions, though.
> > The workaround used by this patch is to run the command on a known-good revision and abort if we still get the same error code.
> This adds one step to runs with scripts that use exit codes 126 and 127, but keeps them supported, with one exception: It won't work with commands that cannot recognize the (manually marked) known-good revision as such.
> > Run commands that use low exit codes are unaffected.
> Typos are reported after executing the missing command twice and three checkouts (the first step, the known good revision and back to the revision of the first step).

See examples.