bk changes(7.3ce)           BitKeeper User's Manual          bk changes(7.3ce)

NAME
       bk changes - show changeset history

SYNOPSIS
       bk changes [<options>] [-r<revs> | -]
       bk changes [<options>] <repo> [<repo> ...]
       bk changes -L [<options>] [<repo> ...]
       bk changes -R [<options>] [<repo> ...]
       bk changes -L -R [<options>] [<repo> ...]

DESCRIPTION
       The changes command is used to get an overview of the changes made to a
       repository.  There are options to  search  for  particular  changesets,
       view  only  tagged  changesets,  limit the search to a particular user,
       view only local changes, view only remote changes, view  changes  rela-
       tive to a set of repositories, etc.

       =>  The  first  form shown above shows changes in the local repository.
           If the last argument is a "-" then the revisions to be  listed  are
           specified, as keys, tags, and/or revisions, on stdin.
       =>  The second form shown above shows changes in the named repository.
       =>  The third form shown above lists changes found in the local reposi-
           tory but not in the remote repository.  If the remote repository is
           not  specified,  the  outgoing  parent[s]  of  the local repository
           is/are used, i.e., the listing is what would  be  sent  on  a  push
           (when used with "-a").
       =>  The  fourth  form  shown  above  lists  changes found in the remote
           repository but not in the local repository.  If the remote  reposi-
           tory  is not specified, the incoming parent[s] of the local reposi-
           tory is/are used, i.e., the listing is what would be received on  a
           pull (when used with "-a").
       =>  The  fifth  form  shown  above  lists  changes unique to either the
           remote or the local  repository.   The  local  changes  are  listed
           first,  then  the  remote  changes, and both sets of changes have a
           title line to separate them.

       In all but the second form, the changes command must be run from within
       a  repository,  and  that  repository is the local repository while the
       named repository is the remote repository.   All  the  other  selection
       options are applied to the list of local or remote only changesets.

       The  changesets  to  be listed may be limited to a revision, a range of
       revisions, the last (or first) N changesets, or a list of revisions  on
       stdin.   The  default is all revisions.  Specifying revisions is incom-
       patible with the "-R/-L" options.

OPTIONS
       -<n>             A numeric argument that limits the number  of  change-
                        sets printed.

       -/<str>/[igt]    List  only those changesets whose comments contain the
                        string <str>.  <str> may be a regular  expression,  or
                        if the <g> option is specified, a glob.  If there is a
                        trailing "i" then ignore case in the search.  If there
                        is a trailing "t" then search only in tag names.  Yes,
                        it would be nice if this worked  on  (meta)data  other
                        than the comments but as of now it does not.

       -a               List all deltas, including tag deltas.  The default is
                        to list the tag name on the changeset implied  by  the
                        tag.   Implies  "-e".   An  additional "-e" after this
                        option will turn off the listing of  the  empty  merge
                        deltas  (the "-e" option is inverted from its previous
                        value each time the option is seen).

                        lar  the  examples) is awk like and has begin/end sec-
                        tions.  This option allows you to specify the body  of
                        a  begin section (if the file also has a begin section
                        then both are  run;  order  is  undefined).   A  begin
                        script  is  typically  used with an on disk dspec file
                        that has been written in a way  to  do  one  thing  by
                        default and another if a variable is set to non-zero.

       -c<dates>        Specifies the changesets to be listed as a date range,
                        i.e., "-c-6W.."  lists  the  last  6  weeks  worth  of
                        changes.

       -D               When  showing  local  or remote only changes and there
                        are multiple local or  remote  repositories  specified
                        (or  implied  via the parent pointer[s]), there may be
                        duplicate changesets which are present  in  more  than
                        one repository.  If this option is specified, then the
                        duplicates are filtered out such that  the  changesets
                        listed  are  a  unique set.  This option combined with
                        "-aL" or "-aR" is used to answer the questions:  "What
                        is  only  in  this  repository  relative to all of the
                        specified repositories?" or "What is only  in  one  or
                        more  of the remote repositories but not in this local
                        repository?" respectively.

       -d<dspec>        Override the default dspec, allows for arbitrary  out-
                        put formats.

       --dspecf=<file>  Like -d but read the dspec from a file.

       -e               Show  empty  merge  changesets.  By default, these are
                        not shown.

       -f               print the changes in forward (oldest to newest) order.
                        The default is backwards in time, i.e., most recent to
                        least recent order.

       --html           Produce html as output.   May  not  be  combined  with
                        "-d".

       -i<pat>          Include  information  only  from  changesets involving
                        files matching <pat> pattern (see below).

       -k               Produce a list of matching changeset keys, usually for
                        scripts.  Equivalent to "-Dnd:KEY:".

       -L               List  only  those  changesets  which are unique to the
                        local repository.  Requires either a BK url or a valid
                        repository  parent.   Will  not  report tags, or empty
                        merges.  Use with "-a" to see tags and  empty  merges,
                        i.e.,  everything  which  would be sent back with a bk
                        push.

       --lattice        Restrict  the  changesets  to  those  on  the  lattice
                        between  the two range endpoints.  Unlike a range, the
                        lower bound is included in the  output.   Empty  merge
                        nodes are included (unlike the default output).

       --longest        Restrict  the  changesets to those on the longest line
                        between the two range endpoints.  Unlike a range,  the
                        lower  bound  is  included in the output.  Empty merge
                        nodes are included (unlike the default output).

       -m               Do not show any merge changesets, empty or not.

       -n               add a newline to each printed record (sometimes useful
                        with "-d").

       -q               When  listing  local/remote changes from multiple par-
                        ents (or remote repositories) do not print  the  loca-
                        tion  of  the  remote  repositories.   This  option is
                        implied by "-D".

       -r<revs>         Specifies the changesets to be listed, i.e., 1.100..

       -R               List only those changesets which  are  unique  to  the
                        remote repository, Requires either a BK url or a valid
                        repository parent.  Will not  report  tags,  or  empty
                        merges.   Use  with "-a" to see tags and empty merges,
                        i.e., everything which would be brought over with a bk
                        pull.

       --oneline        Print  a summary of every cset in a single line. It is
                        an alias for: bk changes -nd'$if(:CHANGESET: && !:COM-
                        PONENT_V:){:MD5KEY: $first(:C:)}$else{  :DPN:}'

       --short          With  the  system supplied dspecs, this will limit the
                        file/commit comments to only the first line  (it  does
                        so  by  setting the $9 dspec variable to 1, the system
                        supplied dspecs use that to change their output).

       --sparse-ok      When using include/exclude patterns  (-i/-x)  and  the
                        patterns  could match in a component that is not popu-
                        lated, BitKeeper will refuse to perform the search and
                        print an error. This option allows searching in sparse
                        products (with some components not populated)  without
                        erroring.

       -S
       --standalone     When used in a nested collection, treat the repository
                        as if it were detached rather than as part of the col-
                        lection.   Pathnames  will  be printed relative to the
                        repository root, revisions are based on the repository
                        changeset,  not  the product changeset (if in a compo-
                        nent), pending changesets,  if  any,  will  be  listed
                        (again,  if  in a component).  See product notes below
                        for examples.

       -t
       --tags           Only list changesets which are currently tagged.   Use
                        -tt  (or --all-tags) to list all changesets which have
                        ever been tagged, annotated  with  the  tag's  current
                        state.

       -T               Sort  the  deltas  in  a changeset in time order.  The
                        default is to sort by current file name.  This  option
                        only affects verbose ("-v") output.

       -u<user>         Only  list  changesets created by <user>.  This option
                        may appear multiple times in which case the  changeset
                        is listed if it matches any of the specified users.

       -U<user>         Only  list  changesets  created  by someone other than
                        <user>.  This option  may  appear  multiple  times  in
                        which  case  the changeset is not listed if it matches
                        any of the specified users.

       -v               Shows  individual  file  change  history  as  well  as
                        changeset history.

       -vv              Same as "-v" except that each file's change history is
                        followed by unified diffs for that change  (using  the
                        :DIFFS_UP: keyword).

       -x<pat>          Exclude  information  from changesets involving
                        files matching <pat> pattern (see below).

INCLUDE/EXCLUDE PROCESSING
       Include and/or  exclude  patterns  are  used  to  control  which
       changesets  are  selected  for  printing.  There may be multiple
       include and/or exclude patterns.  The patterns are a  file  glob
       as  used by bk ignore.  Patterns are matched against the partial
       pathname from the root of the repository.  If the partial  path-
       name  matches  any of the exclude patterns then the changeset is
       skipped.  If there are one or more include patterns but the par-
       tial  pathname  does  not match any of the include patterns then
       the changeset is skipped.  Exclude processing  takes  precedence
       over include processing.

       When  reporting  information  there can be ambiguity as to which
       name is used for include/exclude processing because  some  files
       may  have  been  moved  since  the  changeset  in question.  The
       include/exclude processing always applies to the file name as it
       was  as  of the changeset in question.  For example, suppose you
       have a file that is currently deleted but at  the  time  of  the
       changeset  was  in  src/foo.c.  If you told the system to report
       src/* then the file will be in the set.

PRODUCT USAGE
       This command has been extended to handle nested  collections  of
       repositories.

       The  default  behavior  is  identical  to  that of a traditional
       standalone repository, the changesets of the product are listed.
       The  various  options behave as expected, the command treats the
       entire collection as one large repository so a -v will show  the
       product's  changesets  and  files  as  well  as  the component's
       changesets and files.

   SINGLE REPOSITORY
       There are times when you may want to treat a repository as if it
       were  detached  from  the nested collection, i.e., just show the
       history of this component and nothing else.  An example of  that
       might be to see what changes are available to be ported out:

           $ bk changes --standalone -L <URL>

       That  form  of  changes  is  restricted to just that repository;
       pathnames revert back to repository root relative  (rather  than
       product  root  relative),  revisions are based on the repository
       changeset, not the product's changeset, and all changesets, even
       those that are not committed to the product, are listed.

   EXAMPLES
       The most common uses are listed below:

       List only product changesets:

           $ bk changes

       Convert a product changeset to a key:

           $ bk changes -r1.1234 -nd:KEY:

       List  the product changesets and component changesets as well as
       files from both:

           $ bk changes -v

       same as previous but include diffs:

           $ bk changes -vv

       List only the changes in a component:

           $ cd src/component
           $ bk changes --standalone

EXAMPLES
       Sample output:

           ChangeSet@1.607, 2000-02-21 14:05:25-08:00, awc@bitkeeper.com
             update citool to use the "bk unedit" interface.

           ChangeSet@1.606, 2000-02-21 13:35:21-08:00, awc@bitkeeper.com
             Allow BitKeeper to be installed in an alternate directory.
             The install directory is computed from the $PATH variable and
             the bk symlink.

           ChangeSet@1.605, 2000-02-20 01:32:19-08:00, lm@bitkeeper.com
             Fix a diagnostic in pull.
             An aborted attempt at key compression.

BUGS
       Consider this query in a nested collection:

           bk changes -i'source_component/*' -x'test_component/*'

       The expectation is that  you  would  only  get  changesets  that
       touched the source component if they did not touch the test com-
       ponent.  As of now, the include will win whether the test compo-
       nent was or was not changed.

SEE ALSO
       bk commit
       bk glob
       bk pending
       bk log
       bk pcre
       bk pull
       bk push
       bk range
       bk revtool
       bk sccslog
       bk set

CATEGORY
       Common
       Repository

BitKeeper Inc                         1E1                    bk changes(7.3ce)