Essential CVS/Reference/Miscellaneous Topics Reference

From WikiContent

< Essential CVS | Reference(Difference between revisions)
Jump to: navigation, search
(Initial conversion from Docbook)
Current revision (13:08, 7 March 2008) (edit) (undo)
(Initial conversion from Docbook)
 
(5 intermediate revisions not shown.)
Line 53: Line 53:
=== CVS Subdirectory Files ===
=== CVS Subdirectory Files ===
-
'''' CVS creates a subdirectory named ''CVS'' in every directory of a sandbox. It stores the following sandbox administrative files in this subdirectory:
+
CVS creates a subdirectory named ''CVS'' in every directory of a sandbox. It stores the following sandbox administrative files in this subdirectory:
;''Base''
;''Base''
Line 912: Line 912:
<dl>
<dl>
<dt>[...]
<dt>[...]
-
<dd>A character set. Any of the characters in the character set can be matched. The ''[fba]'' character set matches any one (and only one) of ''f'', ''b'', or ''a''. With the ''*''operator, the expression''[fba]*'' matches any sequences composed of zero or more ''f'', ''b'',''''or ''a''characters.
+
<dd>A character set. Any of the characters in the character set can be matched. The ''[fba]'' character set matches any one (and only one) of ''f'', ''b'', or ''a''. With the ''*''operator, the expression''[fba]*'' matches any sequences composed of zero or more ''f'', ''b'',or ''a''characters.
The only special characters or operators inside a character set are ''-'', '']'', and ''^''. To include a '']'' in a character set, use it as the first character. To include a -, use it as the last character or just after a range. To use a ''^'', use it anywhere except as the first character.
The only special characters or operators inside a character set are ''-'', '']'', and ''^''. To include a '']'' in a character set, use it as the first character. To include a -, use it as the last character or just after a range. To use a ''^'', use it anywhere except as the first character.

Current revision

Essential CVS

This chapter is a comprehensive reference of CVS topics other than commands. It is intended to be useful as a quick reference, not a tutorial.

If you have never used CVS before, I suggest you read Chapter 2 and Chapter 3 before reading this reference. Those chapters explain the basic concepts of CVS and how to use it effectively.

This chapter contains the following sections:

Section 11.1
Describes CVS administrative files in the sandbox on the client computer or in the user's home directory on the server.
Section 11.2
Describes CVS administrative files in the repository's CVSROOT directory.
Section 11.3
Describes variables you can use in the administrative files in the CVSROOT directory.
Section 11.4
Describes date and time formats you can use with CVS.
Section 11.5
Describes environment variables on the server or the client that affect CVS.
Section 11.6
Describes the keywords CVS uses, the expansion modes that affect how CVS processes the keywords, and how CVS processes line endings.
Section 11.7
Describes regular-expression and wildcard pattern matching in CVS.
Section 11.8
Describes methods used to access local and remote CVS repositories.

Contents

Administrative Files

Each sandbox directory has administrative files in its CVS subdirectory, but it may also have hidden files in the directory itself, with filenames that start with a dot (.). The user's home directory can contain CVS administrative files that affect all of that user's sandboxes; these filenames are also prefixed with a dot.

Dot Files

In client/server mode, all the dot files other than .rhosts should be on the client computer. The .rhosts file should be in the user's home directory on the server computer.

These are the dot files in the sandbox directory:

.cvsignore
Contains a list of files CVS should not process. This file uses the same format as cvsignore in the repository's CVSROOT directory and may be checked into CVS.
.#filename.revision
If a project file that is not fully synchronized with the repository is overwritten by CVS, the original file is stored as.#filename.revision, where revision is theBASE revision of the file.

These are the dot files in a user's home directories:

.cvsrc
Contains a list of CVS commands and the options the user wants as default options for those commands.
.cvsignore
Contains a list of files CVS should not process. This file uses the same format as cvsignore in the repository's CVSROOT directory.
.cvswrappers
Contains a list of wrappers that affect how a file is stored. The wrappers include a pattern that CVS matches against filenames and a keyword-expansion mode that CVS applies to any file whose name matches the pattern.
.cvspass
Used in pserver remote-access mode. This file contains the user's password for each repository they are logged into, stored in a simple form of encoding. Be aware that the file is human-readable and the passwords are easy to decrypt.
.rhosts
Used when connecting with RSH. This file should be in the user's home directory on the server machine, and it should contain the client's computer and username.

CVS Subdirectory Files

CVS creates a subdirectory named CVS in every directory of a sandbox. It stores the following sandbox administrative files in this subdirectory:
Base
A directory, not a file, that stores the preediting revision of any files that are being edited with cvs edit.
Baserev
Contains the revision information for every file in the Base directory, in the format name/revision/. Later versions of CVS may add to this format.
Baserev.tmp
Changes to the Baserev file are written to Baserev.tmp. CVS then renames Baserev.tmp to Baserev, which overwrites the original Baserev.
Checkin.prog
Used if the current sandbox was checked out as a module and the modules file in the repository's CVSROOT has a -i option for the module the sandbox was checked out as. This file stores the program to be executed when the module is checked in. Checkin.progis obsolete in CVS 1.11.6 and later.

Entries
Contains a line for each file and directory in the relevant sandbox directory. Lines for files have the format:

/name/revision/timestamp[+conflict]/options/tagdate
                        

Lines for directories have the format:

D/name////

There may be text between or after the empty slashes, but in CVS 1.11.5 this text is ignored. The space is reserved for future expansion.

Entries.Backup
Changes to the Entries file are written to Entries.Backup. CVS then renames Entries.Backup to Entries, which overwrites the original Entries.

Entries.Log
Used to record planned changes to the Entries file. Lines to be added start withA; lines to be removed start with R. After the A or R comes a space, followed by the line to be added or removed.

Programs that read Entries should also check for Entries.Log. If Entries.Logexists, they should read Entries, apply the changes from Entries.Log, and then rewrite Entries and remove Entries.Log.

Entries.Static
If this file exists, CVS did not receive a complete set of files from the repository and the sandbox directory that is the parent to the current CVS directory is static (i.e., CVS will not create new files in this directory). This setting can be cleared by using update -d to download a full set of files and subdirectories for the parent directory to the current CVS directory.
Notify
Contains any cvs watch notifications that have not yet been sent to the server.
Notify.tmp
Changes to the Notify file are written to Notify.tmp. CVS then renames Notify.tmp to Notify, which overwrites the original Notify.

Repository
Usually contains the path from the repository root to the repository directory that the relevant sandbox directory is a reflection of. This file may contain the full path, including the path to the root of the sandbox's repository.

If the current sandbox directory does not have a related repository directory, this file contains the string CVSROOT/Emptydir.

Root
Contains the path to the root of the sandbox's repository.

Tag
Used to store directory-specific sticky tags and dates, so that CVS can add them to new files that you add to the directory. This file is most often used when the directory is part of a branch sandbox.

If the first character in the file is T, the file refers to a branch tag. N is a nonbranch tag, and D is a date.

Template
In client/server mode, this file stores the login template specified in the rcsinfo file in the repository's CVSROOT directory.
Update.prog
Used if the modules file in CVSROOT specifies the -u option for the current sandbox's module. Update.prog stores the program to be executed when this module is updated. This file is obsolete in CVS 1.11.6 and later.

CVSROOT Files

The CVSROOT directory in the CVS repository contains several administrative files. Most of these files are editable by the user and are stored in both RCS format (with a ,v suffix) and plain text to be used by CVS. These files can be checked out and committed like any other CVS file.

The history and val-tags files should not be edited. The passwd file should never be checked out; it should be edited in place.

The checkoutlist File

The checkoutlist file is used to designate files to be stored in the CVSROOT directory in both RCS and clear-text formats. Most of the CVS administrative files are stored this way automatically, and the checkoutlist file allows you to store user-created files in the same way. The most common files to be stored like this are scripts executed by the scripting files (commitinfo, loginfo, rcsinfo, taginfo, and verifymsg).

The file format is to simply list the names of the files, one file per line. All files must be in the CVSROOT directory.

The commitinfo File

The commitinfo file defines programs to run before a file is committed. If any of the programs exit with a nonzero exit status, the commit does not proceed. These programs run on the repository computer.

The file syntax is as follows:

                  name_pattern 
                  action
               

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the address of a script, plus any parameters required for that script or template. The full path of the repository and the filenames of all files to be committed are appended as parameters by CVS during processing.

Example 11-1 shows a commitinfo file that calls a formatcheck script with the --style=gnu parameter, for any files committed from the src directory of the wizzard project. The formatcheck script is stored in the repository's CVSROOT directory.

Example 11-1. A commitnfo file

^wizzard/src\(/\|$\) /home/cvs/CVSROOT/formatcheck --style=gnu

Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any pattern except ALL. CVS uses the script on the first line with a directory-name pattern that matches the directory tree the file is in. If no pattern match is found, the script specified by the DEFAULT line is executed. Scripts specified by ALL lines are always executed.

The commitinfo file is usually used to enforce project standards.

The config File

The config file contains CVS configuration options. Lines that start with a # are comments. All other lines are in the form:

                  keyword=value
               

There is one keyword/value pair per line. Each keyword/value pair represents a configuration option. Whitespace is significant, including carriage returns, tabs, and extra spaces.

These are the available configuration options:


LockDir=directory
If this setting is present, CVS puts lock files in the specified directory rather than in the repository. You need to create the directory, but CVS creates all the necessary subdirectories.

Warning

Do not use LockDir if any of your users are running CVS 1.9 or earlier on the repository server, as users will then be putting locks in two different places and not honoring each other's locks. CVS 1.10 doesn't honor the LockDir setting; it displays an error if you use it and does not work. Versions prior to CVS 1.10 silently ignore LockDir.

LogHistory=value
The text in value controls which actions are logged to the historyfile in the repository's CVSROOT directory. The valid values can be any combination of the following:

A
Log when a file is added to the repository.
C
Log when a file would have been updated in a sandbox, but needed to be merged and there were conflicts in the merge.
E
Log when a file is exported.
F
Log when a file is released.
G
Log when a file is updated in a sandbox with a successful merge.
M
Log when a file is modified (a sandbox revision is added to the repository).
O
Log when a file is checked out.
R
Log when a file is removed from the repository.
T
Log when a file is tagged or rtagged.
U
Log when a file is updated in a sandbox with no merge required.
W
Log when a file is deleted from a sandbox during an update because it is no longer active in the repository.

RCSBIN=directory
This option provides the directory in which CVS should look for the rcs program. This option applies only to CVS Versions 1.9.12 to 1.9.18; it is obsolete and ignored in later versions.

RereadLogAfterVerify=value
The log message saved during cvs commit might be changed if the verifymsg file is in use. This option controls whether the message is reread after the program listed in the verifymsg file runs.

This option is useful only if the verifymsg file is in use. These are the available options:

always or yes
Reread the log message after the verifymsg file has been processed. This option is the default case.
never or no
Do not reread the log message after the verifymsg file has been processed.
stat
Check whether the log message has been changed, using the filesystem's stat( )command. If it has changed, reread the log message. This option can take up to an extra second per directory to process than the never case, but it may be faster than always if the log messages aren't always changed by verifymsg.

SystemAuth=value
If value is yes, the server authenticates the connecting user with the passwd file. If the user fails to authenticate there, the server authenticates the user against the main user database for the operating system. If value is no, the server authenticates the user only against the passwd file. The default value is yes.

Warning

SystemAuth=yes weakens security, because CVS transmits passwords using only trivial encryption. The encryption can easily be broken, and a password obtained. The SystemAuth=yes setting uses the operating system's own authentication mechanism, so the obtained password will provide access to the user's shell account.

This option is useful only if you have clients connecting to CVS in pserver mode.

TopLevelAdmin=value
If value is yes, a CVS subdirectory is created in the current working directory when you check out a sandbox. If value is no, the CVS subdirectories are created only in the actual sandbox directory tree. The default is no.
PreservePermissions=value
CVS 1.11.5 does not support this option. In the versions that support it, the option causes CVS to store sandbox permissions in the repository with other data for each revision and pass that data to the sandbox when a file revision is checked out. The valid values are yes and no.

UserAdminOptions=value
This option is available in CVS 1.12.1 and later. If value exists, then any user can run cvs adminoptions listed in value. The contents of value must be a string of letters with no separators or spaces, and the letters must be the command options (without parameters) for cvs admin.

If the cvsadmin group exists on the server machine, then only members of the cvsadmin group are allowed to run commands not listed in value.


The cvsignore File

The cvsignore file contains a list of filenames or filename patterns that CVS should not process. The syntax for this file is a space-separated or line-ending-separated list of filenames or name patterns. cvsignore uses wildcard pattern matching.

The special ! filename causes CVS to clear its ignore list. The special * filename causes CVS to ignore everything.

The cvswrappers File

The cvswrappers file contains a line-ending-separated list of wrappers that control the merge method or keyword-substitution mode of files, based on a filename pattern. The syntax of a wrapper is as follows:

                  wildcard 
                  option value [option value...]

The wildcards are matched to filenames when files are added to the repository.

These are the options and values:

-m 'mode'
Indicates the merge methodology to use for files that match the pattern. Valid modes are COPY or MERGE.
-k 'mode'
Indicates the keyword-expansion mode to use for files that match the pattern. The keyword-expansion modes are provided in Section 11.6 later in this chapter.
-f 'path_to_filter'
Process the file through the filter program every time the file leaves the repository. This option is not available in CVS 1.10 and later.
-t 'path_to_filter'
Process the file through the filter program every time the file enters the repository. This option is not available in CVS 1.10 and later.

The editinfo File

The editinfo file is obsolete; it has been replaced by verifymsg and rcsinfo. In CVS versions that use editinfo, this file enforces the use of a specific editor when entering log messages. If CVS is called from a remote client, or if the -m or -F command options are used with cvs commit, the editinfo file is not used. If the editor exits with a nonzero exit status, the commit does not proceed.

The history File

The history file contains the information displayed by the cvs history command. It must be writable by all CVS users and is created by cvs init to be owner-, group-, and world-writable. This file should not be edited manually; all changes should occur through CVS.

If you wish to turn history logging off, a simple way to do so is to rename the history file. The file can also be removed or rotated like any log file, with no effect on any CVS command other than cvs history. (If you do rotate the file, consider whether to lock the repository during the process of moving the file.)

The loginfo File

The loginfo file defines programs to run when the file has been committed successfully. These programs run on the repository computer.

Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any pattern except ALL. CVS uses the script on the first line with a directory-name pattern that matches the directory tree the file is in. If no pattern match is found, the script specified by the DEFAULT line is executed. Scripts specified by ALL lines are always executed.

The file syntax is as follows:

                  name_pattern 
                  action
               

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the address of a script, plus any parameters required for that script or template, plus a format string. The action is passed the log message on the standard input, followed by the repository path and the results of the format string.

The format string is processed by CVS before being passed to the action's script or command. Before processing, the format string consists of a % , followed by a space, a single variable, or a set of variables enclosed in braces ({ }). These are the variables for the format string:

s
Expands to the name of the current file being processed.
V
Expands to the file's revision number prior to the commit.
v
Expands to the file's revision number after the commit.

When CVS processes the format string, the output passed to the script is a space-separated list of variable expansions, with a variable expansion for each file that was committed. The series of variable expansions is a comma-separated set of strings, such that %{sV} could be expanded to a string like main.c,1.3.

Dollar signs ($), backticks (`), backslashes (\), and quotation marks (") in the repository path or in any filenames expanded from the format string are escaped with a backslash, but the backslash is not visible in the called scripts.

The modules File

The modules file is used to group arbitrary files or directories into a single module. Once a module is defined, the project files and directories it defines can be checked out into a sandbox by either the module name or the name of the repository directory it represents. The modules file can also specify programs to run when files in the module are committed, exported, updated, checked out, or tagged with rtag.

Each module definition needs to be on a line of its own. When adding directories to module definitions, use paths relative to the repository root directory.

An alias module can be used to group files and directories into a single module, regardless of where they are stored in the repository tree. The syntax for an alias module definition is as follows:

                  module_name -a path [path...]

A path may be a pathname to a file or directory or it may be another module name, and there may be any number of paths. If a path leads to a directory, all subdirectories and files are included in the module. If you wish to exclude subdirectories from an alias module, use an exclamation mark (!) in front of the directory name.

A regular module is used to define options for a project. It can also be used to define subsets of a project or group modules together. The syntax of a regular module is as follows:

                  module_name [options] [directory [files|subdirectories...]] [&modules...]

The directory should be a path relative to the repository root directory. If filenames or subdirectory names are included, they should be in the directory and the module definition then applies only to those files or subdirectories. You can include a predefined module in a regular module by prefixing the module name with an ampersand (&) and specifying the resulting name in place of directory in the syntax. The module can be a regular module or an alias module.

Most of the options for a regular module define scripts to run immediately after a CVS command on the files in the module. Here is the full list of options for regular modules:

-d directory_name
Use directory_name rather than the module name as the name of the sandbox root directory.
-e script
Run the script when the module is exported. The script is given the module name as an argument.
-i script
Run the script when the module is committed. The script is given the full pathname of the relevant repository directory as an argument. This option is obsolete in CVS 1.11.6 and later.
-o script
Run the script when the module is checked out. The script is given the module name as an argument.

-s status
Provide a status for the module. This has no meaning internal to CVS, but when the cvs checkout -scommand runs, the status affects the display order.

CVS allocates an 11-character space for the status string when it is displayed, but the string is not truncated if it is longer than 11 characters.

-t script
Run the script when rtag is used on the module. This option does not run when tag is used. The script is given two arguments: the module name and the name of the tag.
-u script
Run the script when the module is updated. The script is given the full pathname of the affected repository directory as an argument. This option is obsolete in CVS 1.11.6 and later.

Each script designated in the modules file runs immediately after its associated CVS command completes. For example, the -o script runs after a checkout command for the module completes.

If the repository is not on the same computer as the client, the scripts for the -i and -uoptions are copied from their original location in the repository to the client computer and stored in the Checkin.prog and Update.prog files in the CVS subdirectories in the sandbox. These scripts are later copied back to the server computer, where they run. For security reasons, this behavior is changed in CVS 1.11.6 and later.

All other scripts called from the modules file run on the repository server computer.

The sandbox copies of the Checkin.prog and Update.prog files are not changed when the modules file or the repository computer's copies of the scripts are changed. To change Checkin.prog and Update.prog, commit and release the sandbox and check out a new sandbox.

The notify File

The notify file contains the commands to run when conditions exist for cvs watch to notify a user of a change to a watched file.

The syntax of the notify file is a series of lines, each line in the following format:

                  filename_pattern 
                  command
               

The filename_pattern can be ALL or any wildcard pattern. The command can be any sh shell command, but it must contain %s, which is replaced by the name of the user to notify. The rest of the notification information is provided to the command through standard input (stdin).

Tip

CVS does not notify you of your own changes to a file.

The passwd File

The passwd file contains the usernames and passwords for the pserver repository method. This file is usually edited in place, not checked out like the other administrative files. If you wish to check it out, add it to the commitinfo file, but be aware of the security risks explained in Chapter 8.

The format for entries in the passwd file is:

                  CVS_username:password:system_username
               

The CVS_username is the name the user sends to CVS. The system_username is the name the CVS programs run under. If these names are the same, you don't need to include the system_username. The system_username must be a valid username on the server; if the system_username does not exist on the server, CVS commands will fail even if the user authenticates with CVS.

The passwords need to be encrypted with the standard Unix crypt( ) function. CVS does not provide a tool to encrypt passwords, so they need to be encrypted elsewhere and then pasted into the file. If the password field is empty, the user automatically authenticates. You can use the Unix and Linux program mkpasswd to encrypt a string for use as a password.

A single system username can be shared by multiple users with different CVS usernames. This can allow several people to work on a project, while recording the changes across multiple users.

The rcsinfo File

The rcsinfo file defines forms to display as the templates for commit log messages. The rcsinfo file is processed before a file is committed.

The file syntax is:

                  name_pattern 
                  action
               

The name_pattern is a regular expression that must match a relative path within the repository. The action is the path to a template file for log messages.

Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any other pattern. CVS uses the file on the first line with a directory name pattern that matches the directory tree the file is in. Files in each directory are processed according to the rules given in the first matching line or in the DEFAULT line. In addition, rules given in ALL lines are always applied.

If the repository is not on the same computer as the client, CVS stores a copy of the template (or templates) that matches each sandbox directory in the appropriate CVS subdirectory of each sandbox. This file is not updated with other sandbox files, so if the rcsinfo file or the main template changes, your users should release and recreate their sandboxes.

The readers File

The readers file contains the usernames of people who have read-only access to the repository via the pserver remote-access method. The readers and writers files use the CVS_username, not the system_username, to determine whether a user has access. The file should contain one name per line. The newline character after the last username is significant.

If a user is listed in the readers file, he has read-only access to the repository, even if he is also listed in the writers file.

The taginfo File

The taginfo file defines programs to run before a file is tagged. If any of the programs exit with a nonzero exit status, the tag does not proceed.

The file syntax is:

                  name_pattern 
                  action
               

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the path and filename of a script, plus any parameters required for that script or template. The full path of the repository and the filenames of all files to be committed are appended as parameters.

Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any other pattern. CVS uses the script on the first line with a directory-name pattern that matches the directory tree the file is in. Files in each directory are processed according to the rules given in the first matching line or in the DEFAULT line. In addition, rules given in ALL lines are always applied.

A string with the following format is appended to the script parameters:

                  tagname 
                  operation 
                  repository_path 
                  file_revision_pair [file_revision_pair...]

The file_revision_pair is a space-separated filename and revision number, and there is one pair for each file to be tagged. The operation is add, mov, or del. The mov operation is used when tag or rtag is called with -F, and del is used when they are called with -d.

The users File

The users file provides a list of email addresses for users whose mailboxes are not on the same machine as the CVS repository. This file is used by the command given in the notify file, and it becomes the input represented by the %s string.

The format of this file is a separate line for each user, consisting of the username and the email address to send notifications to, in the following format:

                  username:email
               

Tip

If you are using the pserver access method, use the system usernames in the users file.

The val-tags File

The val-tags file contains a list of valid tag names, acting as an internal cache for CVS. It must be writable by all CVS users, and is created by cvs init to be owner- and group-writable. This file should not be edited manually; all changes should occur through CVS.

The verifymsg File

The verifymsg file defines programs to run after a log message has been entered, but before the commit takes place. The programs are passed the log message, which they can modify or parse to ensure that all essential fields have been filled in. The verifymsg file is usually used with the rcsinfo file to manage log messages. If a program called from verifymsg exits with a nonzero error status, the commit is aborted.

The file syntax for verifymsgis as follows:

                  name_pattern 
                  action
               

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the address of a script, plus any parameters required for that script or template. The log message is passed to the script or template on the standard input (stdin), as is the path to a temporary file containing the log message.

Lines starting with the hash symbol (#) are comments and are ignored. The special DEFAULT pattern matches directories that do not match any other pattern. CVS uses the script on the first line with a directory-name pattern that matches the directory tree a file is in.

A script invoked through verifymsg can modify the log message, and the config file in the CVSROOT directory then determines whether CVS reads and uses the modified log message or the original one for the rest of the commit process.

The writers File

The writers file contains the usernames of people who have read-write access to the repository via the pserver remote-access method. The readers and writers files use the CVS username, not the system username, to determine whether a user has access. The file should contain one username per line. The newline character after the last user is significant.

If a user is listed in the writers file but not the readers file, she has read-write access to the repository.

Tip

Being listed in the readers file is enough to consign a user to read-only access, regardless of whether that user is also listed in the writers file.

CVSROOT Variables

The administrative files in CVSROOT can use several types of variables: internal, environment, and shell variables. You can use these variables to pass parameters to the scripts in the scripting files, or you can use them as part of command-line templates.

The internal variables allow you to use information CVS stores about the currently running command. The environment variables are used to access information from the environment the command is running in, and the shell variables are used to access information about the shell.

Environment Variables in CVSROOT Files

Three environment variables are set when CVS runs commands or scripts from CVS administrative files:

CVS_USER
This variable is meaningful only with the pserver access method. It refers to the CVS username provided in the leftmost field of the appropriate line in CVSROOT/passwd. If this username does not exist, the variable expands to an empty string.

LOGNAME and USER
Both of these variables contain the username of the user calling the CVS process.

In the pserver access method, the username is the third field of the line in passwd. If no username is there, the CVS_USER value is used.


Internal Variables in CVSROOT Files

The syntax for referencing a CVS internal variable is ${VARIABLE}. The $VARIABLE syntax can also be used if the character immediately following the variable is neither alphanumeric nor an underscore (_).

These are the internal CVS variables:

CVSROOT
The path to the repository root directory (not the path to the CVSROOT directory within the repository). This variable contains the path only, not any access method or host information.
CVSEDITOR or EDITOR or VISUAL
The editor CVS is using. If you use the -e editor CVS option, CVS uses the editor you specify on the command line. If you don't use -e, CVS reads the environment variables and uses the first editor it finds. CVS uses CVSEDITOR by preference, then EDITOR, then VISUAL.

USER
The username (on the server machine in client/server mode) of the user running CVS.

With the pserver access method, this is the third field of the appropriate line in passwd. If no username is there, it is the name in the leftmost field.

RCSBIN
This variable applies only to CVS 1.9.18 or earlier. It contains the path to the rcs executable.

CVS permits user-defined variables that can be passed to administrative files from the client. In the administrative files, reference such a variable with the syntax ${=VARIABLE}. On the command line, use the -s variable=value CVS option to pass the variable to CVS. All strings that contain the $ symbol, other than the variable references, are reserved for CVS internal use. There is no way to escape the $symbol.

Shell Variables in CVSROOT Files

Two shell variables are also used in the administrative files:

~/
The home directory of the user calling the CVS process.
~username
The home directory of the user identified as username.

Dates

In CVS, all dates and times are processed by a version of the GNU getdate function, which can translate dates and times given in several different formats. Case is always irrelevant when interpreting dates. Spaces are permitted in date strings, but in the command-line client a string with spaces should be surrounded by quotes. If the year is 0 to 99, it is considered to be in the twentieth century.

If a time is not given, midnight at the start of the date is assumed. If a time zone is not specified, the date is interpreted as being in the client's local time zone.

Legal Date Formats

The legal time and date formats for CVS are defined by the ISO 8601 standard and RFC 822 as amended by RFC 1123. Other formats can be interpreted, but CVS is designed to handle only these standards.

ISO 8601

The basic ISO 8601 date format is as follows:

                     year-month-day 
                     hours:minutes:seconds
                  

All values are numbers with leading zeros to ensure that the correct number of digits are used. Hours are given in 24-hour time. This produces the structure YYYY-MM-DD HH:MM:SS, which is internationally acceptable and can be sorted easily. You can use a date, a time, or both.

If you're using ISO 8601 format with the hyphens, the full date is required in CVS. The YYYYMMDD date format is also acceptable and can be abbreviated to YYYYMM or YYYY.

The HH and HH:MM time formats are acceptable. Times can also be specified without the colon, so HHMMSS or HHMM are usable.

Warning

Be aware that HHMM may be misinterpreted as YYYY. Get into the habit of using separators.

In strict ISO 8601 format, a T is required between the date and the time, but CVS understands this format with or without the T. The ISO 8601 standard also states that a Z at the end of the string designates UTC (Universal Coordinated Time), but CVS does not recognize the use of Z.

RFC 822 and RFC 1123

RFCs 822 and 1123 define a precise time format:

[DDD ,] DD 
                     MMM 
                     YYYY 
                     HH:MM[:SS] ZZZ
                  

These are the terms in the format:

DDD
A three-letter day of the week
DD
A two-digit date of the month
MMM
A three-letter month
YYYY
The year (it must be a four-digit year)
HH
Hours
MM
Minutes
SS
Seconds
ZZZ
The time zone (can be the text abbreviation, a military time zone, or an offset from UTC in hours and minutes)

Legal Date Keywords

CVS also allows short English phrases such as "last Wednesday" and "a month ago" to be used in placed of actual dates. Case is not significant, and CVS can understand plurals. These are the keywords it understands:

Month names
January, February, March, April, May, June, July, August, September, October, November, and December
Month abbreviations
Jan, Feb, Mar, Apr, Jun, Jul, Aug, Sep, Sept, Oct, Nov, and Dec
Days of the week
Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday
Day abbreviations
Sun, Mon, Tue, Tues, Wed, Wednes, Thu, Thur, Thurs, Fri, and Sat
Units of time
year, month, fortnight, week, day, hour, minute, min, second, and sec
Relative times
tomorrow, yesterday, today, and now
Meridian qualifiers
am, pm, a.m., and p.m.
Modifiers
a, last, this, next, and ago
Sequences
first, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, and twelfth(second can't be used as a sequence term, because it is used as a time unit.)

Time Zones

CVS understands time zones expressed in offsets from UTC, such as +0700(7 hours ahead) and -1130 (11 hours, 30 minutes behind). The format for these time zones is +HHMM or -HHMM, where + means ahead of UTC and - means behind UTC. CVS also understands time-zone abbreviations and ignores case and punctuation when interpreting them.

Tip

Some of the time-zone abbreviations CVS recognizes are ambiguous. CVS recognizes only one meaning for each of the ambiguous time zones. However, which meaning is recognized may vary depending on your operating system, and on how CVS was configured when it was compiled.

Table 11-1 shows the valid civilian time-zone abbreviations for CVS. Table 11-2 shows military time-zone abbreviations that CVS recognizes.

Table 11-1. Civilian time-zone abbreviations

gmt +0000 Greenwich Mean met -0100 Middle European
ut +0000 Coordinated Universal Time mewt -0100 Middle European Winter
utc +0000 Coordinated Universal Time mest Middle European Summer
wet +0000 Western European swt -0100 Swedish Winter
bst +0000 British Summer (ambiguous with Brazil Standard) sst Swedish Summer (ambiguous with South Sumatra)
wat +0100 West Africa fwt -0100 French Winter
at +0200 Azores fst French Summer
bst +0300 Brazil Standard (ambiguous with British Summer) eet -0200 Eastern Europe, USSR Zone 1
gst +0300 Greenland Standard (ambiguous with Guam Standard) bt -0300 Baghdad, USSR Zone 2
nft +0330 Newfoundland it -0330 Iran
nst +0330 Newfoundland Standard (ambiguous with North Sumatra) zp4 -0400 USSR Zone 3
ndt Newfoundland Daylight zp5 -0500 USSR Zone 4
ast +0400 Atlantic Standard ist -0530 Indian Standard
adt Atlantic Daylight zp6 -0600 USSR Zone 5
est +0500 Eastern Standard nst -0630 North Sumatra (ambiguous with Newfoundland Summer)
edt Eastern Daylight sst -0700 South Sumatra, USSR Zone 6 (ambiguous with Swedish Summer)
cst +0600 Central Standard wast -0700 West Australian Standard
cdt Central Daylight wadt West Australian Daylight
mst +0700 Mountain Standard jt -0730 Java
mdt Mountain Daylight cct -0800 China Coast, USSR Zone 7
pst +0800 Pacific Standard jst -0900 Japan Standard, USSR Zone 8
pdt Pacific Daylight cast -0930 Central Australian Standard
yst +0900 Yukon Standard cadt Central Australian Daylight
ydt Yukon Daylight east -1000 Eastern Australian Standard
hst +1000 Hawaii Standard eadt Eastern Australian Daylight
hdt Hawaii Daylight gst -1000 Guam Standard, USSR Zone 9 (ambigous with Greenland Standard)
cat +1000 Central Alaska nzt -1200 New Zealand
ahst +1000 Alaska-Hawaii Standard nzst -1200 New Zealand Standard
nt +1100 Nome nzdt New Zealand Daylight
idlw +1200 International Date Line West idle -1200 International Date Line East
cet -0100 Central European


Table 11-2. Military time-zone abbreviations

a +0100 f +0600 l +1100 q -0400 v -0900
b +0200 g +0700 m +1200 r -0500 w -1000
c +0300 h +0800 n -0100 s -0600 x -1100
d +0400 i +0900 o -0200 t -0700 y -1200
e +0500 k +1000 p -0300 u -0800 z 0000

Environment Variables

Several environment variables affect CVS. Some are read only when CVS is the client, and some are read only when CVS is the server. In local or fork modes, both sets are read.

Client Environment Variables

The environment variables in the following list are read and used by the process that runs on the client computer and must be in the calling user's environment:

COMSPEC
OS/2 only. This variable sets the command interpreter and defaults to CMD.EXE.
CVS_CLIENT_LOG
Used for debugging CVS in client/server mode. If set, everything sent to the server is stored in the CVS_CLIENT_LOG.in file, and everything received by the client is stored in CVS_CLIENT_LOG.out.
CVS_CLIENT_PORT
Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, the client uses port 2401 (gserver and pserver) or port 1999 (kserver) to connect to the server.
CVSIGNORE
A whitespace-separated list of filename patterns that should be ignored. See Section 11.2.4 earlier in this chapter.
CVS_IGNORE_REMOTE_ROOT
Obsolete since CVS 1.10. When set, it prevented CVS from overwriting the CVS/Root file if the -d repository_path option was set. CVS no longer overwrites the file.
CVSEDITOR or EDITOR or VISUAL
Used to set the editor CVS calls when it opens an editor for log messages. On Unix and Linux systems, the default editor is vi. Using CVSEDITOR is preferred over EDITOR and VISUAL, as other variables may be used by other programs.
CVS_PASSFILE
Used to change the file CVS uses to store and retrieve the password in pserver remote-access mode. The default file is HOME/.cvspass.
CVS_RCMD_PORT
Not currently in use. It used to be set to the port number for the server's rcmd (remote command) daemon if the port was nonstandard.
CVSREAD
If set to 1, CVS tries to check out your sandbox in read-only mode. (CVS actually checks whether this variable is nonnull, so it works regardless of the setting. This behavior may change in the future.)
CVSROOT
Contains the full pathname of the CVS repository, as described in Chapter 3. When you're working in a sandbox, this variable is not needed. If you're working outside a sandbox, either this variable must be present or the -d repository_path option must be used.
CVS_RSH
Used to set the program CVS calls to connect to a remote repository in ext mode. The default program is rsh.
CVS_SERVER
If connecting to a CVS server using rsh, this variable is used to determine which program is started on the server side. In ext and server modes, this defaults to cvs. In fork mode, this defaults to the path to the CVS client program.
CVSWRAPPERS
May contain one wrapper but no more than one, as explained in Chapter 3.
HOME or HOMEPATH or HOMEDRIVE
Used to determine where the user's home directory is, to enable CVS to locate its files. On Unix, Linux, and related systems, only HOME is used. On Windows systems, HOMEDRIVE and HOMEPATH are used. Some Windows operating systems (Windows NT, 2000, and XP) set these variables automatically. If yours doesn't, HOMEDRIVE should be set to the drive letter (e.g., C:) and HOMEPATH should be set to the path (e.g., \home\jenn).
PATH
Used to locate any programs whose path is not compiled with the CVS program. This variable is still used, but it is less important now that the rcs, diff, and patch programs CVS uses are all distributed with CVS.
RCSBIN
Obsolete in CVS 1.9.20 and later. It was used for the path to the external rcs executable, before rcs was added to the CVS distribution.

Server Environment Variables

The following variables are read when CVS is operating as the server (or in local or fork modes). They must be in the calling user's environment on the server computer.

CVS_SERVER_SLEEP
Used only when debugging the server in client/server mode. This variable delays the start of the server client process by CVS_SERVER_SLEEP seconds to allow the debugger to be attached to it.

CVSUMASK
Used to set the default permissions of files in the repository. See Chapter 6 for information on securing your projects.

This variable may be added to the client code in a later version of CVS.

PATH
Used to locate any programs whose path is not compiled with the CVS program. This variable is still used, but it is less important now that the rcs, diff, and patch programs CVS uses are all distributed with CVS.

TMPDIR
Sets the temporary directory CVS stores data in. This variable defaults to /tmp.

CVS creates temporary files with mkstemp (BSD 4.3), if possible. If mkstemp is not available when CVS is compiled, it tries tempnam (SVID 3), mktemp (BSD 4.3), or tmpnam (POSIX), in that order. If it uses tmpnam, it cannot use the TMPDIR environment variable and files are created in /tmp.


Keywords and Keyword Modes

CVS contains keywords that can be included in nonbinary project files. When CVS finds a keyword in a file it is checking out, it expands the keyword to provide metadata about the latest revision of the file. You can set keyword-expansion modes on a file to tell CVS whether (and how) to expand the keywords it finds.

Keyword-expansion modes also control line-ending conversion. Unix, Macintosh, and Windows operating systems use different sets of codes to signal the ends of lines. (Linux uses the same codes as Unix.) When you commit a file from an operating system that doesn't use Unix line endings, CVS converts the line endings to Unix style. If you are storing binary files, this conversion can corrupt the file. Use the -kb keyword-expansion mode to tell CVS not to convert line endings.

CVS keywords take the form:

$Keyword$

All keywords except Log expand to the format:

$Keyword: value$

These are the keywords and the information they show about the file they are in:

Author
The username of the user who committed the last revision.
Date
The date on which the last revision was committed, in UTC.
Header
A header containing information about the file, including the author, date and revision number, path and filename of the RCS file (project file in the repository), file status, and whether the file is locked. See Chapter 5 for information about file locking.
Id
A header like the one given by the Header keyword, without the path of the RCS file.
Name
The tag name the file was checked out with. This keyword can display a branch or provide a more meaningful identification of a revision than the revision number alone. See Chapter 4 for more information about tags and branches.
Locker
The username of the user who locked the file with cvs admin -l (empty if the file is not locked).

Log
The commit messages, dates, and authors for the file. This keyword instructs CVS to store this information in the file itself. Any characters that prefix the keyword are also used to prefix log lines; this enables comment markers to be included automatically. Unlike most keywords, existing log expansions are not overwritten with the new ones; the new log expansions are merely prepended to the list.

Tip

The cvs log command displays all the information that the Logkeyword provides.

The Log keyword is best used at the end of a file, to avoid users having to go through all the log messages to get to the important parts of the file.

The log created by the Log keyword does not merge neatly when CVS merges a branch back to the trunk. If your file is likely to be branched and remerged, it is better to use the cvs log command than to store a log within the file.

RCSfile
The name of the RCS file (the project file in the repository).
Revision
The CVS internal revision number of the file. This number is specific to the individual file and does not identify a stage within the project.
Source
The name and path of the RCS file (the project file in the repository).
State
The current state assigned to the current revision, set with cvs admin -s. See Chapter 7.

The keyword-expansion modes in the following list are used in commands and CVS wrappers to control keyword expansion and line-ending conversion. The syntax differs slightly for each use. In commands, you use the mode without a space between the option and the mode (e.g., -kb). In wrappers, you need a space and may need to quote (e.g., -k 'b').


b
Inhibit keyword expansion and line-ending conversion. Use this keyword-expansion mode to signal that a file is binary.

CVS can convert line endings from the form appropriate to the server to the form appropriate to the client. This causes obvious problems when working with binary files.

k
Generate only a keyword name, not a name and value. Use this option when merging different (nonbinary) versions of a file, to prevent keyword substitution from creating spurious merge errors. This option can corrupt binary files.
o
Generate the version of a keyword string that was present just before the current file was last committed, rather than generating a version with the modifications of the last commit. This option is similar to -kb, but with line-ending conversion.
v
Generate only the value of a keyword, rather than the name and value. This is most useful with cvs export, but do not use it for binary files. Once any keyword is removed from a file, further expansions are not possible unless the word is replaced.
kv
Generate the name and value of a keyword. This is the default mode.
kvl
Generate the name and value of a keyword and add the name of the locking user if the revision is locked with cvs admin -l.

Pattern Matching

CVS uses two different forms of pattern matching, depending on which aspect of CVS is attempting to match the pattern. Most CVS functions use sh-style wildcards, but the scripting files in the CVSROOT directory use regular expressions.

This section is not a comprehensive study of regular expressions or wildcards. For a more complete discussion of regular expressions, I recommend Mastering Regular Expressions (O'Reilly) by Jeffrey E. F. Friedl.

Wildcards

Wildcards are used by most CVS functions, including wrappers and ignore files. The wildcards are evaluated by a version of the fnmatch standard function library distributed with CVS.

The wildcards are sh-style, and the symbols used in CVS include:

?
Matches any single character.
\
Escapes the special symbols, so they can be used as literals.
Matches any string, including the empty string.

[ ]
Matches any one of the enclosed characters. Within the brackets, the following symbols are used:

! or ^
If either of these characters is the first character after the open bracket, the brackets match anything that is not included in the brackets.

char1-char2
Denotes the range of characters between char1 and char2.

Regular Expressions

CVS supports regular expressions in the scripting files in the CVSROOT directory. In CVS 1.11.5, the scripting files are the only files that support regular expressions; all other files and functions use pattern matching. The scripting files are commitinfo, editinfo, loginfo, rcsinfo, taginfo, and verifymsg.

CVS regular expressions are based on the GNU Emacs regular-expression syntax, but they do not implement all of the Emacs operators. The regular expressions are parsed by a version of the regex standard function library distributed with CVS.

The CVS regular-expression operators include:

^
Matches the beginning of a line. Use ^foo to match foo at the beginning of a line.
$
Matches the end of a line. Use foo$to match foo at the end of a line.
.
Matches any single character, except a newline character. The expression foo.bar matches foosbar and foo:bar, but not foodiebar.

*
Repeats the previous element zero or more times. The expression fo*bar matches fobar, foobar, fooobar, and any other string in that pattern.

The pattern matcher tries to match the longest string possible. If the next part of the expression fails to match, the pattern matcher rolls back one character at a time in an attempt to match the string. If it is parsing the regular expression fo*obar against the string fooobar, it initially matches the expression fo* against fooo. It then rolls back to matchfo*against foo, thus freeing the obar in the string to match the obar in the expression.

+
Repeat the previous element one or more times. This operator is similar to the * operator and is processed the same way.
?
Repeat the previous element zero times or one time. The expression fo*bar matches fobar or foobar, but nothing else.
\
Escape the next character (\^ is a literal carat). Also used as part of some operators.
\|
The OR operator. Match the element on the left or the element on the right to the end of the string, enclosing parenthesis, or another OR operator.
+? or *? or ??
The same as the+, *, and ? operators, except that they attempt to match the shortest string possible rather than the longest.

[...]
A character set. Any of the characters in the character set can be matched. The [fba] character set matches any one (and only one) of f, b, or a. With the *operator, the expression[fba]* matches any sequences composed of zero or more f, b,or acharacters.

The only special characters or operators inside a character set are -, ], and ^. To include a ] in a character set, use it as the first character. To include a -, use it as the last character or just after a range. To use a ^, use it anywhere except as the first character.

A character range can be specified inside a character set. Create a range by using a hyphen between the start and end of the range. a-z and 0-9 are common ranges. Note that the behavior of a mixed-case range such as A-z is undefined; use [a-zA-Z] instead.

[^...]
A complemented character set. This operator matches everything except the characters or ranges inside the set.

A ] or - that immediately follows the ^ is treated as the literal character.

\(...\)
Group expressions together so that an operation works on the set. The expression ba\(na\)+ matches bana, banana, bananana, and similar sequences.

Repository Access Methods

CVS provides a variety of ways to access the repository. These methods are briefly described in the following sections, and Chapter 8 explains them in more detail.

Client Side

On the client side, you specify the access method as part of the repository path. If you don't declare one of the following methods, CVS assumes either the local or ext method:

local
Connect to a repository on the same computer as the sandbox, but do not use client/server mode.
ext
Connect with an externally defined rsh or rsh-like connection method (such as ssh). If you use anything other than rsh, the CVS_RSH environment variable must be set on the client computer.
fork
Connect to a repository on the same computer as the sandbox as if it were a remote machine. This method is useful if you are trying to diagnose problems with client/server mode.
gserver
Connect to the repository using the GSS-API and Kerberos 5.
kserver
Connect to the repository using Kerberos 4.
pserver
Connect to the repository using CVS's internal password server.
server
Connect to the repository using CVS's internal rsh server (not always available).

Server Side

The kserver, gserver, and pserver access modes require a server to run on the repository computer. For these modes, the server is started with inetd or xinetd. The inetd configuration must be on one line and should call CVS with the --allow-root and -foptions and the pserver or kserver command.

The parameter to the --allow-root option is the path to the repository root directory. If you intend to have several repository root directories, add more --allow-rootoptions.

If your version of inetd doesn't allow you to use port numbers in inetd.conf, add appropriate lines to /etc/services and use those service names instead of the port number in inetd.conf.

These are the two commands the server can use:

kserver
Accept Kerberos 4 connections.
pserver
Accept pserver (password server) and gserver (GSS-API) connections.
Personal tools