GNU Info
(cvsbook.info)Annotations -- A Detailed View Of Project Activity
Annotations - A Detailed View Of Project Activity
=================================================
The annotate Command
====================
If the history command gives an overview of project activity, the
"annotate" command is a way of attaching a zoom lens to the view. With
`annotate', you can see who was the last person to touch each line of a
file, and at what revision they touched it:
floss$ cvs annotate
Annotations for README.txt
***************
1.14 (jrandom 25-Jul-99): blah
1.13 (jrandom 25-Jul-99): test 3 for history
1.12 (qsmith 19-Jul-99): test 2
1.11 (qsmith 19-Jul-99): test
1.10 (jrandom 12-Jul-99): blah
1.1 (jrandom 20-Jun-99): Just a test project.
1.4 (jrandom 21-Jun-99): yeah.
1.5 (jrandom 21-Jun-99): nope.
Annotations for hello.c
***************
1.1 (jrandom 20-Jun-99): #include <stdio.h>
1.1 (jrandom 20-Jun-99):
1.1 (jrandom 20-Jun-99): void
1.1 (jrandom 20-Jun-99): main ()
1.1 (jrandom 20-Jun-99): {
1.15 (jrandom 25-Jul-99): /* another test for history */
1.13 (qsmith 19-Jul-99): /* random change number two */
1.10 (jrandom 12-Jul-99): /* test */
1.21 (jrandom 25-Jul-99): printf ("Hellooo, world!\n");
1.3 (jrandom 21-Jun-99): printf ("hmmm\n");
1.4 (jrandom 21-Jun-99): printf ("double hmmm\n");
1.11 (qsmith 18-Jul-99): /* added this comment */
1.16 (qsmith 25-Jul-99): /* will merge these changes */
1.18 (jrandom 25-Jul-99): /* will merge these changes too */
1.2 (jrandom 21-Jun-99): printf ("Goodbye, world!\n");
1.1 (jrandom 20-Jun-99): }
Annotations for a-subdir/whatever.c
***************
1.3 (jrandom 25-Jul-99): /* A completely non-empty C file. */
Annotations for a-subdir/subsubdir/fish.c
***************
1.2 (jrandom 25-Jul-99): /* An almost completely empty C file. */
Annotations for b-subdir/random.c
***************
1.1 (jrandom 20-Jun-99): /* A completely empty C file. */
floss$
The output of annotate is pretty intuitive. On the left are the
revision number, developer, and date on which the line in question was
added or last modified. On the right is the line itself, as of the
current revision. Because every line is annotated, you can actually see
the entire contents of the file, pushed over to the right by the
annotation information.
If you specify a revision number or tag, the annotations are given as of
that revision, meaning that it shows the most recent modification to
each line at or before that revision. This is probably the most common
way to use annotations - examining a particular revision of a single
file to determine which developers were active in which parts of the
file.
For example, in the output of the previous example, you can see that the
most recent revision of hello.c is 1.21, in which jrandom did something
to the line:
printf ("Hellooo, world!\n");
One way to find out what she did is to diff that revision against the
previous one:
floss$ cvs diff -r 1.20 -r 1.21 hello.c
Index: hello.c
===================================================================
RCS file: /usr/local/newrepos/myproj/hello.c,v
retrieving revision 1.20
retrieving revision 1.21
diff -r1.20 -r1.21
9c9
< printf ("Hello, world!\n");
--
> printf ("Hellooo, world!\n");
floss$
Another way to find out, while still retaining a file-wide view of
everyone's activity, is to compare the current annotations with the
annotations from a previous revision:
floss$ cvs annotate -r 1.20 hello.c
Annotations for hello.c
***************
1.1 (jrandom 20-Jun-99): #include <stdio.h>
1.1 (jrandom 20-Jun-99):
1.1 (jrandom 20-Jun-99): void
1.1 (jrandom 20-Jun-99): main ()
1.1 (jrandom 20-Jun-99): {
1.15 (jrandom 25-Jul-99): /* another test for history */
1.13 (qsmith 19-Jul-99): /* random change number two */
1.10 (jrandom 12-Jul-99): /* test */
1.1 (jrandom 20-Jun-99): printf ("Hello, world!\n");
1.3 (jrandom 21-Jun-99): printf ("hmmm\n");
1.4 (jrandom 21-Jun-99): printf ("double hmmm\n");
1.11 (qsmith 18-Jul-99): /* added this comment */
1.16 (qsmith 25-Jul-99): /* will merge these changes */
1.18 (jrandom 25-Jul-99): /* will merge these changes too */
1.2 (jrandom 21-Jun-99): printf ("Goodbye, world!\n");
1.1 (jrandom 20-Jun-99): }
floss$
Although the diff reveals the textual facts of the change more
concisely, the annotation may be preferable because it places them in
their historical context by showing how long the previous incarnation of
the line had been present (in this case, all the way since revision
1.1). That knowledge can help you decide whether to look at the logs to
find out the motivation for the change:
floss$ cvs log -r 1.21 hello.c
RCS file: /usr/local/newrepos/myproj/hello.c,v
Working file: hello.c
head: 1.21
branch:
locks: strict
access list:
symbolic names:
random-tag: 1.20
start: 1.1.1.1
jrandom: 1.1.1
keyword substitution: kv
total revisions: 22; selected revisions: 1
description:
----------------------------
revision 1.21
date: 1999/07/25 20:17:42; author: jrandom; state: Exp; lines: +1 -1
say hello with renewed enthusiasm
============================================================================
floss$
In addition to -r, you can also filter annotations using the -D DATE
option:
floss$ cvs annotate -D "5 weeks ago" hello.c
Annotations for hello.c
***************
1.1 (jrandom 20-Jun-99): #include <stdio.h>
1.1 (jrandom 20-Jun-99):
1.1 (jrandom 20-Jun-99): void
1.1 (jrandom 20-Jun-99): main ()
1.1 (jrandom 20-Jun-99): {
1.1 (jrandom 20-Jun-99): printf ("Hello, world!\n");
1.1 (jrandom 20-Jun-99): }
floss$ cvs annotate -D "3 weeks ago" hello.c
Annotations for hello.c
***************
1.1 (jrandom 20-Jun-99): #include <stdio.h>
1.1 (jrandom 20-Jun-99):
1.1 (jrandom 20-Jun-99): void
1.1 (jrandom 20-Jun-99): main ()
1.1 (jrandom 20-Jun-99): {
1.1 (jrandom 20-Jun-99): printf ("Hello, world!\n");
1.3 (jrandom 21-Jun-99): printf ("hmmm\n");
1.4 (jrandom 21-Jun-99): printf ("double hmmm\n");
1.2 (jrandom 21-Jun-99): printf ("Goodbye, world!\n");
1.1 (jrandom 20-Jun-99): }
floss$
automatically generated by info2www version 1.2.2.9