Git Basics: Finding a Broken Commit with Bisect

When an older version works and the current version fails, git bisect narrows down the first bad commit. Give Git a repeatable test and known good and bad endpoints.

Run these commands in Bash with Git 2.28 or newer installed. Start a fresh temporary repository for this article:

git_practice=$(mktemp -d) || exit
mkdir "$git_practice/repository"
cd "$git_practice/repository" || exit
git init -q -b main
git config user.name 'Practice User'
git config user.email 'practice@example.invalid'
git config commit.gpgsign false

The identity and signing settings apply only to this repository. Use your own identity in real projects. The temporary files remain afterward. Examples assume default Git settings; if a pager opens, press q to leave it.

Create a small history

printf 'ready
' > result.txt
git add result.txt
git commit -q -m 'Start with working output'
git tag known-good
printf 'Usage notes
' > README.txt
git add README.txt
git commit -q -m 'Add usage notes'
printf 'broken
' > result.txt
git add result.txt
git commit -q -m 'Break output'
printf 'More usage notes
' >> README.txt
git add README.txt
git commit -q -m 'Expand usage notes'
cat result.txt

broken

The test will check whether result.txt contains a line exactly equal to ready. It succeeds at known-good and fails at the tip of main.

Let Git run the test

Start with a clean working tree. Bisect checks out earlier commits, usually with a detached HEAD, while it searches. Avoid editing files during the search.

git status --short
git bisect start HEAD known-good > ../bisect.log
git bisect run grep -qx ready result.txt >> ../bisect.log
git show -s --format=%s refs/bisect/bad
git show refs/bisect/bad:result.txt

Break output
broken

The verbose search progress is saved in ../bisect.log; its commit IDs vary. Git found Break output as the first bad commit. Here, grep returns 0 for working output and 1 for broken output. Bisect treats 0 as good, 1–127 except 125 as bad, and 125 as untestable. Make sure setup failures cannot be mistaken for the bug.

Return to your branch

git bisect reset > /dev/null
git branch --show-current
git log -1 --format=%s

main
Expand usage notes

Git also prints checkout messages, including a variable commit ID, on standard error. Reset ends the bisect session and returns to the original checkout. It does not fix or undo the bad commit. Inspect the identified change and reproduce the failure before deciding how to repair it. Bisect works best when the tested behavior changes from good to bad without repeatedly flipping back.

References

git-bisect manual

Acknowledgements

This post was created with assistance from AI.