Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 25 of 30

Finding the commit that broke things with git bisect

Use git bisect to find the exact commit that introduced a bug through a binary search, by hand or fully automated with a test script and git bisect run.

13 minPower toolsUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonRun a manual bisect session and an automated one with a test script, and interpret the first bad commit Git reports.

What you can do after this lesson

You will be able to answer the question "when did this stop working?" in a handful of steps, even across hundreds of commits. Git does a binary search for you: it checks out the commit in the middle, you say whether the bug is present, and it halves the remaining range again. The practice repository here has eleven commits; the same technique works for thousands, needing only about as many tests as the number of times you can halve the range.

The setup

A fictional shop keeps its price in a config file. Somewhere in history someone changed price=5 to a negative number. The log (hashes differ for you):

bash
git log --oneline
text
990beeb Commit 11: note
c85b148 Commit 10: note
4d4a1e9 Commit 9: note
8955013 Commit 8: tweak config
d4a52f3 Commit 7: note
531f59e Commit 6: note
8e3ffbb Commit 5: note
e4a2b6b Commit 4: note
85e39e3 Commit 3: note
51d8d1a Commit 2: note
41f0785 Commit 1: set price

The bug is visible now: the first line of shop.cfg reads price=-5. Commit 1 was fine. We want the first commit where the price is wrong.

A manual bisect

Start a session, tell Git the current commit is bad and an old commit is good:

bash
git bisect start
git bisect bad HEAD
git bisect good HEAD~10
text
status: waiting for both 'good' and 'bad' commits
status: waiting for 'good' commit(s), 'bad' commit known
Bisecting: 4 revisions left to test after this (roughly 2 steps)
[531f59e087c46e54d26567a54c5b92681e0eb99b] Commit 6: note

Git has checked out the middle commit, Commit 6. Your job is to test it. Here the test is looking at the first line of the file:

bash
head -1 shop.cfg
text
price=5

That is correct, so this commit is good:

bash
git bisect good
text
Bisecting: 2 revisions left to test after this (roughly 1 step)
[8955013d4842270568e584dfd335f6bd09103031] Commit 8: tweak config

Check again:

text
price=-5

Bad. Tell Git:

bash
git bisect bad
text
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[d4a52f3529f1236406c90ef1570b39f9ba97fbe1] Commit 7: note

Commit 7 is good, so the answer is the next commit. Mark it good and Git prints the result:

text
8955013d4842270568e584dfd335f6bd09103031 is the first 'bad' commit
Commit 8: tweak config

(The full message also shows the author, date and files changed.) Three tests found the culprit out of ten candidates. git show 8955013 then shows exactly what the commit changed, and its message and author tell you who to ask and why the change was made. When you are done, always end the session:

bash
git bisect reset
text
Previous HEAD position was 8955013 Commit 8: tweak config
Switched to branch 'main'

Without this you are left on an old commit in a detached state. If you lose track of where you are, git bisect log prints your answers so far, and git bisect visualize opens a graphical view where one is available.

Automating with git bisect run

If you can write a command that exits 0 when the code is good and non-zero when it is bad, Git can run the whole search itself. The test script test-price.sh (kept outside the repository, so checkouts do not touch it) was:

bash
#!/bin/sh
grep -q '^price=5$' shop.cfg

grep -q is silent and exits 0 when it finds a match, which is exactly the good or bad signal bisect wants. Run it:

bash
git bisect start HEAD HEAD~10
git bisect run sh ../test-price.sh
text
Bisecting: 4 revisions left to test after this (roughly 2 steps)
[531f59e087c46e54d26567a54c5b92681e0eb99b] Commit 6: note
running 'sh' '../test-price.sh'
Bisecting: 2 revisions left to test after this (roughly 1 step)
[8955013d4842270568e584dfd335f6bd09103031] Commit 8: tweak config
running 'sh' '../test-price.sh'
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[d4a52f3529f1236406c90ef1570b39f9ba97fbe1] Commit 7: note
running 'sh' '../test-price.sh'
8955013d4842270568e584dfd335f6bd09103031 is the first 'bad' commit
bisect found first 'bad' commit

Git reached the same answer with no manual steps. Run git bisect reset afterwards. According to the Git manual, the exit code rules are: 0 means good; 1 to 127, except 125, means bad; 125 means this commit cannot be tested, so skip it; a code above 127 aborts the run. In a real project the script might run your test suite, for example a single failing test, rather than a grep.

Skipping untestable commits

Sometimes a commit in the middle does not build or run for an unrelated reason. Tell Git to skip it with git bisect skip, or have your script exit 125. Git then picks another nearby commit. If too many commits are skipped, Git may only be able to name a range of suspects instead of one commit.

Tips for good results

  • Small, focused commits make the answer precise. Bisect points to one commit; if that commit changed forty files, you still have work to do.
  • Have a quick, reliable test. A flaky test will send the search the wrong way.
  • Pick a known good commit honestly. If the "good" commit already had the bug, the answer will be wrong.
  • Do not edit tracked files during a session. Checkouts need a clean tree.
  • Tag or remember where you started. git bisect reset returns you to the original branch anyway.

Common mistakes

  • Marking a commit wrongly. One wrong answer sends the search astray; use git bisect log to review, and restart if needed.
  • Forgetting git bisect reset. You stay on an old commit.
  • Testing the wrong thing. Make sure your test fails for the bug you are hunting, not for another problem.
  • Bisecting with uncommitted changes. Commit or stash first.
  • Blaming the author. The commit exposed the bug; the cause may be a combination of changes.

Exercise

  1. Build a repository with ten commits, where one in the middle breaks a line in a file.
  2. Run a manual bisect, marking commits good or bad by looking at the file.
  3. Write a one-line test script and repeat the search with git bisect run. Compare the answers.
Show one possible answer
bash
git init
echo "price=5" > shop.cfg && git add . && git commit -m "Commit 1"
for i in 2 3 4; do echo "note $i" >> shop.cfg; git commit -qam "Commit $i"; done
sed -i.bak 's/price=5/price=-5/' shop.cfg && rm shop.cfg.bak && git commit -qam "Commit 5: break price"
for i in 6 7 8; do echo "note $i" >> shop.cfg; git commit -qam "Commit $i"; done
git bisect start HEAD HEAD~7
git bisect run sh -c "grep -q '^price=5$' shop.cfg"
git bisect reset

Both manual and automatic runs should name Commit 5: break price as the first bad commit.

Next: Submodules: a repository inside a repository.

Key points

  • git bisect does a binary search through history: you mark commits good or bad and Git narrows to the first bad commit.
  • Start with git bisect start, mark the current commit bad, mark an old working commit good, then test each commit Git checks out.
  • git bisect run <script> automates it: exit status 0 means good, 1 to 127 (except 125) means bad, and 125 means skip.
  • Bisect checks out old commits, so finish with git bisect reset to return to your branch.
  • It works best with small, focused commits and a quick, reliable way to test.

Check yourself

1. What problem does git bisect solve?
2. How many commits does bisect need to test, roughly, to search 1,000 commits?
3. In git bisect run, what does a test script's exit status of 0 mean?
4. You have found the culprit. What command ends the session and returns you to your branch?