How to Use git bisect in Linux Terminal to Locate Buggy Commits Using Binary Search

When regression bugs slip into a software codebase across dozens or hundreds of merged pull requests, manually testing individual git revisions is time-consuming and inefficient. The Linux terminal provides a native Git diagnostic engine called git bisect. By utilizing a binary search algorithm, git bisect cuts through commit histories logarithmically—allowing developers to isolate the exact commit that introduced a defect in just a handful of checks.

How Binary Search Operates in Git Bisect

Rather than evaluating commits sequentially from newest to oldest, git bisect requires you to declare two reference points:

• Bad Commit: A commit state (usually the current HEAD) where the defect is observed.
• Good Commit: A known historical commit or release tag where the feature functioned correctly.

Git automatically calculates the midpoint between the good and bad revisions, checks out that specific commit, and awaits your feedback. If the midpoint passes your test, Git eliminates the entire older half of commits; if it fails, it eliminates the newer half. A history of 1,000 commits can be resolved in approximately 10 test iterations.

Step 1: Start the Bisect Wizard

Open your terminal, navigate into your Git repository directory, and initialise the bisect session:

git bisect start

Step 2: Define the ‘Bad’ and ‘Good’ Boundaries

Inform Git that the current checked-out revision exhibits the bug:

git bisect bad

Next, supply a known stable commit hash, branch, or release tag where the bug did not exist:

git bisect good v2.4.0

Git will immediately report the remaining search space and check out the first midpoint commit:

Bisecting: 128 revisions left to test after this (roughly 7 steps)
[a1b2c3d4e5f6] Refactor user session caching layer

Step 3: Test and Flag Midpoint Commits

At each step, build your application, execute unit tests, or run the offending command:

• If the bug persists in this revision, mark it as bad:

  git bisect bad

• If the application functions normally without the bug, mark it as good:

  git bisect good

• If a commit cannot be tested due to an unrelated compile error or missing dependency, skip it:

  git bisect skip

Git continues halving the commit range until it isolates the first broken change.

Step 4: Identify the Culprit and View Commit Details

Once isolated, Git prints the author, date, commit message, and changed files of the offending commit:

a1b2c3d4e5f67890abcdef1234567890abcdef12 is the first bad commit
commit a1b2c3d4e5f67890abcdef1234567890abcdef12
Author: Alex Developer <[email protected]>
Date:   Mon Sep 14 11:24:08 2026 +0100

    Update token expiration validation logic

:040000 040000 789abc... def123... M  src/auth/session.ts

To inspect the exact code changes introduced by this commit, run:

git show a1b2c3d4e5f6

Step 5: Automating the Process with git bisect run

If you have an automated test suite or a shell script that exits with code 0 when successful and code 1 to 127 when failing, Git can run the entire bisect loop autonomously without manual intervention:

git bisect start HEAD v2.4.0
git bisect run npm test -- auth.test.ts

Git will automatically step through each commit, execute the test script, record the exit code, and identify the culprit in seconds.

Step 6: Resetting Your Repository State

After isolating the root cause, return your working tree to your original branch:

git bisect reset

Utilising git bisect eliminates guesswork when debugging regression defects, providing an audit trail and preserving developer productivity across complex software codebases.