Buildroot Git Bisect: Hold Defconfig, Downloads and Toolchain Inputs Constant

A Buildroot Git bisect is useful only when “good” and “bad” describe the same test throughout the search. If the board setup, product customization, host tools or build outputs change between revisions, the result may identify an environmental change rather than the regression you wanted to isolate. Design the test boundary before starting the commit search.

The workflow below is a proposed investigation method. It does not report a completed bisect or a measured product failure. The Buildroot-specific rebuild guidance was checked against the 2026.08 manual; an older range may require its own configuration and host-compatibility checks.

Define one observable failure

Write a test statement that another engineer can apply. “The image is broken” is too broad. A useful hypothetical criterion is: after a controlled boot, a named service must produce a particular response within a declared observation window. Record the board revision, connected peripherals, firmware-loading method and test input.

Decide what makes an attempt invalid. A disconnected test fixture, unavailable source server or host disk exhaustion should not automatically become evidence of the target regression. Conversely, if the regression under investigation is a build failure, that same reproducible compiler failure may be precisely the bad outcome. Classification depends on the question, not merely on whether a command failed.

Reproduce both endpoints first

Choose a known-good and a known-bad Buildroot revision. Test both using the same documented product inputs and procedure before allowing the search to select intermediate revisions. If the good endpoint no longer passes, investigate that mismatch first. A remembered result from another workstation is not an equivalent endpoint observation.

The Git bisect manual describes the good/bad search, skipped revisions and recording the session. Use a dedicated investigation checkout or worktree so the search does not disrupt unrelated development. Git worktree documentation explains the separate working-tree mechanism; it does not isolate external build outputs for you.

Keep a short endpoint report: source commit, resolved configuration checksum, external-tree revision, toolchain identity, output image checksum and observed test result. If any item differs intentionally between endpoints, explain why that difference belongs to the investigated change.

Hold external inputs fixed, but let the tested commit matter

Keep the product's external-tree revision fixed unless that repository is the thing being bisected. Preserve the chosen defconfig and capture the resolved configuration at each revision. A renamed option or changed default deserves review; do not force an old resolved configuration into a new release and assume the product still means the same thing.

There is an important distinction between controlling external inputs and freezing every package version. A Buildroot commit may intentionally change a package or internal toolchain recipe. That change is part of the object being tested. Overriding it merely to keep versions identical can remove the regression from the experiment.

Keep the host environment stable, and pin an external toolchain if the product uses one. Preserve required download artifacts and integrity evidence so a temporary upstream outage does not become a false bad result. Record exceptions rather than silently switching a mirror, dependency revision or compiler halfway through the search.

Separate source selection from build state

Checking out another Git revision does not clear the generated files from a previous Buildroot build. The Buildroot rebuild guidance explains that configuration changes do not trigger complete dependency-aware rebuilding. Architecture and toolchain changes are examples where a full rebuild is needed.

For an uncertain regression range, independently initialized output directories are often a clearer investigation choice than relying on incremental state. This costs time and storage, so plan it deliberately. Retain failed logs and image checksums before discarding any temporary outputs. A shared source-download cache is different from a shared compiled-output tree; document which material you reuse.

The 2026.08 Makefile shows how the selected output location controls build directories. Give each attempt an identity tied to its tested commit and run number. A directory called “latest” makes accidental reuse harder to notice.

Map outcomes before automating

For automated bisection, the Git exit-code contract uses zero for good, 125 for an untestable revision, and other values from one through 127 for bad. Higher exit statuses abort the search. A missing command can therefore be misclassified if the test wrapper blindly forwards its exit status.

Use an explicit result map in the harness:

• Valid test passes the declared criterion: classify good.
• Valid test reproduces the target failure: classify bad.
• Independent prerequisite prevents a meaningful test: classify untestable and retain the reason.
• Harness integrity is uncertain: stop the automated investigation rather than collecting misleading votes.

These categories are an engineering recommendation, not a supplied production script. Test the wrapper with deliberately simulated outcomes before granting it control of a long build sequence. Intermittent behavior needs a predeclared repetition rule and observation window; choosing repetitions after seeing a result biases the search.

Confirm the boundary, not just the printed answer

When the search identifies a candidate change, rebuild and retest the relevant boundary with the same recorded procedure. Inspect the patch and ask whether it plausibly explains the observed failure. A nearby skipped revision can leave several possible first-bad commits, so preserve that ambiguity in the report.

Save the bisect log, attempt records, test definition and limitations. If a corrective patch is proposed, qualify it separately; identifying a boundary does not prove a fix is complete. The useful deliverable is a reviewable causal investigation with a reproducible test, not simply a commit hash that appeared at the end of a command.