Troubleshooting Mercurial hg bisect: Resolving False Positives and Execution Errors

The Problem: Unreliable Regression Tracking

When a bug appears in a codebase but the exact commit that introduced it is unknown, hg bisect uses a binary search to isolate the offending changeset. However, the process often fails when the search space contains merge complexities, repository corruption, or unstable test environments, leading to "no changeset found" errors or the identification of a revision that does not actually contain the bug.

Diagnostic Matrix: Common Bisect Failures

Symptom	Likely Cause	Primary Diagnostic Indicator
abort: no changeset found	Invalid range or missing history	Check hg log -r "good..bad" for empty output.
Incorrect changeset identified	Non-linear history or flaky tests	The identified revision is a merge commit or a test fails intermittently.
abort: repository corrupted	Index or store inconsistency	hg verify reports checksum mismatches.
Infinite loop/Slow progress	High branch density or complex merges	hg bisect keeps checking out similar revisions.

Step-by-Step Resolution Path

1. Validate the Search Range

Before starting a bisect, ensure the starting points are logically sound. If you mark a revision as "good" that actually contains the bug, or a "bad" revision that is actually functional, the binary search will fail to converge.

• Run hg log -r "good_rev..bad_rev" to ensure there is a continuous path of changesets between the two points.
• Verify that the working directory is clean. Uncommitted changes can bleed into every revision checked out by the bisect process, causing every revision to appear "bad."

2. Handle Repository Corruption

If hg bisect aborts with a corruption error, the issue is with the underlying store, not the bisect logic. This must be fixed before the search can continue.

1. Run hg verify on the local repository. This command checks the integrity of the changelog and data files.
2. If corruption is found, attempt to recover by pulling the affected revisions from a known healthy mirror or peer: hg pull [remote_url].
3. If the local store is unsalvageable, re-clone the repository and restart the bisect process.

3. Filter Out False Positives (Merge Commits)

In repositories with frequent merges, hg bisect may land on a merge changeset. If the bug was introduced in one of the parent branches but not the other, the merge commit might appear as the "first bad" revision, even though the actual logic error exists earlier in a feature branch.

Verification Strategy: When hg bisect identifies a revision, check if it is a merge: hg log -r [rev]. If it has multiple parents, manually test the parents individually to see which one carried the regression.

4. Resolving Execution Stalls

If the bisect process feels stagnant, it is often because the search is navigating a complex web of branches. To expedite this, use a scripted test if possible.

# Example: Running bisect with an automated test script
# Run this in the shell where hg is configured
# Required permissions: Execute permissions on the test script

hg bisect --good [good_rev] --bad [bad_rev]
# In a loop, run your test and mark results:
# ./run_test.sh && hg bisect --good || hg bisect --bad

Risk: Automated scripts can mark revisions as "bad" if the build fails for reasons unrelated to the regression (e.g., a compiler error). Always ensure the test script distinguishes between a failed test and a failed build.

Returning to a Stable State

Because hg bisect modifies the working directory by checking out various revisions, you must manually reset your state once the offending commit is found or the process is aborted.

Run the following command to return to the revision you were on before starting the bisect:

hg bisect --reset

If the command fails or you have manually updated the working directory, use hg update [original_rev].

Escalation Criteria

If the following conditions persist, the issue is likely an external environmental factor rather than a Mercurial tool failure:

• hg verify passes, but hg bisect consistently reports corruption.
• The same revision is marked "good" in one session and "bad" in another (indicates a flaky test or external dependency change).
• hg bisect --reset fails to restore the working directory, suggesting a locked repository or filesystem permission issue.