Previous section   Next section

7.5 Tools

Project administrators should be aware of the CVS commands described in Chapter 3 and Chapter 5. You may also want to read Chapter 4 and Chapter 6.

In addition to the commands described in those chapters, there are two commands that are particularly useful to project administrators: cvs admin and cvs history. cvs admin allows you to use RCS-like commands on files stored in the repository. cvs history provides a record of the actions performed on a project's files and is similar to cvs log or cvs annotate.

7.5.1 The cvs admin Command

The cvs admin command is used to edit the RCS files directly in the repository. It is more accurately thought of as a set of commands than a single command, as it provides many of the commands that RCS would make available, though not all of these commands are usable or have an effect that matters to CVS. These commands are present mostly for historic reasons and backward compatibility with early versions of CVS.

If there is a system group called cvsadmin on the repository server, only users in that group can use the cvs admin command. If this group does not exist, any user can use the cvs admin commands on any repository files they have permission to change. Consider using the cvsadmin system group, as some of the cvs admin commands can prevent CVS from using the affected file or files.

There is a new option in the config file of CVS 1.12.1 and later. The UserAdminCommands option allows the system administrator to set cvs admin options that users who are not in the cvsadmin group can run.

The syntax for cvs admin is as follows:

cvs [cvs-options] admin command-options [filename...]

I strongly recommend always stating the filenames you wish cvs admin to act on, as some of the cvs admin commands can be difficult or impossible to recover from if you accidentally use them on the wrong file. If you do not specify a filename, cvs admin operates on all files in the current sandbox directory and moves recursively down its subdirectories.

Each of the RCS commands that cvs admin provides is represented by a command option to cvs admin. RCS commands that are obsolete or meaningless when used with CVS are not listed in this chapter. For many of the commands, there can be no space between an option and its argument. See Chapter 10 for the full list of cvs admin command options.

The most commonly used cvs admin option is the -k option, which sets the default keyword-substitution mode for a file. This option is explained in the Section 3.11 of Chapter 3. If you forget to set the -kb keyword-substitution mode of a binary file when you add it to the repository, you can use cvs admin -kb filename to correct the mistake.

If you use the rcslock script to reserve development of files, as described in Chapter 5, you use cvs admin -l filename and cvs admin -u filename to lock and unlock the file you are reserving.

The -o option is used in one of the methods of moving files, as described in Chapter 6. This option allows you to remove old revisions of a file, effectively collapsing the changes from those revisions into a single revision. It cannot be reversed once it is done, so be very careful and test it on a copy of the repository first. The full syntax of the -o option is provided in Chapter 10.

The -m option allows you to replace a log message. The -s option is used to set the state of a file. The state is shown in cvs log output and in the results of the Log keyword. The -t option is used to set a description of the file, which is also shown in cvs log output.

The -U option to cvs admin sets file locking to nonstrict, which prevents CVS from working with a file effectively. The -L option repairs this problem by setting the file locking to strict. The -U and -L options should not be used, but if someone accidentally uses -U while trying to use -u, you now know you can use -L to repair the damage.

7.5.2 The cvs history Command

The cvs history command reports on the history of actions performed on the files in a repository. This command is a variation of the cvs log command explained in Chapter 5. The cvs log command displays only commit actions; cvs history can display most types of actions.

7.5.2.1 The history file

cvs history uses the history file in a repository's CVSROOT directory as a database and displays only events that have occurred while the file is present and writable. The cvs init command creates the history file by default. Note that CVS will not report an error if the history file is removed.

The history file must be writable by all users. Since it never causes a script to be executed, this is not a security issue. The actions that are logged to the history file are controlled by the LogHistory setting in the config file in the repository's CVSROOT directory.

7.5.2.2 cvs history output

The format of the output of the cvs history command varies, depending on the options chosen. The basic format of each line of the history output is:

type date timezone user {revision|path|branch} {module|directory|tag|filename} 
[module|project-root-directory] access_type

The type is a single letter, representing one of the types given in the list at the end of this section. The timezone is +0000 (i.e., UTC) if not specified otherwise. The access type is remote or local; if it is local, it shows the directory the sandbox was in when the command recorded in the history file was run.

Example 7-15 shows an example of most of the output types for cvs history. Whitespace has been removed to prevent the output from wrapping.

Example 7-15. cvs history command output
bash-2.05a$ cvs history -e -zUTC
O 2002-08-22 05:42 UTC jenn wizzard =wizzard= <remote>/*
O 2002-10-03 08:38 UTC jenn wizzard =wizmake= /tmp/*
O 2002-10-03 08:38 UTC jenn wizzard/src =wiztest= /tmp/*
M 2002-08-22 08:00 UTC jenn 1.8 1-introduction.sxw cvsbook =  = <remote>
A 2002-08-29 12:17 UTC jenn 1.1 Z-copiesto cvsbook =  = <remote>
W 2002-09-12 04:36 UTC jenn wizzard.h wizzard/src =  = <remote>/src
C 2002-09-12 05:32 UTC jenn 1.2 main.c wizzard/src =  = <remote>
G 2002-09-12 05:32 UTC jenn 1.4 wizzard.h wizzard/src  =  = <remote>
R 2002-09-12 06:07 UTC jenn 1.3 main.c wizzard/src =  = <remote>
T 2002-09-13 04:04 UTC jenn wizzard [pre_alpha_0-2:HEAD]
T 2002-09-13 04:04 UTC jenn wizzard [pre_alpha_0-2:2002.09.13.04.04.22]
T 2002-09-13 07:12 UTC jenn wizzard [beta_0-1_branch:beta_0-1_branch_root]
E 2002-10-01 07:00 UTC jenn [2002.10.01] wizzard =wizzard= <remote>/*
F 2002-10-02 17:48 UTC jenn =wizzard= <remote>/*
7.5.2.3 Using the cvs history command

The syntax for the cvs history command is

cvs [cvs-options] history [command-options] [filenames...]

The options to cvs history modify how much of the history is shown for which users and modules. The -T, -c, and -o options display the records for tags, commits, and checkouts, respectively. The -e option displays all record types. The -z timezone option converts times and displays them in the specified time zone.

CVS does not allow you to combine the -T, -c, -o, -x, and -e options. If you wish to display multiple action types, use the -x option with a type letter.

The types shown in the history output are designated by letters, which can also be used with the -x option to specify the types of events you wish to display. Multiple types can be specified. These are the types:

A

Report on records of files added to the repository (a committed add).

C

Report on records showing files that would have been updated in a sandbox, but that needed to be merged and for which there were conflicts in the merge (compare with G and U).

E

Report on records of files being exported.

F

Report on records of files being released.

G

Report on records of a file being updated in a sandbox with a successful merge (compare with C and U).

M

Report on records of a file being modified (a successful commit of a sandbox revision).

O

Report on records of files being checked out.

R

Report on records of files being removed from the active part of the repository (a committed remove).

T

Report on records of files being tagged or rtagged.

U

Report on records of a file being updated in a sandbox with no merge required (compare with C and G).

W

Report on records of a file being deleted from a sandbox during an update because it is no longer active in the repository.

The full list of command options for cvs history is provided in Chapter 10.


  Previous section   Next section
Top