The search assumes 1 thing: somewhere in the range the behavior flipped & stayed flipped. Old commits pass, new commits fail, exactly 1 transition. Under that assumption binary search is optimal & exact.

Real history breaks the assumption 2 ways. The behavior flipped more than once, fixed & re-broken. Or it drifted gradually with no single commit responsible. crux detects both. Multiple transitions and it switches to ranked mode: every commit gets tested, each failing commit scored on evidence (flip boundary, recency, size), and you get a ranked list. A wrong single answer is worse than an honest list.

binary search animation: the candidate window shrinks each step until only the flip commit remains

what it costs

2 runs to establish the flip, then 1 run per binary search step. Cost grows logarithmically: 10,000 commits is about 15 runs. The parallel flag trades the logarithmic search for full coverage across worktrees, worth it only when 1 test run costs seconds.

bar chart of test executions per scenario for git bisect versus crux across the benchmark campaign
Your tree comes back the way you left it

Every path that mutates the working tree restores the original HEAD. Minimization probes apply patches onto throwaway parent checkouts and clean up. ctrl+c mid-probe, and a git checkout of your branch fixes any residue.

edit this page