git-bisect-assistant

Git Bisect Assistant

Automates the git bisect process to efficiently identify the first bad commit responsible for a bug or test failure.

Quick Start

Basic usage pattern:

python scripts/git_bisect_runner.py \
  --good <known-good-commit> \
  --bad <known-bad-commit> \
  --test "<test-command>"

Example:

python scripts/git_bisect_runner.py \
  --good v1.0.0 \
  --bad HEAD \
  --test "pytest tests/test_feature.py::test_specific_case"

Workflow

1. Gather Information

   • Identify the known good revision (commit, tag, or branch)
   • Identify the known bad revision (defaults to HEAD)
   • Determine the test command that fails on bad commits and passes on good commits

2. Run Bisect

   • Execute the git_bisect_runner.py script with appropriate parameters
   • The script will automatically test commits and narrow down the culprit

3. Review Results

   • Examine the identified bad commit
   • Review the bisect log showing all tested commits
   • Check confidence level and assumptions

Parameters

Required

• --good: Known good revision (commit hash, tag, or branch name)
• --test: Shell command to test each commit. Exit code 0 = good, non-zero = bad

Optional

• --bad: Known bad revision (default: HEAD)
• --repo: Repository path (default: current directory)
• --retries: Number of test runs per commit for flaky tests (default: 1)
• --timeout: Test execution timeout in seconds (default: no timeout)

Handling Flaky Tests

For non-deterministic tests, use --retries to run the test multiple times per commit:

python scripts/git_bisect_runner.py \
  --good abc123 \
  --bad HEAD \
  --test "npm test" \
  --retries 3

The script uses majority voting: if a test passes 2 out of 3 times, the commit is marked as good.

Test Command Guidelines

The test command should:

• Exit with code 0 for good commits (test passes)
• Exit with non-zero code for bad commits (test fails)
• Be deterministic or use --retries for flaky tests
• Complete within reasonable time or use --timeout