holocron/plugins/git/skills/git-history/references/bisect.md

topic, source_keys

topic	source_keys
bisect	git-scm-bisect-docs

Finding a commit with git bisect

Read this when the question is which commit changed the behaviour and there is no string, file, or line range to search the log for. Binary search reduces the trials from O(N) to O(log N).

Manual flow

rtk git bisect start
rtk git bisect bad [HEAD]        # mark current (or specified) as broken
rtk git bisect good <commit>     # mark known-good baseline
# Git checks out the midpoint; test it
rtk git bisect good              # test passes
rtk git bisect bad               # test fails
# Repeat until git reports "X is the first bad commit"
rtk git bisect reset             # return to the original HEAD

Automated

With a test command available, use rtk git bisect run <cmd>. Git reads the exit code: 0 good, 1–124 bad, 125 skip (build broken), 126–127 POSIX shell errors, treated as bad, and 128 or above aborts the session outright rather than marking the commit bad.

Untestable commits

rtk git bisect skip excludes a commit that cannot be built or tested without deciding good or bad for it. When the first bad commit is adjacent to a skipped range, bisect reports that it cannot pinpoint the culprit and lists the candidates — that is the precise answer the skip range allows, not a failure.

Undoing a wrong good/bad call

rtk git bisect log prints the session's decision history. Save it, edit out the mistaken entry, and resume from the corrected log rather than restarting the search:

rtk git bisect log > bisect.log
# edit bisect.log, removing the wrong decision
rtk git bisect reset && rtk git bisect replay bisect.log

Narrowing and speeding up

• rtk git bisect start HEAD v1.2 -- src/ restricts bisection to a path, cutting the trial count.
• --no-checkout updates the BISECT_HEAD ref instead of checking out a working tree — useful for tests that do not need one, and automatic in bare repos.
• --first-parent follows only first parents at merges, finding the integration commit that introduced a regression while ignoring broken side branches.

Inspecting the remaining candidates

rtk git bisect visualize (alias view) opens the suspects in gitk, falling back to git log when no graphical display is detected. Add --stat or -p for a diffstat or full patches.

Hunting a non-bug property change

rtk git bisect start --term-new <new> --term-old <old> searches for any property change — a performance regression, say — instead of a bug. Use the custom terms in place of good and bad for the rest of the session.

Once the first bad commit is identified, return to Step 3 to act on it and Step 4 to report it.