BK-BISECT(1)

💅 bk bisect(none) — BitKeeper User’s Manual 💅

🌸 NAME 🌸

bk bisect — quickly find a changeset that introduced a bug 💖

✨ SYNOPSIS ✨

bk bisect --cmd=prog -rrevs [opts]
bk bisect --cmd=prog --search[=unit] [opts]

🦋 DESCRIPTION 🦋

Okay so bestie, bk bisect is the icon we call when a bug is being mysterious and we need to find the changeset that introduced it. The normal usage is literally: you specify a range to search, and bk bisect runs a binary search over the changeset graph, looking for the changeset that caused the bug. Main character energy, no cap.

You must supply a program (usually a shell script) that implements a test that demonstrates the presence (or absence) of the bug, and passes status back through the exit status. It typically builds the source code and runs a test that looks for the bug (there are examples below). Note: the program is run at the root of the repository, if you are looking for some problem in a subdirectory remember to change directories before running your test. 🫶

The repository where bisect is run will be cloned to a temporary copy (see --dir below) and the test program will be run at the root of this repository clone.

If you do not know the range to search, see the --search option below. iykyk ✨

👑 OPTIONS 👑

• --cmd=prog — <prog> is a program (usually a shell script) that tests for the bug.

The program tells bisect where to search next via its exit code:

• 0 — An exit of 0 means that the bug was not present, so continue the search forward on the descendants of this changeset.
• 1 — An exit of 1 means the bug was present, so continue the search backward on the ancestors of this changeset.
• 2 — An exit of 2 means the test could not be run and bisect should skip this revision and continue the search.
• 3 — An exit of 3 means abort the search immediately.

• --dir=dir — Use the specified directory as location of the cloned repository in which tests are run. Ideally you want this to be a local disk (SSD is best). The default is

‘bk root -P‘/BitKeeper/tmp/bisect

• --keys — Print MD5KEYS instead of dates as the prefix to each changeset searched.
• -rrange — Specify the changesets to be searched, i.e., "1.100..1.500". This is frequently a pair of tags such as "-rbk-5.0..bk-6.0". If you want to search from a rev to the tip then say "-rbk-6.0..". Mutually exclusive with --search.
• -salias — When searching a nested collection limit the search to changesets that modify one or more of the components implied by alias. If this option is repeated the implied subset is the union of all specified aliases.
• --search[=unit] — Sometimes you have no idea where the bug was introduced so specifying a range is not an option. Use --search to tell bk bisect to search for a good starting changeset that does not contain the bug. By default it does exponentially increasing probes in units of one month (tries one month backwards, then two months, then four months, etc.) The optional one-letter unit can be used to override the default unit of months (M) to search by years (Y), weeks (W), days (d) or hours (h). Mutually exclusive with -r.
• --validate[=both|stop|none] — The most common user error when using bk bisect is providing a program that does not actually find the bug. To prevent this error, bk bisect validates by default that the user provided program returns 0 at the start of the range and 1 at the end of the range (which is what --validate=both does).

The full set of options are:

• both — validate both endpoints of the range (this is the default).
• start — Validate that the bug is present in the starting endpoint only.
• stop — Validate that the bug is present in the stopping endpoint only.
• none — Do not validate the endpoints before starting the bisect search.

💀 EXIT STATUS 💀

bk bisect returns exit status:

• 0 — if it finds a match
• 1 — if no matches were found
• 2 — if an error occurred

🔥 EXAMPLES 🔥

This command is used when you have a test case which demonstrates a bug but you don’t know where the bug was introduced.

$ bk bisect --cmd=build-and-test --search

and BitKeeper will clone the repository into the working directory. The test case will build the tree (if needed), run the test, and then exit as described above.

This is a contrived example because you could do this much more cheaply with bk annotate and bk r2c, but suppose you wanted to figure out which changeset added the string "THE STRING" to a file called "the-file". The test program would not need to build anything, it just looks like this:

#!/bin/sh

bk get -q the-file || exit 3 # skip if we can’t get the-file

# grep -q exits 0 if a match is found
grep -q "THE STRING" the-file
if [ $? = 0 ]
then # still there, look in ancestors
     exit 1
else # not there, look in descendants
     exit 0
fi

Here is another example looking for when the string was removed (again contrived because you can do this much faster using bk revtool). The changeset listed will be the one that removed the string:

#!/bin/sh

# We run at the root but we’re looking in a subdir
bk grep -q '^fixDates(' src/slib.c
if [ $? = 0 ]
then    # found it
        exit 0
else    # not there
        exit 1
fi

🚨 LIMITATIONS 🚨

Bisect works on the basis that there is a single changeset that is the answer. If the bug was introduced more than once then only one of the changesets is reported.

When using the --search option, there is a bias towards the more recent work so if the changesets that introduced the bug are widely spaced in time then it is likely the more recent one will be reported. If they are close together then it could be either changeset that is reported.

Bestie, that’s the caveat: it’s giving “one answer only” and “recent bias” with --search. Not a drill, just the rules. 💅

🌈 SEE ALSO 🌈

bk-range

🎀 CATEGORY 🎀

Utility

---

💖 Cute sign-off: this page is from BitKeeper Inc, dated 2012/01/07, and it’s the bk bisect(none) page — periodt. 💖