Git Bisect

Q: What if a commit cannot be tested during git bisect?

Run git bisect skip and Git will pick a nearby commit instead. If too many commits are skipped, Git may only be able to report a small range of possible culprits.

Q: What is the difference between git bisect and git blame?

git blame shows which commit last changed each line of a file, while git bisect searches history for the commit where a behavior broke. Use blame when you know the suspicious line, and bisect when you only know that something used to work.

Pronunciation: git by-SEKT

Updated September 30, 20262 min read

In short

Git bisect is a Git command that uses binary search through commit history to find the exact commit that introduced a bug, testing only a few commits.

What is git bisect?

Git bisect is a debugging command that finds which commit introduced a bug. You tell Git one commit where the code was good and one where it is bad, and Git checks out a commit halfway between them for you to test. After you mark it as good or bad, Git halves the range again, until only the first bad commit remains.

Because it uses binary search, git bisect needs very few steps: about 10 tests are enough to search 1,000 commits, and about 20 for a million. You can mark commits by hand with git bisect good and git bisect bad, or automate the whole process with git bisect run followed by a script that exits with 0 when the code works and a non-zero code when it fails. When you are done, git bisect reset returns you to the branch you started on.

It is like finding the page where a typo first appeared in a long book by opening it in the middle, checking, and then only searching the half that must contain it. Git bisect is especially useful for regressions, which are bugs in features that used to work, when nobody knows which of many recent changes broke them.

Git bisect is sometimes confused with git blame. Blame shows who last changed each line of a file, which helps when you already know where the bug lives, while bisect finds the commit that caused the behavior even when you have no idea which file is involved. Bisect works best when every commit builds and passes basic tests, which is one reason teams value small, self-contained commits.

Key takeaways

Git bisect finds the first commit that introduced a bug.
It uses binary search, so the number of steps grows very slowly with history size.
You mark commits with git bisect good and git bisect bad.
git bisect run automates the search with a test script.
Always finish with git bisect reset to return to your branch.

Example

Finding the commit that broke the testsbash

# Start a bisect session
git bisect start
git bisect bad                 # the current commit has the bug
git bisect good v2.3.0         # this older tag was working

# Git checks out a commit in the middle: test it, then mark it
git bisect good                # or: git bisect bad

# Or let a script decide automatically (exit 0 = good, non-zero = bad)
git bisect run npm test

# Return to where you started
git bisect reset

Readers ask

What does git bisect do?

It helps you find the exact commit that introduced a bug by repeatedly checking out a commit halfway between a known good and a known bad version. You test each one and mark it, and Git narrows the range until only the culprit remains.

What if a commit cannot be tested during git bisect?

Run git bisect skip and Git will pick a nearby commit instead. If too many commits are skipped, Git may only be able to report a small range of possible culprits.

What is the difference between git bisect and git blame?

git blame shows which commit last changed each line of a file, while git bisect searches history for the commit where a behavior broke. Use blame when you know the suspicious line, and bisect when you only know that something used to work.