Next: , Previous: History -- A Summary Of Repository Activity, Up: Advanced CVS


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$
Karl Fogel wrote this book. Buy a printed copy via his homepage at red-bean.com

copyright  ©  January 17 2019 sean dreilinger url: https://durak.org/sean/pubs/software/cvsbook/Annotations-_002d_002d-A-Detailed-View-Of-Project-Activity.html