bk-annotate - (unknown subject)
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 useful 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 version 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 displayed, instead, only the lines which were added in that range of changes are displayed.) The −R option turns on this form of annotation. Each version of a line is grouped closely with other versions of that line. This can be useful for determining when a particular feature was added or modified. This form of annotation has no annotations by default; the desired annotations must be specified. If no annotations are specified then the selected lines are shown without annotations.
OPTIONS
−A5dnpru 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 relative 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
modification.
5 Prefix each line with the MD5 key of the last
modification.
n Prefix each line with its line number.
−a5dnpru
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.
−cdates 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.
−rrev 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 revision[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