bk bisect(7.3ce-rc1)        BitKeeper User's Manual       bk bisect(7.3ce-rc1)

NAME
       bk bisect - quickly find a changeset that introduced a bug

SYNOPSIS
       bk bisect --cmd=<prog> -r<revs> [<opts>]
       bk bisect --cmd=<prog> --search[=<unit>] [<opts>]

DESCRIPTION
       The bisect command is used to find the changeset that introduced a bug.

       The normal usage is to specify a range to search and bk bisect will run
       a binary search over the changeset graph,  looking  for  the  changeset
       that caused the bug.

       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  directo-
       ries 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.

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 change-
                         set.
                    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.
       -r<range>    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".
       -s<alias>    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 expo-
                    nentially 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 over-
                    ride  the  default  unit  of months (M) to search by years
                    (Y), weeks (W), days (d) or  hours (h).   Mutually  exclu-
                    sive with "-r".
       --validate[=<both|stop|none>]
                    The most common user error when using bk bisect is provid-
                    ing 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 --vali-
                    date=<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.

SEE ALSO
       bk range

CATEGORY
       Utility

BitKeeper Inc                     2012/01/07              bk bisect(7.3ce-rc1)