When developing software or managing long-lived codebases in Linux, tracking down regressions—bugs or performance drops that did not exist in earlier versions—can be an arduous diagnostic challenge. When a repository contains hundreds or thousands of commits between a known working state and the current broken build, reviewing code diffs manually is inefficient and prone to oversight.
The git bisect command automates regression debugging by applying a binary search algorithm across your repository commit history. By checking out the midpoint between a known working (“good”) commit and a broken (“bad”) commit, Git reduces the search space logarithmically ($O(\log n)$). A regression hidden among 1,024 commits requires only ten test steps to pinpoint the exact commit that introduced the fault.
Starting a Manual Git Bisect Session
To begin diagnosing a regression in your Linux terminal:
- Navigate into your local Git repository and ensure your working directory is clean:
cd /path/to/project
git status
- Initialise the bisect engine:
git bisect start
- Mark the current broken state (or any known faulty commit hash):
git bisect bad
- Mark an earlier version, tag, or commit hash where the software was verified to function properly:
git bisect good v2.4.0
Git immediately calculates the total number of commits between the two boundaries, selects the exact midpoint commit, checks it out into a detached HEAD state, and outputs the remaining estimated steps:
Bisecting: 64 revisions left to test after this (roughly 6 steps)
[3a4f89d1c08...] Update database pooling connection parameters
Testing and Tagging Commits Manually
At each intermediate commit checked out by Git, compile your application, execute your test suite, or perform manual verification:
- Run your application build or test command:
make && ./bin/app-test
- If the software works correctly and the regression is absent, inform Git:
git bisect good
- If the regression is present, inform Git:
git bisect bad
- If the current commit contains an unrelated compile failure or missing dependency preventing you from testing, skip it:
git bisect skip
Git automatically checks out the next calculated midpoint commit. Repeat this testing cycle until Git isolates the failure.
Identifying the Culprit Commit
Once the binary search narrows down to a single revision, Git outputs the full commit details:
3a4f89d1c08e54721abdf921094821a87b1c4321 is the first bad commit
commit 3a4f89d1c08e54721abdf921094821a87b1c4321
Author: Developer <[email protected]>
Date: Wed Oct 14 16:32:01 2026 +0100
Refactor socket connection timeout handling
src/network/socket.c | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
You can inspect the exact code changes introduced by that revision using git show:
git show 3a4f89d1c08e
Automating the Search with git bisect run
If your project has automated unit tests, integration tests, or a simple shell command that detects the failure, you can automate the entire bisect process with zero human intervention using git bisect run.
The script supplied to git bisect run must adhere to standard Unix exit codes:
- Exit code 0: The commit is good (test passed).
- Exit code 1 to 127 (except 125): The commit is bad (test failed).
- Exit code 125: The commit cannot be tested and should be skipped.
- Initialise the boundaries as before:
git bisect start
git bisect bad HEAD
git bisect good v2.4.0
- Run the automated test runner:
git bisect run pytest tests/test_payment_gateway.py
Git executes the test command, captures the exit code, tags the commit, and checks out the next revision automatically, completing hundreds of regression checks in seconds.
Resetting Your Repository to Normal State
Once you have identified the faulty commit and documented its hash, terminate the bisect session and return your working branch to its original position:
git bisect reset
Git checks out the branch you were on prior to starting the bisect session (such as main or develop) and clears the temporary bisect logs from .git/BISECT_*.