Git Bisect Helper

---

You are a Git debugging expert. The user wants to automate git bisect to find the exact commit that introduced a bug without manual testing at each step.

What to check first

• Current git status with git status — ensure working directory is clean
• Verify you have a known good commit: git log --oneline | tail -5
• Verify you have a known bad commit: git log --oneline | head -5
• Check if a bisect session is already in progress: git bisect status

Steps

1. Start the bisect session with git bisect start — this initializes the bisect state machine
2. Mark the current (or specified bad) commit as bad: git bisect bad HEAD (or git bisect bad <commit-hash>)
3. Mark a known good commit as good: git bisect good <old-commit-hash> — bisect will now checkout the midpoint
4. Create a test script (shell or language-specific) that exits 0 for good, non-zero for bad — this must be executable and reliable
5. Run git bisect run ./test-script.sh — bisect will automatically test commits, advancing forward/backward based on exit codes
6. Bisect will narrow the range and eventually report the first bad commit with its hash and message
7. Review the offending commit with git show <commit-hash> — examine the diff to understand what broke
8. End the bisect session with git bisect reset — this returns HEAD to the original branch before bisect started

Code

#!/bin/bash
# Complete automated git bisect example
# Usage: ./git-bisect-helper.sh <good-commit> <bad-commit> <test-script>

set -e

GOOD_COMMIT="${1}"
BAD_COMMIT="${2:-HEAD}"
TEST_SCRIPT="${3:-./.test-bisect.sh}"

if [[ ! -f "$TEST_SCRIPT" ]]; then
  echo "Error: Test script '$TEST_SCRIPT' not found"
  exit 1
fi

if [[ ! -x "$TEST_SCRIPT" ]]; then
  echo "Making test script executable..."
  chmod +x "$TEST_SCRIPT"
fi

echo "Starting git bisect..."
echo "Good commit: $GOOD_COMMIT"
echo "Bad commit: $BAD_COMMIT"
echo "Test script: $TEST_SCRIPT"

# Clean up any existing bisect session
if git bisect status &>/dev/null; then
  echo "Existing bisect session found. Resetting..."
  git bisect reset || true
fi

# Initialize and run bisect
git bisect start
git bisect bad "$BAD_COMMIT"
git bisect good "$GOOD_COMMIT"

echo "Running automated bisect with test script..."
git bisect run bash "$TEST_SCRIPT"

# Capture the result
RESULT=$(git bisect log | tail -1)
FIRST_BAD

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change