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)
File