glossary

Git Bisect

A git command that uses binary search to find the specific commit that introduced a bug, by repeatedly halving the range of suspect commits.

explanation

Git bisect is one of the most powerful debugging tools in version control. You mark a known-good commit and a known-bad commit, and git uses binary search to narrow down the commit that first introduced the bug. In each step, git checks out a commit in the middle of the range, and you mark it as good or bad after testing. With N commits in the range, bisect finds the culprit in log2(N) steps — finding a bug among 1000 commits takes about 10 steps. The process can be automated with git bisect run, which takes a script or command that exits with 0 (good) or non-zero (bad). This is especially powerful with a comprehensive test suite: git bisect run npm test will automatically find the commit that broke the build. The effectiveness of bisect depends directly on commit quality. A series of atomic commits with clear, single-purpose changes makes bisect precise: the bad commit will cleanly isolate the change that introduced the bug. A large "mega-commit" that mixed multiple changes will be identified as the culprit even if only one of its changes caused the bug, forcing you to debug within the commit.

examples

git bisect start # begin a bisect session

git bisect good abc1234 # mark a known-good commit

git bisect bad HEAD # mark the current commit as bad

git bisect bad # mark the current checkout as containing the bug

git bisect run npm test # automate bisect with a test script

how git-agent helps

git-agent's atomic commits dramatically improve bisect precision. Because each commit contains exactly one logical change, when bisect identifies a commit as the bug-introducer, you know the exact change responsible. No more digging through mega-commits to find which change broke things.

brew install gitagenthq/brew/git-agent

FAQ

Can bisect find a bug across merge commits?

Yes, though merges can complicate the search. git bisect can skip merge commits that are not easily testable. Use git bisect skip to skip a commit that cannot be tested (e.g., due to build failures unrelated to the bug).

How many steps does bisect take for 5000 commits?

Approximately 13 steps. Bisect halves the range each time, so it takes ceil(log2(N)) steps. For 5000 commits, log2(5000) ≈ 12.3, so 13 steps at most.

Does git-agent integrate with git bisect?

git-agent is a commit authoring tool, not a bisect tool. It produces the kind of high-quality atomic commits that make bisect most effective. The actual bisect workflow is done with standard git bisect commands.

Atomic commits Git reflog Git rebase