Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 78 ยท Inspecting History

Finding Bugs with git bisect

Use git bisect to find the exact commit that introduced a bug by binary search: manual good/bad marking, automated bisect run, skip, terms, log and replay.

Your test suite passed last month. Today it fails. Between then and now there are 400 commits from eight people. Reading them all is hopeless, and checking out each one to test by hand takes days. But you do not need to check 400 commits. You need to check about nine.

git bisect finds the commit that introduced a change in behavior using binary search. You tell Git one commit where things were good and one where they are bad. Git checks out the commit in the middle and asks you: good or bad? Each answer discards half of the remaining candidates. After roughly log2(N) steps (9 for 400 commits, 10 for 1,000, 20 for a million) Git names the first bad commit. If you can write a script that tests for the bug, Git can run the whole search for you with no human involved.

The idea in a picture

TEXT
good                                                              bad
 o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o---o
 1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17

 test 9  -> bad    : the culprit is among 2..9      (8 candidates left)
 test 5  -> good   : the culprit is among 6..9      (4 left)
 test 7  -> good   : the culprit is 8 or 9         (2 left)
 test 8  -> bad    : commit 8 is the first bad commit

Two assumptions make this work. First, the history between "good" and "bad" must be linear enough that the property flips once: good before some commit, bad from it onwards. Second, you must be able to test a commit reliably. Flaky tests produce wrong answers. Git handles merges (it follows all parents), but if the bug was introduced, fixed and re-introduced, bisect finds one transition, not necessarily the one you expect.

A history with a hidden bug

All examples use a generated project of 12 commits. Every commit writes a small file app.cfg. Starting with commit 8, the file contains score=-1 (the bug). We will find commit 8 without looking at the file history.

Bash Create the project and see the bug

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Manual bisect step by step

The commands are small:

Command Meaning
git bisect start begin a session (it records where you started)
git bisect bad [rev] this commit has the bug (defaults to HEAD)
git bisect good [rev] this commit does not have the bug
git bisect skip I cannot test this commit; pick a different one
git bisect reset end the session and go back to where you started
git bisect log show everything you told Git so far
git bisect run <cmd> automate the whole thing

After you have given Git one bad and one good commit, it checks out a commit in the middle and prints how many steps remain. You test, answer good or bad, and repeat until Git prints "is the first bad commit".

Bash Bisect by hand (answers given by a helper)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Count the lines starting with --- testing: Git needed only four tests (Change 6, 9, 8 and 7) to pick the culprit out of twelve commits, and the log of the session ends with the verdict "Change 8". After git bisect reset you are back on your branch, as if nothing had happened. Notice that the files in the working directory changed on every step: bisect really checks out each candidate commit. Commit or stash your own work before you start, or Git will refuse to switch.

During a bisect session you are on a temporary, detached HEAD. Do not commit there. When you find the culprit, run git bisect reset first, then fix the bug on your normal branch.

Automating it: git bisect run

If you can express "is this commit good?" as a command, let Git drive. git bisect run <command> runs your command at each step and interprets the exit status:

Exit status Meaning
0 the commit is good
1 to 124, 126, 127 the commit is bad
125 the commit cannot be tested; skip it
128 or above abort the bisect (something is wrong with the script)

So the rule is: exit 0 for good, a small non-zero number for bad, 125 for "cannot test". A test failure from pytest, npm test, make test or grep already behaves like this, so often the command is just your normal test command.

Bash bisect run with a test script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The output shows each check: line, then the final block: the full hash, author, date, message and list of changed files of the first bad commit. Read that commit with git show; the cause of the bug is almost always in the diff. The shortcut git bisect start <bad> <good> is the same as start followed by bad and good.

Tips for a good test script:

  • Keep it outside the working tree (as above), or in a path that every commit has. A script inside the repo changes with each checkout.
  • It must be deterministic. Run it a few times on a known-good and a known-bad commit before bisecting.
  • If the project needs a build, build inside the script. A commit that does not even compile should exit 125 so it is skipped rather than counted as bad.
  • Test for the specific symptom, not "the test suite passes". Otherwise an unrelated earlier failure will derail the search.

Skipping commits that cannot be tested

Sometimes a commit in the middle is broken for a different reason: the build fails, a dependency is missing, a half-finished refactoring. You cannot tell if the bug is present. Answer git bisect skip (or exit 125 in a script). Git picks a nearby commit instead. If too many commits are skipped, Git may only be able to say that the culprit is "one of these commits".

Bash Skipping untestable commits with exit 125

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The skipped commits appear in git bisect log with a # skip entry, and the search still lands on "Change 7". Skipping is safe as long as the neighbours of the culprit can be tested.

Terms other than good and bad

"Good" and "bad" are awkward when you hunt for something that is not a bug: "when did this feature start to work?" or "when did the startup time get slower?" You can rename the two states with --term-old and --term-new (for example git bisect start --term-old=fast --term-new=slow), or simply use the generic words old and new: git bisect old means "like the start", git bisect new means "like the end".

Bash Bisect with custom terms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The result uses your own word: "is the first 'slow' commit". It makes logs and chat messages read naturally when the question is not about bugs.

Recording and replaying a session

git bisect log prints the commands issued so far. Save it to a file, and git bisect replay file repeats the whole session. It is handy when you made a wrong answer in the middle of a long manual bisect: save the log, edit out the wrong line, replay. It is also a convenient way to hand the evidence to a colleague. git bisect visualize (or view) opens gitk or falls back to git log to show the remaining candidates, which is not available in our sandbox.

Bash bisect log and replay

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Practical advice from the field

  • Pick the good commit carefully. A release tag or last known-good CI run is ideal. If you pick a "good" commit that is really bad, bisect lands on a meaningless result. Check it out and verify.
  • Small, atomic commits make bisect precise. If the first bad commit is a 3,000-line squash, you have only narrowed the bug to a pull request. This is a strong reason to commit in small steps (see Making Good Commits).
  • Merges: bisect handles them, but the culprit may be a merge commit if two individually fine branches combine into a failure. Look at its parents.
  • Flaky tests lie. If the bug appears 1 time in 5, loop the test inside the script (for i in 1 2 3 4 5; do ... done) so that "good" means five clean runs.
  • Use bisect for performance and behavior too, not only for crashes: any property you can measure with a command works.
  • Binary search needs a boundary. If you do not know a good commit at all, check out progressively older tags until the bug disappears.

For narrowing a bug down to a line rather than a commit, see blame, grep and Searching History; for naming the endpoints, see Revision Syntax.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Roughly how many commits does git bisect need to test to find one culprit among 1,000 commits?

    Binary search halves the candidate range at each step, so the number of tests grows with log2(N). For 1,000 commits that is about 10.
  2. 2. What should a script given to git bisect run exit with to say 'this commit cannot be tested, skip it'?

    0 means good, 1 to 124 (and 126, 127) means bad, 125 asks Git to skip the commit, and 128 or more aborts the bisect.
  3. 3. You finished a bisect and found the culprit. What is the right next step?

    During bisect you sit on a temporary detached HEAD. git bisect reset puts you back on your original branch so your fix lands in the right place.
  4. 4. Why should the test script for bisect run usually live outside the repository's working tree?

    Each step checks out another version of the files. A script that lives in the tree can disappear or change between steps, while one outside stays the same.
  5. 5. When is git bisect start --term-old=fast --term-new=slow useful?

    Custom terms make a bisect about performance or features easier to read: the result says 'first slow commit'.

Summary

  • git bisect binary-searches history for the first commit where a property changed; it needs one good and one bad commit and a way to test.
  • Manually: git bisect start, bad, good, answer at each step, then git bisect reset.
  • Automatically: git bisect run <command>; exit 0 = good, 1 to 124 = bad, 125 = skip, 128+ = abort.
  • Keep the script outside the working tree and make it deterministic; loop it for flaky tests.
  • skip handles commits that cannot be tested; custom terms (--term-old, --term-new) fit non-bug questions.
  • git bisect log and replay save and repeat a session; always reset before fixing anything.
  • Small, atomic commits make the result precise.

Next: The Reflog and Recovering Lost Work