Git Bisect and Debugging History¶

Overview¶

Production worked in v1.4.0 but fails in v1.5.0 — which of 200 commits broke it? Manual search is impractical. git bisect performs binary search through history, halving the candidate set with each test. Combined with automated test scripts, bisect finds regression commits in logarithmic time.

This is Tutorial 15 in Module 5: Recovery & Debugging of the REBASH Academy Git series.

Prerequisites¶

• Cherry-pick and Reflog
• Viewing History and Diffs

Learning Objectives¶

By the end of this tutorial, you will be able to:

• Start and run manual git bisect sessions
• Automate bisect with test scripts (git bisect run)
• Mark commits good/bad/skip appropriately
• Bisect across merge commits and tags
• Visualize bisect progress and results
• Integrate bisect into CI debugging workflows
• Reset cleanly after bisect with git bisect reset

Bisect Process Diagram¶

flowchart TB
    START["Start bisect<br/>bad=HEAD good=v1.4.0"]
    MID[Checkout middle commit]
    TEST{Test passes?}
    GOOD["Mark good<br/>search upper half"]
    BAD["Mark bad<br/>search lower half"]
    FOUND[First bad commit found]

    START --> MID --> TEST
    TEST -->|yes| GOOD --> MID
    TEST -->|no| BAD --> MID
    GOOD --> FOUND
    BAD --> FOUND```

## Theory

### Binary Search Concept

Given known **good** commit (works) and **bad** commit (broken), bisect checks out midpoint and asks: good or bad? Each answer eliminates half the remaining commits.

For N commits, ~log₂(N) steps — 1024 commits need ~10 tests.

### Starting Bisect

```bash
git bisect start
git bisect bad                    # current HEAD is broken
git bisect good v1.4.0            # tag known good

Git checks out middle commit. You test manually:

make test
git bisect good    # if pass
git bisect bad     # if fail

Repeat until first bad commit identified.

Automated Bisect¶

git bisect start HEAD v1.4.0
git bisect run ./test.sh

Script exit codes:

• 0 — good
• 1–124, 126–127 — bad
• 125 — skip (untestable commit)

#!/usr/bin/env bash
# test.sh for bisect
make build && ./run-integration-test.sh

Automation enables overnight bisect on large histories.

Skip Commits¶

Non-buildable commits (missing dependency, broken CI):

git bisect skip

Too many skips may fail to find exact commit — bisect warns.

Bisect and Merges¶

Bisect walks first-parent chain by default on merge-heavy repos. Use --first-parent explicitly when appropriate:

git bisect start --first-parent

Finding Good/Bad Boundaries¶

Document good/bad boundaries in incident tickets.

After Bisect¶

git bisect reset    # return to original branch

Always reset — bisect leaves you in detached HEAD.

DevOps Use Cases¶

• Terraform plan regression — which commit changed module source?
• Docker build failure — which Dockerfile layer change broke build?
• Flaky test introduction — bisect with probabilistic test (harder)
• Performance regression — script comparing response time threshold

git bisect log and replay¶

git bisect log > bisect.log
git bisect replay bisect.log

Share bisect session with teammates.

Limitations¶

• Requires reproducible good/bad test
• Shallow clones may lack commits — unshallow first
• Flaky tests produce wrong results
• Submodule repos need extra care

Hands-on Lab¶

Step 1 – Create history with intentional bug¶

Command:

mkdir -p /tmp/git-bisect-lab && cd /tmp/git-bisect-lab
git init -b main

good_test() { test "$(cat counter.txt 2>/dev/null)" -lt 5; }

for i in 1 2 3 4 5 6 7 8; do
  echo "$i" > counter.txt
  git add counter.txt
  if [ "$i" -le 4 ]; then
    git commit -m "feat: increment to $i (good)"
  else
    git commit -m "feat: increment to $i (bad region)"
  fi
done
git log --oneline

Explanation: Commits 5-8 are "bad" when threshold is < 5.

Step 2 – Manual bisect¶

Command:

git bisect start
git bisect bad HEAD
git bisect good HEAD~7
# Test current counter
VAL=$(cat counter.txt)
if [ "$VAL" -lt 5 ]; then git bisect good; else git bisect bad; fi
# Repeat until found — or use run script below
git bisect reset

Step 3 – Automated bisect¶

Command:

cat > test.sh << 'EOF'
#!/usr/bin/env bash
val=$(cat counter.txt)
test "$val" -lt 5
EOF
chmod +x test.sh
git bisect start HEAD HEAD~7
git bisect run ./test.sh
git bisect reset

Expected: First bad commit is when counter reaches 5.

Step 4 – Inspect culprit commit¶

Command:

git log --oneline | head -5
git show HEAD~4 --stat

Step 5 – Clean up¶

Command:

cd /tmp && rm -rf git-bisect-lab

Commands & Code¶

Terraform plan bisect test¶

#!/usr/bin/env bash
# tf-plan-bisect.sh — exit 0 if plan succeeds without errors
set -euo pipefail
terraform init -backend=false -input=false >/dev/null 2>&1
terraform validate
terraform plan -detailed-exitcode -input=false >/dev/null 2>&1
rc=$?
# 0 = no changes (good), 2 = changes (good), 1 = error (bad)
test "$rc" -ne 1

Common Mistakes¶

Best Practices¶

Troubleshooting¶

Summary¶

• git bisect binary-searches history between known good and bad commits
• Manual mode: mark good/bad after each test; automated: git bisect run
• Exit code 125 skips untestable commits; 0 good, non-zero bad for scripts
• Always git bisect reset when finished
• Essential for regression hunting in IaC, builds, and integration tests

Interview Questions¶

1. How does git bisect work algorithmically?
2. What exit codes should a bisect test script use?
3. When would you use git bisect skip?
4. How many steps to bisect 1000 commits approximately?
5. What is git bisect run?
6. Why must you run git bisect reset after finishing?
7. What are limitations of bisect with flaky tests?
8. How do tags help bisect in release debugging?
9. How does shallow clone affect bisect?
10. Give a DevOps scenario where bisect saves significant time.

Related Tutorials¶

• Cherry-pick and Reflog (previous)
• Git Hooks and Automation (next — Module 6)
• Viewing History and Diffs
• Undoing Changes — Reset, Revert, and Stash
• Git – Category Overview

References¶

• Pro Git Book – Debugging with Git
• git bisect documentation
• Kernel.org – Bisecting regressions
• REBASH Academy – Git Overview