Next: , Previous: Getting Rid Of A Working Copy, Up: Advanced CVS

History – A Summary Of Repository Activity

In Repository Administration, I briefly mentioned the cvs history command. This command displays a summary of all checkouts, commits, updates, rtags, and releases done in the repository (at least, since logging was enabled by the creation of the CVSROOT/history file in the repository). You can control the format and contents of the summary with various options.

The first step is to make sure that logging is enabled in your repository. The repository administrator should first make sure there is a history file

     floss$ cd /usr/local/newrepos/CVSROOT
     floss$ ls -l history
     ls: history: No such file or directory

and if there isn't one, create it, as follows:

     floss$ touch history
     floss$ ls -l history
     -rw-r--r--   1 jrandom   cvs           0 Jul 22 14:57 history

This history file also needs to be writeable by everyone who uses the repository, otherwise they'll get an error every time they try to run a CVS command that modifies that file. The easiest way is simply to make the file world-writeable:

     floss$ chmod a+rw history
     floss$ ls -l history
     -rw-rw-rw-   1 jrandom   cvs           0 Jul 22 14:57 history

If the repository was created with the cvs init command, the history file already exists. You may still have to fix its permissions, however.

The rest of these examples assume that history logging has been enabled for a while, so that data has had time to accumulate in the history file.

The output of cvs history is somewhat terse (it's probably intended to be parsed by programs rather than humans, although it is readable with a little study). Let's run it once and see what we get:

     paste$ pwd
     paste$ cvs history -e -a
     O 07/25 15:14 +0000 qsmith  myproj =mp=     ~/*
     M 07/25 15:16 +0000 qsmith  1.14 hello.c    myproj == ~/mp
     U 07/25 15:21 +0000 qsmith  1.14 README.txt myproj == ~/mp
     G 07/25 15:21 +0000 qsmith  1.15 hello.c    myproj == ~/mp
     A 07/25 15:22 +0000 qsmith  1.1  goodbye.c  myproj == ~/mp
     M 07/25 15:23 +0000 qsmith  1.16 hello.c    myproj == ~/mp
     M 07/25 15:26 +0000 qsmith  1.17 hello.c    myproj == ~/mp
     U 07/25 15:29 +0000 qsmith  1.2  goodbye.c  myproj == ~/mp
     G 07/25 15:29 +0000 qsmith  1.18 hello.c    myproj == ~/mp
     M 07/25 15:30 +0000 qsmith  1.19 hello.c    myproj == ~/mp
     O 07/23 03:45 +0000 jrandom myproj =myproj= ~/src/*
     F 07/23 03:48 +0000 jrandom        =myproj= ~/src/*
     F 07/23 04:06 +0000 jrandom        =myproj= ~/src/*
     M 07/25 15:12 +0000 jrandom 1.13 README.txt myproj == ~/src/myproj
     U 07/25 15:17 +0000 jrandom 1.14 hello.c    myproj == ~/src/myproj
     M 07/25 15:18 +0000 jrandom 1.14 README.txt myproj == ~/src/myproj
     M 07/25 15:18 +0000 jrandom 1.15 hello.c    myproj == ~/src/myproj
     U 07/25 15:23 +0000 jrandom 1.1  goodbye.c  myproj == ~/src/myproj
     U 07/25 15:23 +0000 jrandom 1.16 hello.c    myproj == ~/src/myproj
     U 07/25 15:26 +0000 jrandom 1.1  goodbye.c  myproj == ~/src/myproj
     G 07/25 15:26 +0000 jrandom 1.17 hello.c    myproj == ~/src/myproj
     M 07/25 15:27 +0000 jrandom 1.18 hello.c    myproj == ~/src/myproj
     C 07/25 15:30 +0000 jrandom 1.19 hello.c    myproj == ~/src/myproj
     M 07/25 15:31 +0000 jrandom 1.20 hello.c    myproj == ~/src/myproj
     M 07/25 16:29 +0000 jrandom 1.3  whatever.c myproj/a-subdir == ~/src/myproj

There, isn't that clear?

Before we examine the output, notice that the invocation included two options: -e and -a. When you run history, you almost always want to pass options telling it what data to report and how to report it. In this respect, it differs from most other CVS commands, which usually do something useful when invoked without any options. In this example, the two flags meant "everything" (show every kind of event that happened) and "all" (for all users), respectively.

Another way that history differs from other commands is that, although it is usually invoked from within a working copy, it does not restrict its output to that working copy's project. Instead, it shows all history events from all projects in the repository – the working copy merely serves to tell CVS from which repository to retrieve the history data. (In the preceding example, the only history data in that repository is for the myproj project, so that's all we see.)

The general format of the output is:


The code letters refer to various CVS operations, as shown in Table 6.1.

For operations (such as checkout) that are about the project as a whole rather than about individual files, the revision and file are omitted, and the repository path is placed between the equal signs.

Although the output of the history command was designed to be compact, parseable input for other programs, CVS still gives you a lot of control over its scope and content. The options shown in Table 6.2 control what types of events get reported.

     Table 6.1  The meaning of the code letters.
     Letter	        Meaning
     ======          =========================================================
     O		Checkout
     T		Tag
     F		Release
     W		Update (no user file, remove from entries file)
     U		Update (file overwrote unmodified user file)
     G		Update (file was merged successfully into modified user file)
     C		Update (file was merged, but conflicts w/ modified user file)
     M		Commit (from modified file)
     A		Commit (an added file)
     R		Commit (the removal of a file)
     E		Export
     Table 6.2  Options to filter by event type.
     Option	        Meaning
     ==========      =========================================================
     -m MODULE	Show historical events affecting MODULE.
     -c		Show commit events.
     -o		Show checkout events.
     -T		Show tag events.
     -x CODE(S)	Show all events of type CODE (one or more of OTFWUGCMARE).
     -e		Show all types of events, period.  Once you have
                     selected what type of events you want reported, you can
                     filter further with the options shown in Table 6.3.
     Table 6.3  Options to filter by user.
     Option	        Meaning
     ==========      =========================================================
     -a		Show actions taken by all users
     -w		Show only actions taken from within this working copy
     -l		Show only the last time this user took the action
     -u USER 	Show records for USER
Karl Fogel wrote this book. Buy a printed copy via his homepage at

copyright  ©  November 19 2019 sean dreilinger url: