Carla opens an issue with an uncomfortable title: "The delete task button does not delete anything". She reproduces it in three browsers. You click the bin, the task flickers and it is still there.

The baffling part is that it used to work. In version v1.0.0, which the team tagged two months ago (lesson 05-05), deleting worked perfectly: there is a recorded demo that proves it. Between that tag and main there are 214 commits.

The obvious options are bad ones. Reading through 214 diffs is a day's work and a guarantee of seeing nothing. Searching by keyword with git log -S "delete" (lesson 02-06) gives twenty-odd candidates, and none of them looks guilty. And asking in the team chat only produces theories.

But there is a property of the problem that changes everything: the history is ordered, and at some point in that sequence the behaviour went from "works" to "does not work". That is exactly the scenario for a binary search, and Git ships a built-in implementation: git bisect. With it, those 214 commits come down to eight tests.

1. The idea: binary search over the history
2. How many steps are really needed
3. A complete manual session
4. git bisect skip: commits that cannot be tested
5. git bisect log and replay: not losing the work
6. Automating with git bisect run
7. The test script for task-manager
8. The exit codes, in detail
9. --first-parent: skipping the inside of merges
10. git bisect terms: when it is not "good/bad"
11. What makes a history bisectable

bisect has one single premise:

There is one specific commit from which the behaviour changed. Before it, fine; from it onwards, broken.

If that holds, there is no need to test the commits one by one. It is enough to test the middle one:

• If the middle one is bad, the culprit is in the first half. The second half is discarded entirely.
• If the middle one is good, the culprit is in the second half. The first is discarded entirely.

And you repeat over the half that remains. Every test eliminates half the candidates.

Git does all the logistical work: it works out which commit to test, does the checkout for you (in detached HEAD, lesson 03-02), keeps count of what has been discarded and at the end tells you the exact hash. All you do is answer one binary question at each step: does it work or not?

The number of tests is the base-2 logarithm of the number of candidates, rounded up. The difference with a linear search is brutal and deserves seeing in a table:

That is the headline: doubling the size of the history adds one single test. A repository with a million commits is bisected in twenty steps. It is the reason bisect remains useful however large the project gets.

Git itself tells you this when you start:

"106 revisions left to test, roughly 7 steps". It is not an optimistic estimate: it is mathematics.

Carla begins. First of all, leave the working tree clean: bisect is going to do a lot of checkouts, and it cannot if there are uncommitted changes. If she has any, git stash (lesson 05-04).

Step 1: start the session.

It answers nothing. Git has entered bisection mode: it has created internal references in .git/refs/bisect/ and a .git/BISECT_LOG file.

Step 2: mark the two ends.

Note what has happened: Git has checked out the middle commit. Carla's working tree is now that of commit 9f3c7a1, and HEAD is detached:

Step 3: the loop. Carla opens index.html in the browser, creates a task, clicks the bin:

It works. She marks it:

From 106 to 53 in one go. And so on:

Carla carries on: good, bad, good, bad… Five tests later:

Eight tests. 214 commits. A culprit with a name, a date and a diff.

Step 4: look at the diff.

There it is. Bruno swapped the individual listeners for event delegation on the container, which is a legitimate improvement. But the delete button contains an <svg> with the bin icon, so when you click, e.target is the <svg>, not the button: classList.contains('delete') gives false and nothing happens. With e.target.closest('.delete') it would work.

Without bisect, finding that would have taken hours. With it, eight tests and a twelve-line diff.

Step 5: exit. And this step is not optional:

reset cleans up the bisection state and returns HEAD to where it was when you started. If you forget, you are left in detached HEAD on an old commit, and the next git status will be an unpleasant surprise.

Summary of the session's commands:

The starting shortcut saves two commands and is the one used in practice:

On the sixth test, Carla runs into this:

That commit is broken for another reason. It is not that deleting does not work: it is that the whole application does not start. Marking it bad would be lying to bisect and could lead it down the wrong path; marking it good, worse still.

The correct answer is:

skip tells Git: "this commit gives me no information". Git picks another nearby candidate and carries on. If you end up skipping too many and it cannot isolate a single one, it will tell you:

In that case it gives you a small set of suspects, which is already infinitely better than 214.

You can also skip whole ranges, if you know that an entire zone does not build:

Usual reasons for skip: the commit does not build, dependencies are missing that were not yet in the package.json, or the commit is a massive reformatting change that makes it impossible to run anything. skip is your friend; lying to bisect is not.

Halfway through a long bisection anything can happen: you mark something wrongly, the terminal closes, or you have to deal with something else. git bisect log saves the session:

Saving it and picking it up later:

replay rebuilds the session up to where you got to and leaves you on the next commit to test.

And here is its other use, the most valuable one: correcting a marking mistake. If you realise you said good where you should have said bad, there is no need to start from scratch:

The manual session works, but eight rounds of "open the browser, create a task, click, mark" are eight opportunities to get it wrong and twenty minutes of Carla's life.

If the check can be written as a command that returns 0 when things are fine and something other than 0 when they are not, git bisect run does the whole thing by itself:

Git tests, runs the command, interprets the exit code, marks, moves on and repeats until it finds the culprit. With no human intervention.

With a test suite, it is literally this:

And for a single case, a one-line command may be enough:

grep -q returns 0 if it finds something, 1 if not. It is exactly the contract bisect run expects.

Since Carla's fault is a behaviour in the browser, a somewhat more elaborate script is needed. The team has an automated test with Node:

And the test itself, which simulates the minimum DOM needed:

The three points that make this script work well with bisect:

1. It tests one single thing. Only deletion. If the test also failed for other reasons, bisect would find the first commit that breaks anything, which is not what we are after.
2. It distinguishes "does not work" from "cannot be evaluated". That is the role of 125, and it is what we shall see now.
3. It is silent and deterministic. No interactive output, no dependence on the network, no intermittent failures. A test that fails sometimes poisons the entire bisection.

Running it:

Forty seconds, without touching the keyboard. And a warning about the #!: the script must be executable (chmod +x) and be outside the working tree or present in every commit. If it lives inside the repository and did not exist in the old commits, bisect will not find it when it checks those commits out. The usual solution is to copy it to /tmp and run it from there:

This is the complete contract of git bisect run, and knowing it is the difference between an automation that works and one that gives false results:

Three practical consequences:

• 125 is the key piece. It is the automatic equivalent of git bisect skip. Without it, a commit that does not build would be marked "bad" and bisect would point you at the wrong culprit.
• 126 and 127 are deadly traps. If the script is not executable or the path is wrong, bisect will mark every commit as bad and will "find" the first one in the range as the culprit. If the result looks absurd to you, first check that the script runs by hand: ./my-script.sh; echo $?.
• Avoid exit 128 and above. A kill -9 of a process gives 137, for example. If your script can end that way, wrap it to normalise the exit code.

A mandatory preliminary check, always, before launching a bisect run:

Thirty seconds that stop you bisecting for ten minutes towards an invented answer.

task-manager's history has merges (lesson 03-03), and by default bisect explores all reachable commits, including the internal ones of each merged branch. That has two drawbacks:

• The intermediate commits of a branch under development are usually half-finished: they may not even build, and you end up doing a lot of skips.
• As far as main is concerned, what matters is which merge the problem came in through, not which of the branch's six commits introduced it.

With --first-parent, Git only considers the mainline: main's direct commits and the merge commits, without going inside the branches. It is exactly the same --first-parent concept that we shall see in git log in lesson 06-04, and the same "first parent" that -m 1 was choosing when reverting a merge (lesson 05-06).

Without --first-parent, the candidates are a1, f1, f2, f3, a2, M1, a3. With --first-parent, only a1, a2, M1, a3.

When to use each:

The two-phase tactic gets the best of both: first --first-parent to identify the merge, then a second bisection inside that branch:

M1^2 is the second parent (the tip of the merged branch) and M1^1 the first (the base on main), with the notation from lesson 02-06.

bisect is not only for hunting regressions. It serves to locate any monotonic change of state in the history. The typical examples:

• In which commit was a bug fixed? (here "good" and "bad" are inverted)
• In which commit did start-up go from taking 200 ms to 900 ms?
• In which commit did the bundle go from 400 KB to 1.2 MB?

In those cases, the default terminology is confusing. git bisect terms lets you rename it:

From then on, at each step you answer git bisect broken or git bisect fixed, and Git looks for the first fixed commit.

What has to be understood is that Git does not care about the words: it always looks for the first commit with the "new" state, be that "broken", "fixed", "slow" or "fat". To check the active terms at any moment:

A performance example, measuring with the script itself:

The script's last line is the one that decides: [ "$bytes" -lt 512000 ] returns 0 if it holds and 1 if it does not, which is exactly the contract of bisect run.

bisect is a tool that gives you back what you gave it. Its effectiveness depends directly on the quality of the history, and that is where module 5 and this one join hands:

Put another way: the interactive rebase from lesson 05-02 is not cosmetics. When you consolidate the fixup!s, split a giant commit and make sure each one leaves the project in a working state, what you are building is a bisectable history. The bill for not doing it is paid on the day a two-month-old regression has to be found.

And with --exec (lesson 05-02) you can check in advance that an entire branch is bisectable before integrating it:

Git applies each commit and runs the check on each one. If any of them fails, it stops you there.

All of this — atomic commits, a history that builds, what to consolidate before integrating — is the subject of lesson 08-02: Keeping a Clean History. bisect is the best practical justification there is for those practices: it turns an abstract virtue into minutes of work saved.

One last note on scope: bisect answers "which commit changed this behaviour?". It does not answer "why is my repository in a strange state?" nor "what is Git doing underneath?". That diagnosis — reflog, fsck, GIT_TRACE and company — is the territory of the module 9 lessons, and in particular of 09-06: Advanced Debugging Techniques.

Mistake 1: starting with a dirty working tree. bisect does a checkout at every step and will either fail or drag your changes between commits. Commit or git stash beforehand.

Mistake 2: forgetting git bisect reset. You are left in detached HEAD on a commit from June. Every commit you make there will end up orphaned.

Mistake 3: inverting good and bad at the start. The order in the shortcut is git bisect start <BAD> <GOOD>. If you invert it, Git will search in the opposite direction and will not find anything coherent.

Mistake 4: marking as bad a commit that is broken for another reason. Use skip. Lying to bisect produces a wrong culprit with every appearance of being the right one.

Mistake 5: forgetting the exit 125 in the script. Without it, commits that do not build count as bad and the result is rubbish.

Mistake 6: a script that is not executable or has the wrong path. Codes 126/127: everything comes out "bad" and the culprit is the first commit in the range. Test the script by hand first.

Mistake 7: leaving the script inside the repository. In the old commits it may not exist. Copy it to /tmp and run it from outside.

Mistake 8: a non-deterministic test. If it fails one time in five, bisect will give you a different answer each time. Ensure determinism before automating.

Tip 1: choose the most recent "good" you can. Starting at v1.0.0 rather than at the project's first commit saves steps. Tags (lesson 05-05) are perfect for this.

Tip 2: always save git bisect log. A long session is valuable work. A text file lets you resume it or correct a wrong marking.

Tip 3: first --first-parent, then inside the branch. Fast for locating the merge, precise for locating the commit.

Tip 4: bisect run with npm test is often enough. If you already have tests, do not write anything new.

Tip 5: when you find the culprit, do not blow it up without thinking. Look at it, understand it and decide: git revert if it is published (lesson 05-06), or a fix going forward if the change itself was good and only a detail was missing — as in Bruno's case, where the event delegation was correct and only closest() was missing.

Create a repository with 15 commits where the file value.txt contains 10, and from commit number 9 onwards it contains 99 (the "fault"). Then:

1. Start a bisection with main as bad and the first commit as good.
2. At each step, check cat value.txt and mark good or bad.
3. Check that Git identifies exactly commit 9.
4. How many steps did you need? Does it match log₂(14)?

With the same repository as in exercise 1:

1. Write a script in /tmp that returns 0 if value.txt contains 10 and 1 if it does not.
2. Test the script by hand on a good commit and on a bad one before using it.
3. Launch git bisect run and check that it finds the same commit.
4. Add to the repository an intermediate commit in which value.txt does not exist, and make the script return 125 in that case. Check that the bisection still works.

Create a repository of 10 commits where state.txt contains broken and from commit 7 onwards contains fixed. Using --term-old and --term-new, find the first fixed commit. Also write the corresponding bisect run.

Solution 1:

Four tests for 14 candidates. log₂(14) ≈ 3.8, which rounded up is 4. Exactly right.

Solution 2:

The preliminary check, which must never be skipped:

The untestable commit:

When the bisection reaches the commit with no value.txt, the script returns 125 and Git skips it:

The culprit is still commit 9: the 125 has stopped an untestable commit from falsifying the result.

Solution 3:

With automation:

The important thing: even though the terms are called broken and fixed, the script still returns 0 for the old state and 1 for the new one. bisect does not interpret the words; it only looks for the boundary.

git bisect turns a desperate search into a mechanical, bounded procedure. The essentials:

• It is a binary search over the history: each test discards half the candidates, so log₂(n) tests are needed. 214 commits are 8 tests; a million, twenty.
• The manual session is start → bad → good → the testing loop → reset. The final reset is not optional: without it you are left in detached HEAD.
• git bisect skip is the honest answer to a commit that cannot be evaluated. Lying by marking good or bad produces a false culprit.
• git bisect log and replay save long sessions and let you correct a wrong marking without starting from scratch.
• git bisect run <command> automates the whole process. The contract is the exit codes: 0 good, 1–124 bad, 125 skip, 128+ abort. The 125 is what separates a reliable automation from one that invents answers.
• Always test the script by hand on a good commit and on a bad one before launching bisect run, and take it out of the working tree (/tmp) so that it exists in every commit.
• --first-parent limits the search to the mainline: less noise and fewer skips. The two-phase tactic — the merge first, then inside the branch — combines speed and precision.
• git bisect terms generalises the tool to any monotonic change of state: when something was fixed, when it started running slowly, when the bundle put on weight.
• And the underlying conclusion: a history of small commits that build is a bisectable history. Lesson 08-02 develops this; bisect is the reason it matters.

Carla now has the guilty commit and the exact diff. But on looking at app.js to fix it she finds something else: twenty lines further down there is a text normalisation function that nobody knows the purpose of, with a replace of odd characters that looks arbitrary. Nobody on the team remembers writing it. Deleting it looks tempting… and would probably break something.

Before touching code you do not understand, you need to know who wrote each line, when and in which commit, so that you can read the message that explains why. That is the tool of lesson 06-03: Git Blame.