Previous section   Next section

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 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
bash-2.05a$ cvs log main.c 
    
RCS file: /var/lib/cvs/wizzard/src/main.c,v
Working file: main.c
head: 1.9
branch:
locks: strict
access list:
symbolic names:
     beta_0-1_branch: 1.9.0.2
     beta_0-1_branch_root: 1.9
     pre_beta_0-1: 1.8
keyword substitution: kv
total revisions: 9;     selected revisions: 9
description:
----------------------------
revision 1.9
date: 2002/09/12 08:14:19;  author: jenn;  state: Exp;  lines: +0 -0
Final test of re-addition methods.
.
.
.
----------------------------
revision 1.1
date: 2002/09/11 13:33:13;  author: jenn;  state: Exp;
Added main.c: parses parameters and calls functions in other files.
Added wizzard.h: defines compile-time global variables.
=  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =  =

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 -wusernames 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.

Chapter 10 provides the full list of options for cvs log.


  Previous section   Next section
Top