bisect Git Command Guide

The git bisect command uses binary search to find the commit that introduced a bug or regression. It efficiently narrows down the range of commits by marking good and bad commits to isolate the problem.

git bisect Syntax:

git bisect <subcommand> <options>
git bisect start <bad> [<good>...]
git bisect good [<rev>]
git bisect bad [<rev>]
git bisect skip [<rev>...]
git bisect reset [<branch>]

Subcommands:

Subcommand	Description
start	Start the bisection session marking bad/good commits
good	Mark commit(s) as good
bad	Mark commit(s) as bad
skip	Skip commits that are not testable
reset	End bisection and return to original branch
run	Automate good/bad marking with a script
log	Show bisect log
replay	Replay a bisect session from log
terms	Show current terms (good/bad)

Parameters:

Parameter	Description
rev	Commit hash or reference
cmd	Script or command to run during automated bisect

Caution

Bisect changes your HEAD; it checks out commits sequentially. Always start from a clean state and backup work if needed.

git bisect Command Samples:

Start bisecting between known good and bad commits

git bisect start HEAD v1.0

Starts bisect with HEAD as bad and v1.0 as good.

Mark current commit as good

git bisect good

Indicates the current commit is good (bug not present).

Mark current commit as bad

git bisect bad

Indicates the current commit has the bug.

Skip a commit that can’t be tested

git bisect skip

Moves to the next commit without marking good or bad.

Reset and return to original branch

git bisect reset

Ends the bisect session and returns to original HEAD.

Automate with a test script

git bisect run make test

Runs “make test” on each checked out commit and marks automatically.

Tip

Use git bisect log to save your progress. For rebase conflicts, consider git bisect —first-parent to follow main branch only.

How do I start a git bisect session?

To start a bisect session, use git bisect start followed by the bad commit and good commit:

git bisect start <bad-commit> <good-commit>

How do I mark a commit as good or bad during bisect?

During bisect, after checking out a commit, run git bisect good if the bug is not present, or git bisect bad if it is.

How can I automate the bisect process?

To automate, use git bisect run followed by a test command that exits with 0 if good, 125 if skip, or other for bad.

How do I end a bisect session?

To end the session and return to the original branch, execute git bisect reset.

What if some commits can’t be tested?

If a commit can’t be tested, use git bisect skip to move to the next one.

Applications of the git bisect command

1. Finding the commit that introduced a bug in the codebase
2. Identifying regressions introduced in new features
3. Locating the source of performance issues over time
4. Debugging when a test starts failing unexpectedly
5. Narrowing down problematic changes in large codebases
6. Tracing the origin of security vulnerabilities in commits