5.6. Displaying File History
The cvs log command displays information about files, directories, or modules. You pass a parameter to specify which file, directory, or module you are interested in. If you don't specify anything, cvs log displays log information about all files in the current sandbox directory. The user-provided part of this log information is entered when you run cvs commit or when you set the -m command option to cvs add.
cvs log is often used to help decide which of two revisions to use to create a patch file, to determine a branch point, or to provide a quick guide to what the other developers are doing in a multiuser environment. Informative log messages are very important for all of these uses.
The options to cvs log reduce the amount of information it shows. By default, it displays everything it can. For each file, it displays a header; then, for each revision of the file, it displays the revision number, date, author, state, log message, and number of lines added and deleted in that revision.
Example 5-18 shows a simple use of cvs log. Note that the keyword-substitution mode is the default mode, generating both keyword and value, and that the log message in revision 1.1 mentions both files that were added at the time.
Example 5-18. Using cvs log
The header for each file includes the path to the repository copy of the file, the name of the sandbox (or working) file, the revision number of the head revision, the current branch, if any, the lock status, the access list, tag (or symbolic) names and revision numbers, any keyword-substitution modes, the number of total revisions for the file, the number of revisions the log command is to display, and any description of the file stored in CVS.
The access list and the description are historical and exist because the files are stored in an RCS-based format. CVS relies on strict locking, so the lock status should always be strict. CVS files are created with strict locking; locking can only be set nonstrict through the cvs admin command or through editing the file directly.
cvs log has the following syntax:
cvs [cvs-options] log [command-options] [filenames]
If no file, directory, or module names are given, cvs log assumes the current sandbox directory as the parameter. The options to cvs log differ from the standard options for most other commands.
Most of the options to cvs log restrict the revisions for which information is displayed. cvs log normally displays only those revisions that match all the options you specify, so as you add options, you tend to reduce the set of revisions for which cvs log displays information. For example, if both -b and -r options are selected, cvs log displays only the revisions that match both -b and -r parameters. If other options are also selected, cvs log displays the revisions that match -b and -r and also fit the other options.
The -b option limits the cvs log output to the default branch, usually the latest branch off the trunk. -rrevision-range restricts the output to the revisions given in the revision range. Chapter 10 provides the syntax to use in specifying the revision range.
The -w usernames option limits cvs log output to revisions checked in by users in a comma-separated list of usernames. The list of usernames should not include spaces, and there should be no space between the -w and the list.
The -h and -t options limit the amount of information cvs log displays with each file. -h limits it to the header, and -t limits it to the header and the description. Using the -S option tells cvs log not to display the header of files where at least one revision will be displayed.
Graphic clients can produce extremely helpful and useful displays with the data from CVS log. TkCVS provides a diagram of the tree structure of a file, as shown in Figure 5-5.
Figure 5-5. Graphic display of log
Chapter 10 provides the full list of options for cvs log.