


Imagine this: a user reports that a feature is silently broken. No test caught it, no alert fired. You check `git log` and count 200 commits since the last known-good version. Questions stack up: which commit introduced it? Why does this code even exist, and what was it trying to do? Checking each one manually would take hours.

Git bisect solves this with binary search: a strategy where you repeatedly check the midpoint of a range and eliminate half the remaining possibilities each step. Applied to commits, 200 commits becomes 8 steps. 1,000 commits becomes 10 steps. You find the exact commit that introduced the bug.

## What you will have at the end

By the end, you will find the exact commit that broke a function using `git bisect`, first manually and then with a fully automated script. Tested on Git 2.39+ on macOS 14 and Ubuntu 22.04, June 2026.

Final output:

```text
b3f91a2 is the first bad commit
commit b3f91a2e7d5c1a0f3b8e9d4c2a1f6e7b8c9d0e1
Author: You <you@example.com>
Date:   Mon Jan 15 14:32:01 2026

    refactor: extract validation logic
```

That is the commit you want. Name, date, and a diff you can read and revert.

## Why not just read git log?

With a handful of commits, reading the log is fine. But bugs may surface late. By the time a test fails in CI, the culprit could be dozens of commits back, buried among refactors, dependency bumps, and formatting fixes.

Binary search removes the guesswork. You need only two things: a bad commit (current HEAD) and a good commit (some point before the bug appeared). Git bisect narrows the gap from there.

## Prerequisites

- Git 2.x (`git --version` to confirm)
- A repository with at least a few commits of history
- A way to test whether a given commit is broken: a test command, a script, or a quick manual check

## How bisect works

The midpoint is the commit that sits exactly halfway between your known-good and known-bad boundaries. Git calculates it automatically, checks it out, and waits for you to label it. When you do, one boundary moves inward and Git picks a new midpoint. The loop repeats until the two boundaries are adjacent and only one commit remains.

```mermaid caption="Git bisect loops until one commit remains. A wrong good/bad mark silently steers the search in the wrong direction."
flowchart TD
  A["Mark bad (HEAD)\n+ good (known stable)"] --> B["Git checks out midpoint\n(commit halfway between\ncurrent boundaries)"]
  B --> C{"Test it manually\nor run a script"}
  C -- "passes: git bisect good\nmove good boundary up" --> D["Eliminate older half"]
  C -- "fails: git bisect bad\nmove bad boundary down" --> E["Eliminate newer half"]
  C -- "untestable:\ngit bisect skip" --> B
  D --> F{"One commit\nleft?"}
  E --> F
  F -- "No, keep narrowing" --> B
  F -- "Yes" --> G["First bad commit reported"]
  G --> H{"Was every\nmark correct?"}
  H -- "Yes" --> I["Culprit found"]
  H -- "No: wrong mark\nor flaky test" --> J["Wrong commit reported\nReset and start over"]
```

Each loop cuts the remaining commits in half. The midpoint moves each round. Here is what that looks like on a history of 8 commits, where commit 5 introduced the bug:

```text
Start:   [1  2  3  4  5  6  7  8]   bad=8, good=1, midpoint=4
Round 1: test commit 4 → PASS       move good boundary to 4
         [            5  6  7  8]   new midpoint=6
Round 2: test commit 6 → FAIL       move bad boundary to 6
         [            5  6]         new midpoint=5
Round 3: test commit 5 → FAIL       boundaries adjacent, range collapsed
Result:  commit 5 is the first bad commit
```

Three tests for eight commits. That ratio holds at any scale: 1,000 commits takes at most 10 tests.

## Walking through a real session

The goal here is to simulate the exact scenario from the intro: a bug slipped in silently, we know a good starting point, and we want `git bisect` to surface the exact commit. We will build a small repository where we control which commit breaks things, then run bisect as if we did not know the answer.

## Step 1: Create a demo repository

Set up a small repo that simulates a real regression. A JavaScript `add` function gets silently broken in one commit.

```bash
mkdir bisect-demo && cd bisect-demo
git init
```

Add a function and build some history around it:

```bash
cat > math.js << 'EOF'
function add(a, b) { return a + b; }
module.exports = { add };
EOF
git add . && git commit -m "initial: add function"

git commit --allow-empty -m "chore: update readme"
git commit --allow-empty -m "feat: add multiply"
git commit --allow-empty -m "refactor: clean up imports"

# Introduce the bug
cat > math.js << 'EOF'
function add(a, b) { return a - b; }
module.exports = { add };
EOF
git add . && git commit -m "refactor: extract validation logic"

git commit --allow-empty -m "feat: add divide"
git commit --allow-empty -m "fix: unrelated typo"
git commit --allow-empty -m "chore: bump dependencies"
```

Check the full history:

```bash
git log --oneline
```

Expected output (your hashes will differ):

```text
a1b2c3d (HEAD) chore: bump dependencies
e4f5a6b fix: unrelated typo
c7d8e9f feat: add divide
b3f91a2 refactor: extract validation logic    <- the bug lives here
8a9b0c1 refactor: clean up imports
7d8e9f0 feat: add multiply
6c7d8e9 chore: update readme
5b6c7d8 initial: add function
```

## Step 2: Start the bisect session

A bisect session is the active search process managed by Git. It tracks which commits are good, which are bad, and which midpoint to test next.

```bash
git bisect start
```

Expected output:

```text
status: waiting for both good and bad commits
```

## Step 3: Mark the current commit as bad

Tell Git that HEAD is broken. In practice this is the commit your CI just flagged.

```bash
git bisect bad
```

Expected output:

```text
status: waiting for good commit(s), bad commit known
```

## Step 4: Mark a known-good commit

Pick the last commit you know was working. The older it is, the more commits Git searches, but the step count is still O(log n). Use the SHA from your `git log --oneline` output.

```bash
git bisect good 5b6c7d8   # replace with your "initial: add function" SHA
```

Expected output:

```text
Bisecting: 3 revisions left to test after this (roughly 2 steps)
[c7d8e9f] feat: add divide
```

Git checked out the midpoint commit. You are no longer on HEAD. Do not worry about that; `git bisect reset` will restore your branch at the end.

## Step 5: Test and mark each midpoint

At each step, Git waits for you to decide whether the current commit is good or bad. Test it:

```bash
node -e "const {add} = require('./math.js'); console.log(add(2, 3) === 5 ? 'PASS' : 'FAIL')"
```

If the output is `PASS`, mark it good:

```bash
git bisect good
```

If the output is `FAIL`, mark it bad:

```bash
git bisect bad
```

Repeat until Git prints the culprit:

```text
b3f91a2 is the first bad commit
commit b3f91a2...
Author: You <you@example.com>
Date:   ...

    refactor: extract validation logic
```

**Checkpoint:** You should see "is the first bad commit" and a single SHA. If you still see "Bisecting:", there are more rounds to complete.

## Step 6: Inspect the culprit

```bash
git show b3f91a2
```

The diff shows exactly what changed. From here you can understand the bug, file an issue, or revert the commit:

```bash
git bisect reset        # always do this first to restore HEAD
git revert b3f91a2      # optional: undo the commit
```

## Step 7: Reset the session

Git modifies your working tree during bisect. Resetting restores your branch.

```bash
git bisect reset
```

Expected output:

```text
Previous HEAD position was b3f91a2 refactor: extract validation logic
Switched to branch 'main'
```

Skipping this step leaves your repository in a detached HEAD state, meaning you are no longer on any branch. Always reset before continuing normal work.

## Automate with git bisect run

> **Pro tip:** Once you have a reliable test command, `git bisect run` removes you from the loop entirely. Useful for large histories and CI pipelines where you want zero human interaction.

Manual marking works for quick investigations. For large histories or CI pipelines, `git bisect run` removes the human entirely. You provide a script that exits `0` for good and non-zero for bad, and Git drives every step.

Create the test script:

```bash
cat > test.sh << 'EOF'
#!/bin/sh
node -e "const {add} = require('./math.js'); process.exit(add(2, 3) === 5 ? 0 : 1)"
EOF
chmod +x test.sh
```

Run the full automated bisect:

```bash
git bisect start
git bisect bad HEAD
git bisect good 5b6c7d8
git bisect run ./test.sh
```

Expected output:

```text
running ./test.sh
Bisecting: 3 revisions left to test after this (roughly 2 steps)
running ./test.sh
Bisecting: 1 revision left to test after this (roughly 1 step)
running ./test.sh
b3f91a2 is the first bad commit
bisect run success
```

No interaction required. The script ran on every midpoint and stopped at the first bad commit.

## Edge cases worth knowing

**The commit does not build**

Sometimes a midpoint cannot be tested because the code does not compile, or a dependency from that era is missing.

What to do:

```bash
git bisect skip
```

What to expect: Git picks an adjacent commit and continues. If several consecutive commits are skipped, the final answer may be a small range ("the bug is somewhere between commit A and commit B") rather than a single SHA. That range is still narrow enough to inspect manually.

**Flaky tests**

A test that randomly passes or fails on the same code will misclassify commits. One wrong good/bad label shifts the entire search in the wrong direction, and bisect will point at an innocent commit.

What to do: fix the flakiness before using `git bisect run`. You can verify a test is stable by running it ten times on the same commit and checking for consistent output. Manual bisect is safer with flaky tests because you can re-run before marking.

**Multiple regressions**

Bisect finds the first bad commit in the range you defined. If two separate bugs were introduced in the same window, bisect stops at the earlier one.

What to do: after fixing the first bug, run a fresh bisect session with updated bounds. Mark the commit just after the first fix as your new "good" starting point and repeat.

{/* subscribe-cta */}

## The one thing to remember

Start with a good commit as far back as you need. A wider initial range adds at most one or two extra steps, and every step you save is a minute you keep. When in doubt, start at the last release tag.

## References

- ["git bisect documentation."](https://git-scm.com/docs/git-bisect) git-scm.com
- ["git bisect run scripting guide."](https://git-scm.com/docs/git-bisect#_bisect_run) git-scm.com


Essaystaggeddebugging

Git Bisect: Find the Bug-Introducing Commit in Minutes