Git Bisect Helper Action

Automated git bisect session that pinpoints the exact commit introducing a regression.

When to Use This Command

Run this command when you need to:

• Identify the precise commit that introduced a bug or regression in your codebase
• Automate binary search through hundreds of commits with a test command
• Debug intermittent failures by systematically narrowing down the offending changeset

Consider alternatives when:

• The regression was introduced in the last few commits and manual inspection is faster
• You already know which file or module caused the issue and want to use git log -p instead

Quick Start

Configuration

Copy
name: git-bisect-helper-action
type: command
category: git-workflow

Example Invocation

Copy
claude command:run git-bisect-helper-action --bad HEAD --good v2.3.0 --test "npm test"

Example Output

Starting bisect session...
Bisect range: v2.3.0..HEAD (47 commits)
Running test at commit a3f8c21... PASS (good)
Running test at commit d91b4e7... FAIL (bad)
Running test at commit c54ea09... PASS (good)
Running test at commit e82f1a3... FAIL (bad)
Bisect complete: first bad commit is e82f1a3
  Author: [email protected]
  Date: 2026-02-14
  Message: "Refactor auth middleware to use async handlers"
  Files changed: src/middleware/auth.ts, src/utils/session.ts

Core Concepts

Bisect Strategy Overview

Aspect	Details
Algorithm	Binary search through commit history for O(log n) efficiency
Test Modes	Automatic (exit-code based), manual (interactive prompts), hybrid
Safety	Creates backup branch before starting; restores state on abort
Skip Support	Automatically skips commits that cannot be tested (build failures)
Logging	Maintains detailed bisect log with reasoning at each step

Bisect Workflow

[Known Good Commit] ---- midpoint ---- [Known Bad Commit]
        |                   |                   |
        v                   v                   v
    tag: v2.3.0        test here             HEAD
                           |
                     PASS? go right
                     FAIL? go left
                           |
                    narrow range by half
                           |
                    repeat until 1 commit

Configuration

Parameter	Type	Default	Description
bad	string	HEAD	The commit known to contain the bug
good	string	(required)	The last known working commit or tag
test	string	(none)	Shell command to run at each bisect step
skip-build-failures	boolean	true	Skip commits where the project fails to build
max-steps	integer	50	Abort bisect if it exceeds this many steps

Best Practices

1. Tag releases consistently - Having reliable version tags makes choosing a good commit trivial rather than guessing at random SHAs from months ago.

2. Use deterministic test commands - Flaky tests produce false positives during bisect, causing the algorithm to converge on the wrong commit. Isolate a single reliable test.

3. Start with a narrow range when possible - If you know the regression appeared sometime last week, use a commit from eight days ago as the good ref rather than a tag from six months back.

4. Inspect the result before reverting - Once bisect identifies the offending commit, review the diff carefully. The bug might be a side effect of an otherwise correct change that simply needs a guard clause.

5. Clean your working tree first - Uncommitted changes can interfere with checkout operations during bisect. Stash or commit before starting.

Common Issues

1. Test passes on both good and bad commits - Your test command may not actually exercise the regression. Verify the test fails on HEAD independently before starting bisect.

2. Bisect lands on a merge commit that cannot build - Use the skip-build-failures option or manually run git bisect skip to advance past unbuildable commits without corrupting results.

3. Session interrupted or terminal closed - Run git bisect log to see progress, then git bisect replay to restore the session from the saved log file.