git bisect

Debugging

Find the commit that introduced a bug by binary search


The 'git bisect' command finds the commit that introduced a bug. You mark one commit bad (has the bug) and one good (does not); git checks out the commit in the middle, you test it and answer good or bad, and git halves the suspects again until only one is left. Even a thousand commits take only about ten tests. git bisect reset brings you back to where you started.

Synopsis

git bisect start [<bad> [<good>...]]
git bisect (bad | good) [<rev>...]
git bisect skip [<rev>...]
git bisect reset
git bisect log
git bisect run <cmd>...
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (4)

Start a session; optionally give the bad commit and then the good ones directly.

RecommendedSkip two commands: name bad and good at once

Example

git bisect start HEAD v1.0

The current commit cannot be tested; pick another one.

When neededMove on when a commit cannot be tested

Example

git bisect skip

Show every command and answer of the current session.

When neededReview or replay a bisect session

Example

git bisect log

End the session and return to the branch you started from.

RecommendedAlways end a bisect session with it

Example

git bisect reset

Advanced (1)

Run a command on each candidate: exit code 0 = good, 1–127 = bad, 125 = skip.

RecommendedFully automatic bisect with a test script

Example

git bisect run npm test

Choosing the Right Option

Tests needed

Binary search halves the suspects each time

Commandbisect tests
10 commitsabout 4
100 commitsabout 7
1000 commitsabout 10

Examples

Start a session

git bisect start

Begin the search.


Mark commits

git bisect bad && git bisect good v1.0

Current commit is bad, v1.0 was good.


Automate

git bisect run npm test

Let a test script answer for you.


Finish

git bisect reset

Back to your branch.

Workflow Examples

1
git bisect start HEAD v1.0

Bad now, good at v1.0

2
git bisect good / git bisect bad

Test each commit git checks out

3
git bisect reset

Back to your branch

4
git revert <first-bad>

Undo the culprit

Troubleshooting

You need to start by "git bisect start"

Cause: No session is running

Run git bisect start first

Wrong answer given

Cause: Every later step is based on it

git bisect log > log.txt, fix the line, git bisect reset, git bisect replay log.txt

Tips & Pitfalls

Best Practices

  • ✓Write an automatic test and use git bisect run.
  • ✓Always finish with git bisect reset.

Common Mistakes

  • ✗Answering the wrong way once — every later step is then wrong (check with git bisect log).
  • ✗Forgetting git bisect reset and continuing to work on a detached HEAD.
  • ✗Starting with uncommitted changes that get in the way of checkouts.

FAQ

A:

Yes: git bisect start --term-old=fast --term-new=slow, e.g. to find when something got slow.