Next: Annotations -- A Detailed View Of Project Activity, Previous: Getting Rid Of A Working Copy, Up: Advanced CVS
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 floss$
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 floss$
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 floss$
If the repository was created with the
cvs init command, the
history file already exists. You may still have to fix its permissions,
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 /home/qsmith/myproj 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 paste$
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:
CODE DATE USER [REVISION] [FILE] PATH_IN_REPOSITORY ACTUAL_WORKING_COPY_NAME
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