Binary Search for Bug-Introducing Commits with Bisect

Intermediate12 minTrending

Use git bisect to perform an efficient binary search through commit history and pinpoint the exact commit that introduced a bug.

Prerequisites

-Git installed
-A known good commit where the bug did not exist
-A way to test whether the bug is present (manual or script)

Steps

Start the bisect session

Initialize bisect mode. Git will guide you through a binary search of commits between a known good and bad state.

$ git bisect start

Mark the current commit as bad

Tell Git that the current HEAD contains the bug. This sets the upper bound of the search range.

$ git bisect bad

You can also specify a commit hash: 'git bisect bad <hash>' if HEAD is not the bad commit.

Mark a known good commit

Provide a tag, branch, or commit hash where the bug was not present. Git will now check out the midpoint between good and bad.

$ git bisect good v2.1.0

If unsure which commit was good, try a commit from a few weeks ago and narrow down from there.

Test and mark each bisect step

Git checks out a commit halfway between good and bad. Test it, then mark it. Git halves the range each time, finding the culprit in O(log n) steps.

$ # Run your test, then mark: git bisect good # or if the bug is present: git bisect bad

If a commit cannot be tested (e.g., it does not build), use 'git bisect skip' to skip it. Git will try a nearby commit instead.

Automate bisect with a test script

Provide a command that exits 0 for good and non-zero for bad. Git will run it at each step automatically until it finds the first bad commit.

$ git bisect run npm test

You can use any script: 'git bisect run ./test-bug.sh'. The script must be in the working tree or an absolute path.

End the bisect session

Return to the original HEAD and end bisect mode. Git will output the first bad commit hash before resetting.

$ git bisect reset

Full Script

full-script.sh

#!/usr/bin/env bash
# git-bisect-debug.sh — Automated bisect with a test command
set -euo pipefail

GOOD_REF="${1:?Usage: $0 <good-ref> <bad-ref> <test-command>}"
BAD_REF="${2:?Usage: $0 <good-ref> <bad-ref> <test-command>}"
TEST_CMD="${3:?Usage: $0 <good-ref> <bad-ref> <test-command>}"

echo "Starting bisect..."
echo "  Good: $GOOD_REF"
echo "  Bad:  $BAD_REF"
echo "  Test: $TEST_CMD"
echo ""

git bisect start
git bisect bad "$BAD_REF"
git bisect good "$GOOD_REF"

echo ""
echo "Running automated bisect with: $TEST_CMD"
echo "========================================="
git bisect run $TEST_CMD

echo ""
echo "=== Bisect result ==="
git bisect log | tail -5

echo ""
echo "Resetting to original HEAD..."
git bisect reset
echo "Done."

FAQ

Discussion

Loading comments...

#!/usr/bin/env bash # git-bisect-debug.sh — Automated bisect with a test command set -euo pipefail GOOD_REF="${1:?Usage: $0 <good-ref> <bad-ref> <test-command>}" BAD_REF="${2:?Usage: $0 <good-ref> <bad-ref> <test-command>}" TEST_CMD="${3:?Usage: $0 <good-ref> <bad-ref> <test-command>}" echo "Starting bisect..." echo " Good: $GOOD_REF" echo " Bad: $BAD_REF" echo " Test: $TEST_CMD" echo "" git bisect start git bisect bad "$BAD_REF" git bisect good "$GOOD_REF" echo "" echo "Running automated bisect with: $TEST_CMD" echo "=========================================" git bisect run $TEST_CMD echo "" echo "=== Bisect result ===" git bisect log | tail -5 echo "" echo "Resetting to original HEAD..." git bisect reset echo "Done."