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

NAME
       bk annotate - provide annotated listings of one or more source files

SYNOPSIS
       bk annotate [options] [<file> ... | -]

DESCRIPTION
       BitKeeper  annotations add an extra level of information, such as date,
       author, etc., when viewing file contents.  Annotated listings are  use-
       ful  for  deeper  understanding of your source base, i.e., when you are
       tracking down bugs.

       BitKeeper has two kinds of annotations: annotations of a specific  ver-
       sion  of  a  file,  and annotations of all (or some) versions of a file
       (the second form is unique to BitKeeper).

       By default, the bk annotate command will display a specific version  of
       a  file  with  annotations.   The  default  version of file is the most
       recent version; the "-r" option may be used to specify  an  alternative
       version.   The default annotations are the revision in which the change
       was made and the user who made that change.  Selecting any  annotations
       overrides all of the default annotations.

       An  alternate  form  of  the bk annotate command may be used to show or
       annotate either all lines added by all versions or just the lines added
       by one or more versions (in the latter case, the whole file is not dis-
       played, instead, only the lines which  were  added  in  that  range  of
       changes  are displayed.)  The "-R" option turns on this form of annota-
       tion.  Each version of a line is grouped closely with other versions of
       that  line.   This can be useful for determining when a particular fea-
       ture was added or modified.  This form of annotation has no annotations
       by  default;  the desired annotations must be specified.  If no annota-
       tions are specified then the selected lines are shown  without  annota-
       tions.

OPTIONS
       -A<5dnpru> Align  annotations  in  a  human  readable form.  The set of
                  annotations will be followed by a vertical bar and  a  space
                  before  the  data  from  each line of the file starts.  Each
                  annotation is aligned in a column.  The  option  argument[s]
                  turn  on  one  or more annotations as a prefix to each line.
                  The order of annotations is fixed (no matter what order  you
                  specify them) and is the same as the order listed below:
                  p      Prefix  each line with the pathname of the file rela-
                         tive to the current working directory.  The  name  is
                         always  the  current  name of the file even if it has
                         been renamed.
                  d      Prefix each line with the date of last modification.
                  u      Prefix each line with the name of the user  who  last
                         modified it.
                  r      Prefix  each line with the revision of the last modi-
                         fication.
                  5      Prefix each line with the MD5 key of the last modifi-
                         cation.
                  n      Prefix each line with its line number.
       -a<5dnpru> Similar  to  "-A" but without the alignment (each annotation
                  is followed by a tab).  The order of fields is fixed and is:
                  pathname, date, user, revision, md5key, line number.
       -c<dates>  annotate  only  the  lines  added  by the specified range of
                  dates.  See bk range for information on specifying dates.
       -k         do not expand RCS or SCCS keywords.  This option is  implied
                  by "-c" and "-R".
       -r<rev>    annotate all lines in this version of the file.
       -R[<rev>]  annotate  only the lines added by the specified revision (or
                  range of  revisions).   If  <rev>  is  not  specified,  that
                  implies  all revisions (i.e., "..").  The difference between
                  this option and the previous option is that in this case  bk
                  annotate shows only those lines added by the specified revi-
                  sion[s], but in the "-r" case, the entire  contents  of  the
                  specified version is annotated.
       -w[<rev>]  Change  the  format  of  the  "r"  annotation  from "rev" to
                  "rev-d<rev>" in the case where the line is deleted from  the
                  rev  passed  as  the  argument,  or "rev-x<rev>" in the case
                  where the line has been excluded.  If  no  rev  argument  is
                  given, the tip revision is used.

EXAMPLES
       Annotate the latest revision of a file:

           $ bk annotate foo.c

       Annotate the lines added in the latest revision of that file

           $ bk annotate -R+ foo.c

       Annotate all lines in all versions of that file

           $ bk annotate -R foo.c

       Annotate  all lines added to all files in the current directory between
       June 1 of 2010 and July 31 of 2010:

           $ bk annotate -c2010/06..2010/07

       To annotate all lines added between two tagged releases:

           bk -U annotate -Rbk-4.6..bk-5.0

NOTES
       In previous versions of BitKeeper, the "-c" option was used to select a
       single  revision  and annotate all lines in that revision.  You can now
       get the same effect as the old:

           bk annotate -c2000 foo.c

       with the more complicated (this assumes bash is your shell):

           bk annotate -r$(bk prs -1 -hnd:REV: -c..2000 foo.c) foo.c

SEE ALSO
       bk get
       bk grep
       bk range
       bk revtool

CATEGORY
       File

BitKeeper Inc                         1E1                   bk annotate(7.3ce)