Book HomeLinux in a NutshellSearch this book

14.4. CVS User Reference

This section provides details on connecting to a repository, the structure of sandboxes, and using the CVS commands.

14.4.1. Repository Locators

CVS currently supports five methods for the client to access the repository: local, external, a password server, a GSS-API (Generic Security Services API) server, and a Kerberos 4 server (most Kerberos users will want to use GSS-API). Table 14-12 describes the various repository locator types and their respective access methods.

Table 14-12. Repository Access Types and Methods

Method

Locator Format

Description

Local

path

If the repository directory is local to the computer from which you will access it (or appears local, such as an NFS or Samba mounted filesystem), the repository string is just the pathname of the repository directory, such as /usr/local/cvsrep.

External

:ext:user@host:path

External repositories are accessed via a remote shell utility, usually rsh (the default) or ssh. The environment variable $CVS_RSH is used to specify the remote shell program.

Password server

:pserver:user@host:path

Password server repositories require authentication to a user account before allowing use of the repository. Public CVS servers are commonly configured this way so they can provide anonymous CVS access. See Section 14.3.3.11, "The passwd file", earlier in this chapter, for more information on anonymous CVS.

GSS-API server

:gserver:

This locator type is used for servers accessible via Kerberos 5 or other authentication mechanisms supported by GSS-API.

Kerberos server

:kserver:

This locator type is used for servers accessible via Kerberos 4.

14.4.2. Configuring CVS

CVS's behavior can be influenced by two classes of settings other than the command-line arguments: the environment variables (see Table 14-13) and special files (see Table 14-14).

Table 14-13. Environment Variables

Variable

Description

$COMSPEC

Command interpreter on OS/2, if not cmd.exe.

$CVS_CLIENT_LOG

Client-side debugging file specification for client/server connections.

$CVS_CLIENT_LOG is the basename for the $CVS_CLIENT_LOG.in and $CVS_CLIENT_LOG.out files, which will be written in the current working directory at the time a command is executed.

$CVS_CLIENT_PORT

$CVS_IGNORE_REMOTE_ROOT

The port number for :kserver: locators.

$CVS_CLIENT_PORT doesn't need to be set if the kserver is listening on port 1999 (the default).

According to the ChangeLog, this variable was removed from CVS with Version 1.10.3.

$CVS_PASSFILE

Password file for :PSERVER: locators. This variable must be set before issuing the cvs login to have the desired effect. Defaults to $HOME/.cvspass.

$CVS_RCMD_PORT

For non-Unix clients, the port for connecting to the server's rcmd daemon.

$CVS_RSH

Remote shell for :ext: locators, if not rsh.

$CVS_SERVER

Remote server program for :ext: locators, if not cvs.

$CVS_SERVER_SLEEP

Server-side execution delay (in seconds) to allow time to attach a debugger.

$CVSEDITOR

Editor used for log messages; overrides $EDITOR.

$CVSIGNORE

A list of filename patterns to ignore, separated by white space. (See also cvsignore in Table 14-4 and .cvsignore in Table 14-14.)

$CVSREAD

Determines read-only (if the variable is set) or read/write (if the variable is not set) for checkout and update.

$CVSROOT

Default repository locator.

$CVSUMASK

Used to determine permissions for (local) repository files.

$CVSWRAPPERS

A list of filename patterns for the cvswrappers function. See also Section 14.3.3, "Repository Structure".

$EDITOR

Specifies the editor to use for log messages; see notes for $CVSEDITOR earlier in this table.

$HOME

On Unix, used to find the .cvsrc file.

$HOMEDRIVE

On Windows NT, used to find the .cvsrc file.

$HOMEPATH

On Windows NT, used to find the .cvsrc file.

$PATH

Used to locate programs to run.

$RCSBIN

Used to locate RCS programs to run. This variable is obsolete.

$TEMP

$TMP

$TMPDIR

Location for temporary files. $TMPDIR is used by the server. On Unix, /tmp (and TMP on Windows NT) may not be overridden for some functions of CVS due to reliance on the system's tmpnam() function.

Despite the similarity in names, the $CVSROOT environment variable and the CVSROOT directory in a repository are not related to each other.

The "RSH" in the name of the $CVS_RSH environment variable doesn't refer to the particular program (rsh), but rather to the program CVS is supposed to use for creating remote shell connections (which could be some program other than rsh, such as ssh).

Since there is only one way to specify the remote shell program to use ($CVS_RSH), and since this is a global setting, users that commonly access multiple repositories may need to pay close attention to which repository they are using. If one repository requires one setting of this variable and another requires a different setting, then you will have to change this variable between accesses to repositories requiring different settings. This aspect of the repository access method is not stored in the CVS/Root file in the sandbox (see Section 14.4.4.3, "CVS directories", later in this chapter). For example, if you access some repositories via rsh and some via ssh, then you can create the following two utility aliases (bash syntax):

user@localhost$ alias cvs="export CVS_RSH=ssh; cvs" 
user@localhost$ alias cvr="export CVS_RSH=rsh; cvs" 

Table 14-14 shows the files used by the CVS command-line client for server connection and client configuration information. These files reside in the user's home directory.

Table 14-14. Client Configuration Files

Option

Description

~/.cvsignore

Filename patterns of files to ignore

~/.cvspass

Passwords cached by cvs login

~/.cvsrc

Default command options

~/.cvswrappers

User-specific checkout and commit filters

The ~/.cvspass file is really an operational file, not a configuration file. It is used by the cvs client program to store the repository user account password between cvs login and cvs logoff.

Some common .cvsrc settings are:

update -dP

Brings in new directories and prunes empty directories on cvs update.

diff -c

Give output in context diff format.

14.4.3. Creating a Sandbox

In order to use CVS, you must create a sandbox or have one created for you. This section describes sandbox creation, assuming there is already a module in the repository you want to work with. See Section 14.4.7.11, "import" for information on importing a new module into the repository.

  1. Determine the repository locator. Talk to the repository administrator if you need help finding the repository or getting the locator syntax right.

  2. If this will be the main repository you use, set $CVSROOT; otherwise, use the -d option when running CVS commands that don't infer the repository from the sandbox files.

  3. Pick a module to check out.

  4. Pick a sandbox location, and cd to the parent directory.

  5. If the repository requires login, do cvs login.

  6. Run cvs checkout module.

For example:

export CVSROOT=/usr/local/cvsroot
cd ~/work
cvs checkout hello

14.4.4. Sandbox Structure

This section describes the files and directories that may be encountered in sandboxes.

14.4.4.1. .cvsignore files

Sandboxes may contain .cvsignore files. These files specify filename patterns for files that may exist in the sandbox but which normally won't be checked into CVS. This is commonly used to cause CVS to bypass derived files.

14.4.4.2. .cvswrappers files

Sandboxes may contain .cvswrappers files, which provide directory-specific file handling information like that in the repository configuration file cvswrappers (see Section 14.3.3.6, "The cvswrappers file", earlier in this chapter).

14.4.4.3. CVS directories

Each directory in a sandbox contains a CVS directory. The files in this directory (see Table 14-15) contain metadata used by CVS to locate the repository and track which file versions have been copied into the sandbox.

Table 14-15. Files in the CVS Directories

File

Description

Base

Baserev

Baserev.tmp

The Base directory stores copies of files when the edit command is in use. The Baserev file contains the revision numbers of the files in Base. The Baserev.tmp file is used in updating the Baserev file.

Checkin.prog

Update.prog

The programs specified in the modules file for options -i and -u, respectively (if any).

Entries

Version numbers and timestamps for the files as they were copied from the repository when checked out or updated.

Entries.Backup

Entries.Log

Entries.Static

These are temporary and intermediate files used by CVS.

Notify

Notify.tmp

These are temporary files used by CVS for dealing with notifications for commands like edit and unedit.

Repository

The name by which the directory is known in the repository.

Root

The repository locator in effect when the sandbox was created (via cvs checkout).

Tag

Information about sticky tags and dates for files in the directory.

Template

Used to store the contents of the rcsinfo administrative file from the repository for remote repositories.

Since each sandbox directory has one CVS/Root file, a sandbox directory corresponds to exactly one repository. You cannot check out some files from one repository and some from another into a single sandbox directory.

14.4.5. Client Global Options

Table 14-16 lists the global options that control the operation of the CVS client program.

Table 14-16. Client Global Options

Option

Description

-a

Authenticate (gserver only).

-d root

Locate the repository. Overrides the setting of $CVSROOT.

-e editor

Specify message editor. Overrides the settings of $CVSEDITOR and $EDITOR.

-f

Don't read ~/.cvsrc. Useful when you have .cvsrc settings that you want to forgo for a particular command.

-H [command]

--help [command]

Display help. If no command is specified, general CVS help, including a list of other help options, is displayed.

-l

Don't log command in history.

-n

Don't change any files. Useful when you want to know ahead of time which files will be affected by a particular command.

-q

Be quiet.

-Q

Be very quiet. Print messages only for serious problems.

-r

Make new working files read-only.

-s variable=value

Set the value of a user variable to a given value. User variables can be used in the contents of administrative files.

-t

Trace execution. Helpful in debugging remote repository connection problems and, in conjunction with -n, in determining the effect of an unfamiliar command.

-w

Make new working files read/write. Overrides $CVSREAD. Files are read/write unless $CVSREAD is set or -r is specified.

-x

Encrypt. (Introduced in Version 1.10.)

-z gzip_level

Set the compression level. Useful when using CVS in client/server mode across slow connections.

14.4.6. Common Client Options

Table 14-17 and Table 14-18 describe the options that are common to many CVS commands. Table 14-17 lists the common options with a description of their function, while Table 14-18 lists which options can be used with the user commands. In the sections that follow, details will be provided only for options that are not listed here and for those that do not function as described here.

Table 14-17. Common Options

Option

Description

-D date

Use the most recent revision no later than date.

-f

For commands that involve tags (via -r) or dates (via -D), include files not tagged with the specified tag or not present on the specified date. The most recent revision will be included.

-k kflag

Determine how keyword substitution will be performed. The space between -k and kflag is optional. See Table 14-19 for the list of keyword substitution modes.

-l

Do not recurse into subdirectories.

-n

Don't run module programs.

-R

Do recurse into subdirectories (the default).

-r rev

Use a particular revision number or symbolic tag.

Table 14-18 shows which common options are applicable to each user command.

Table 14-18. Client Common Option Applicability

User Command

-D

-f

-k

-l

-n

-R

-r

add

annotate

checkout

commit

diff

edit

editors

export

help

history

import

log

login

logout

rdiff

release

remove

rtag

status

tag

unedit

update

watch

watchers

14.4.6.1. Date formats

CVS can understand dates in a wide variety of formats, including:

ISO standard

The preferred format is YYYY-MM-DD HH:MM, which would read as 2000-05-17, or 2000-05-17 22:00. The technical details of the format are defined in the ISO 8601 standard.

Email standard

17 May 2000. The technical details of the format are defined in the RFC 822 and RFC 1123 standards.

Relative

10 days ago, 4 years ago.

Common

month/day/year. This form can cause confusion because not all cultures use the first two fields in this order (1/2/2000 would be ambiguous).

Other

Other formats are accepted, including YYYY/MM/DD and those omitting the year (which is assumed to be the current year).

14.4.6.2. Keyword substitutions

Table 14-19 describes the keyword substitution modes that can be selected with the -k option. CVS uses keyword substitutions to insert revision information into files when they are checked out or updated.

Table 14-19. Keyword Substitution Modes

Mode

Description

b

Binary mode. Treat the file the same as with mode o, but also avoid newline conversion.

k

Keyword-only mode. Flatten all keywords to just the keyword name. Use this mode if you want to compare two revisions of a file without seeing the keyword substitution differences.

kv

Keyword-value mode. The keyword and the corresponding value are substituted. This is the default mode.

kvl

Keyword-value-locker mode. This mode is the same as kv mode, except it always adds the lock holder's user ID if the revision is locked. The lock is obtained via the cvs admin -l command.

o

Old-contents mode. Use the keyword values as they appear in the repository rather than generate new values.

v

Value-only mode. Substitute the value of each keyword for the entire keyword field, omitting even the $ delimiters. This mode destroys the field in the process, so use it cautiously.

Keyword substitution fields are strings of the form $Keyword ...$. The valid keywords are:

Author

The user ID of the person who committed the revision.

Date

The date and time (in standard UTC format) the revision was committed.

Header

The full path of the repository RCS file, the revision number, the commit date, time, and user ID, the file's state, and the lock holder's user ID if the file is locked.

Id

A shorter form of Header, omitting the leading directory name(s) from the RCS file's path, leaving only the filename.

Name

The tag name used to retrieve the file, or empty if the no explicit tag was given when the file was retrieved.

Locker

The user ID of the user holding a lock on the file, or empty if the file is not locked.

Log

The RCS filename. In addition to keyword expansion in the keyword field, each commit adds additional lines in the file immediately following the line containing this keyword. The first such line contains the revision number, the commit date, time, and user ID. Subsequent lines are the contents of the commit log message. The result over time is a reverse-chronological list of log entries for the file. Each of the additional lines is preceded by the same characters that precede the keyword field on its line. This allows the log information to be formatted in a comment for most languages. For example:

#
# ch14_04.htm
#
# $Log: ch14_04.htm,v $
# Revision 1.3  2001/06/22 16:14:09  ellie
# replaced grave entity w/literal backtic
#
# Revision 1.2  2001/06/18 18:28:37  ellie
# regenerated after xslt fixes
#
# Revision 1.1  2000/06/09 18:07:51  ellie
# Fixed the last remaining bug in the system.
#

Be sure that you don't place any keyword fields in your log messages if you use this keyword, since they will get expanded if you do.

RCSfile

The name of the RCS file (without any leading directories).

Revision

The revision number of the file.

Source

The full path of the RCS file.

State

The file's state, as assigned by cvs admin -s (if you don't set the state explicitly, it will be Exp by default).

14.4.7. User Commands

The CVS client program provides the user commands defined in Table 14-20.

Table 14-20. User Commands

Command

Description

ad

add

new

Indicate that files/directories should be added to the repository.

ann

annotate

Display contents of the head revision of a file, annotated with the revision number, user, and date of the last change for each line.

checkout

co

get

Create a sandbox for a module.

ci

com

commit

Commit changes from the sandbox back to the repository.

di

dif

diff

View differences between file versions.

edit

Prepare to edit files. This is used for enhanced developer coordination.

editors

Display a list of users working on the files. This is used for enhanced developer coordination.

ex

exp

export

Retrieve a module, but don't make the result a sandbox.

help

Get help.

hi

his

history

Display the log information for files.

im

imp

import

Import new modules into the repository.

lgn

login

logon

Log in to (cache the password for) a remote CVS server.

lo

log

rlog

Show the activity log for the file(s).

logout

Log off from (flush the password for) a remote CVS server.

pa

patch

rdiff

Release diff. The output is the format of input to Larry Wall's patch command. Does not have to be run from within a sandbox.

re

rel

release

p Perform a logged delete on a sandbox.

remove

rm

delete

Remove a file or directory from the repository.

rt

rtag

rfreeze

Tag a particular revision.

st

stat

status

Show detailed status for files.

ta

tag

freeze

Attach a tag to files in the repository.

unedit

Abandon file modifications and make read-only again.

up

upd

update

Synchronize sandbox to repository.

watch

Manage the watch settings. This is used for enhanced developer coordination.

watchers

Display the list of users watching for changes to the files. This is used for enhanced developer coordination.

14.4.7.1. add

add
  [ -k kflag ]
  [ -m message ]
  file ...

Indicate that files/directories should be added to the repository. They are not actually added until they are committed via cvs commit. This command is also used to resurrect files that have been deleted with cvs remove.

The standard meaning of the common client option -k applies. There is only one additional option that can be used with the add command: -m message. This option is used to provide a description of the file (which appears in the output of the log command).

14.4.7.2. annotate

annotate
  [ [ -D date | -r rev ] -f ]
  [ -l | -R ]
  file ...

CVS prints a report showing each line of the specified file. Each line is prefixed by information about the most recent change to the line, including the revision number, the user, and the date. If no revision is specified, then the head of the trunk is used.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply.

14.4.7.3. checkout

checkout
  [ -A ]
  [ -c | -s ]
  [ -d dir [ -N ] ]
  [ [ -D date | -r rev ] -f ]
  [ -j rev1 [ -j rev2 ] ]
  [ -k kflag ]
  [ -l | -R ]
  [ -n ]
  [ -p ]
  [ -P ]
  module ...

Copy files from the repository to the sandbox.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are listed in Table 14-21.

Table 14-21. Checkout Options

Option

Description

-A

Reset any sticky tags or dates.

-c

Copy the module file to standard output.

-d dir

Override the default directory name.

-j rev

Join branches together.

-N

Don't shorten module paths.

-p

Pipe the files to standard output, with header lines between them showing the filename, RCS filename, and version.

-P

Prune empty directories.

-s

Show status for each module from the modules file.

14.4.7.4. commit

commit
  [ -f | [ -l | -R ] ]
  [ -F file | -m message ]
  [ -n ]
  [ -r revision ]
  [ files ... ]

Commit the changes made to files in the sandbox to the repository.

The standard meanings of the common client options -l, -n, -r, and -R apply. Additional options are listed in Table 14-22.

Table 14-22. commit Options

Option Description

-f

Force commit, even if no changes were made.

-F file

Use the contents of the file as the message.

-m message

Use the message specified.

Use of the -r option causes the revision to be sticky, requiring the use of admin -A to continue to use the sandbox.

14.4.7.5. diff

diff
  [ -k kflag ]
  [ -l | -R ]
  [ format ]
  [ [ -r rev1 | -D date1 ] [ -r rev2 | -D date2 ] ]
  [ file ... ]

The diff command compares two versions of a file and displays the differences in a format determined by the options. By default, the sandbox version of the file will be compared to the repository version it was originally copied from.

The standard meanings of the common client options -D, -k, -l, -r, and -R apply. All options for the diff command in Chapter 3, "Linux Commands" can also be used.

14.4.7.6. edit

edit
  [ -a action ]
  [ -l | -R ]
  [ file ... ]

The edit command is used in conjunction with watch to permit a more coordinated (serialized) development process. It makes the file writable and sends out an advisory to any users who have requested them. A temporary watch is established and will be removed automatically when either the unedit or the commit command is issued.

The standard meanings of the common client options -l and -R apply. There is only one additional option that can be used with the edit command: -a actions. This option is used to specify the actions to watch. The legal values for actions are described in the entry for the watch command.

14.4.7.7. editors

editors
  [ -l | -R ]
  [ file ... ]

Display a list of users working on the files specified. This is determined by checking which users have run the edit command on those files. If the edit command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also the later section on watch.

14.4.7.8. export

export
  [ -d dir [ -N ] ]
  [ -D date | -r rev ]
  [ -f ]
  [ -k kflag ]
  [ -l | -R ]
  [ -n ]
  [ -P ]
  module ...

Export files from the repository, much like the checkout command, except that the result is not a sandbox (i.e., CVS subdirectories are not created). This can be used to prepare a directory for distribution. For example:

user@localhost$ cvs export -r foo-1_0 -d foo-1.0 foo
user@localhost$ tar czf foo-1.0.tar.gz foo-1.0

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are listed in Table 14-23.

Table 14-23. export Options

Option

Description

-d dir

Use dir as the directory name instead of using the module name.

-n

Don't run any checkout programs.

-N

Don't shorten paths.

When checking out a single file located one or more directories down in a module's directory structure, the -N option can be used with -d to prevent the creation of intermediate directories.

14.4.7.9. help

help

Display helpful information about using the cvs program.

14.4.7.10. history

history
  [ -a | -u user ]
  [ -b string ]
  [ -c ]
  [ -D date ]
  [ -e | -x type ]
  [ -f file | -m module | -n module | -p repository ]... 
  [ -l ]
  [ -o ]
  [ -r rev ]
  [ -t tag ]
  [ -T ]
  [ -w ]
  [ -z zone ]
  [ file ... ]

Display historical information. To use the history command, you must first set up the history file in the repository. See Section 14.3.3, "Repository Structure" for more information on this file.

NOTE

When used with the history command, the functions of -f, -l, -n, and -p are not the same as elsewhere in CVS.

The standard meanings of the common client options -D, and -r apply. History is reported for activity subsequent to the date or revision indicated. Additional options are listed in Table 14-24.

Table 14-24. history Options

Option

Description

-a

Show history for all users (default is current user).

-b str

Show history back to the first record containing str in the module name, filename, or repository path.

-c

Report each commit.

-e

Report everything.

-f file

Show the most recent event for file.

-l

Show last event only.

-m module

Produce a full report on module.

-n module

Report the last event for module.

-o

Report on modules that have been checked out.

-p repository

Show history for a particular repository directory.

-t tag

Show history since the tag tag was last added to the history file.

-T

Report on all tags.

-u name

Show history for a particular user.

-w

Show history only for the current working directory.

-w zone

Display times according to the time zone zone.

-x type

Report on specific types of activity. See Table 14-25.

The -p option should limit the history report to entries for the directory or directories (if multiple -p options are specified) given, but as of Version 1.10.8, it doesn't seem to affect the output. For example, to report history for the CVSROOT and hello modules, run the command:

cvs history -p CVSROOT -p hello

Using -t is faster than using -r because it only needs to search through the history file, not all of the RCS files.

The record types shown in Table 14-25 are generated by update commands.

Table 14-25. Update-Related history Record Types

Type

Description

C

Merge was necessary, but conflicts requiring manual intervention occurred.

G

Successful automatic merge.

U

Working file copied from repository.

W

Working copy deleted.

The record types shown in Table 14-26 are generated by commit commands:

Table 14-26. Commit-Related history Record Types

Type

Description

A

Added for the first time

M

Modified

R

Removed

Each of the record types shown in Table 14-27 is generated by a different command.

Table 14-27. Other history Record Types

Type

Command

E

export

F

release

O

checkout

T

rtag

14.4.7.11. import

import
  [ -b branch ]
  [ -d ]
  [ -I pattern ]
  [ -k kflag ]
  [ -m message ]
  [ -W spec ]
  module
  vendor_tag
  release_tag ...

Import an entire directory into the repository as a new module. Used to incorporate code from outside sources or other code that was initially created outside the control of the CVS repository. More than one release_tag may be specified, in which case multiple symbolic tags will be created for the initial revision.

The standard meaning of the common client option -k applies. Additional options are listed in Table 14-28.

Table 14-28. import Options

Option

Description

-b branch

Import to a vendor branch.

-d

Use the modification date and time of the file instead of the current date and time as the import date and time. For local repository locators only.

-I pattern

Filename patterns for files to ignore.

-m message

Use message as the log message instead of invoking the editor.

-W spec

Wrapper specification.

The -k setting will apply only to those files imported during this execution of the command. The keyword substitution modes of files already in the repository are not modified.

When used with -W, the spec variable is in the same format as entries in the cvswrappers administrative file (see Section 14.3.3.6, "The cvswrappers file").

Table 14-29 describes the status codes displayed by the import command.

Table 14-29. import Status Codes

Status

Description

C

Changed. The file is in the repository, and the sandbox version is different; a merge is required.

I

Ignored. The .cvsignore file is causing CVS to ignore the file.

L

Link. Symbolic links are ignored by CVS.

N

New. The file is new. It has been added to the repository.

U

Update. The file is in the repository, and the sandbox version is not different.

14.4.7.12. log

log
  [ -b ]
  [ -d dates ]
  [ -h ]
  [ -N ]
  [ -rrevisions ]
  [ -R ]
  [ -s state ]
  [ -t ]
  [ -wlogins ]
  [ file ... ]

Print an activity log for the files.

The standard meaning of the common client option -l applies. Additional options are listed in Table 14-30.

Table 14-30. log Options

Option

Description

-b

List revisions on default branch.

-d dates

Report on these dates.

-h

Print header only.

-N

Don't print tags.

-r[revisions]

Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.

-R

Print RCS filename only. The usage of -R here is different than elsewhere in CVS (-R usually causes CVS to operate recursively).

-s state

Print only those revisions having the specified state.

-t

Print only header and descriptive text.

-wlogins

Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 14-31. Multiple specifications separated by semicolons may be provided.

Table 14-31. log Date Range Specifications

Specification

Description

d1<d2, or d2>d1

The revisions dated between d1 and d2, exclusive

d1<=d2, or d2>=d1

The revisions dated between d1 and d2, inclusive

<d, or d>

The revisions dated before d

<=d, or d>=

The revisions dated on or before d

d<, or >d

The revisions dated after d

d<=, or >=d

The revisions dated on or after d

d

The most recent revision dated d or earlier

For -r, use the revision specifications in Table 14-32.

Table 14-32. log Revision Specifications

Specification

Description

rev1: rev2

The revisions between rev1 and rev2, inclusive.

:rev

The revisions from the beginning of the branch to rev, inclusive.

rev:

The revisions from rev to the end of the branch, inclusive.

branch

All revisions on the branch.

branch1: branch2

All revisions on all branches between branch1 and branch2 inclusive.

branch.

The latest revision on the branch.

For rev1:rev2, it is an error if the revisions are not on the same branch.

14.4.7.13. login

login

This command is used to log in to remote repositories. The password entered will be cached in the ~/.cvspass file, since a connection to the server is not maintained across invocations.

14.4.7.14. logout

logout

This command logs out of a remote repository. The password cached in the ~/.cvspass file will be deleted.

14.4.7.15. rdiff

rdiff
  [ -c | -s | -u ]
  [ { { -D date1 | -r rev1 } [ -D date2 | -r rev2 ] } | -t ]
  [ -f ]
  [ -l | -R ]
  [-V vn]
  file ...

The rdiff command creates a patch file that can be used to convert a directory containing one release into a different release.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-33.

Table 14-33. rdiff Options

Option

Description

-c

Use context diff format (the default).

-s

Output a summary of changed files instead of a patch file.

-t

Show the differences between the two most recent revisions.

-u

Use unidiff format.

-V rcsver

Obsolete. Used to specify version of RCS to emulate for keyword expansion. (Keyword expansion emulates RCS Version 5.)

14.4.7.16. release

release
  [ -d ]
  directory ...

Sandboxes can be abandoned or deleted without using cvs release if desired; using the release command will log an entry to the history file (if this mechanism is configured) about the sandbox being destroyed. In addition, it will check the disposition (recursively) of each of the sandbox files before deleting anything. This can help prevent destroying work that has not yet been committed.

There is only one option that can be used with the release command, -d. The -d option will delete the sandbox copy if no uncommitted changes are present.

NOTE

New directories (including any files in them) in the sandbox will be deleted if the -d option is used with release.

The status codes listed in Table 14-34 are used to describe the disposition of each file encountered in the repository and the sandbox.

Table 14-34. release Status Codes.

Status

Description

A

The sandbox file has been added (the file was created and cvs add was run), but the addition has not been committed.

M

The sandbox copy of the file has been modified.

P

U

Update available. There is a newer version of the file in the repository, and the copy in the sandbox has not been modified.

R

The sandbox copy was removed (the file was deleted and cvs remove was run), but the removal was not committed.

?

The file is present in the sandbox but not in the repository.

14.4.7.17. remove

remove
  [ -f ]
  [ -l | -R ]
  [ file ... ]

Indicate that files should be removed from the repository. The files will not actually be removed until they are committed. Use cvs add to resurrect files that have been removed if you change your mind later.

The standard meanings of the common client options -l and -R apply. Only one other option may be used with the remove command, -f. When used, -f will delete the file from the sandbox first.

14.4.7.18. rtag

rtag
  [ -a ]
  [ -b ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -F ]
  [ -l | - R ]
  [ -n ]
  tag
  file ...

Assign a tag to a particular revision of a set of files. If the file already uses the tag for a different revision, cvs rtag will complain unless the -F option is used. This command does not refer to the sandbox file revisions (use cvs tag for that), so it can be run outside of a sandbox, if desired.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-35.

Table 14-35. rtag Options

Option

Description

-a

Search the Attic for removed files containing the tag.

-b

Make it a branch tag.

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

-n

Don't run any tag program from the modules file.

14.4.7.19. status

status
  [ -l | -R ]
  [ -v ]
  [ file ... ]

Display the status of the files.

The standard meanings of the common client options -l and -R apply. The other option that can be used with the status command, -v, may be used to include tag information.

14.4.7.20. tag

tag
  [ -b ]
  [ -c ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -F ]
  [ -l | R ]
  tag
  [ file ... ]

Assign a tag to the sandbox revisions of a set of files. You can use the status -v command to list the existing tags for a file.

The tag must start with a letter and must consist entirely of letters, numbers, dashes (-) and underscores (_). Therefore, while you might want to tag your hello project with 1.0 when you release Version 1.0, you'll need to tag it with something like hello-1_0 instead.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-36.

Table 14-36. tag Options

Option

Description

-b

Make a branch.

-c

Check for changes. Make sure the files are not locally modified before tagging.

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

Since the -d option throws away information that might be important, it is recommended that you use it only when absolutely necessary. It is usually better to create a different tag with a similar name.

14.4.7.21. unedit

unedit
  [ -l | -R ]
  [ file ... ]

Abandon file modifications and make the file read-only again. Watchers will be notified.

The standard meanings of the common client options -l and -R apply.

14.4.7.22. update

update
  [ -A ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -I pattern ]
  [ -j rev1 [ -j rev2 ] ]
  [ -k kflag ]
  [ -l | -R ]
  [ -p ]
  [ -P ]
  [ -W spec ]
  [ file ... ]

Update the sandbox, merging in any changes from the repository. For example:

cvs -n -q update -AdP

can be used to do a quick status check of the current sandbox versus the head of the trunk of development.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are listed in Table 14-37.

Table 14-37. update Options

Option

Description

-A

Reset sticky tags.

-d

Create and update new directories.

-I pattern

Provide filename patterns for files to ignore.

-j revision

Merge in changes between two revisions. Mnemonic: join.

-p

Check out files to standard output.

-P

Prune empty directories.

-W spec

Provide wrapper specification.

Using -D or -r results in sticky dates or tags, respectively, on the affected files (using -p along with these prevents stickiness). Use -A to reset any sticky tags or dates.

If two -j specifications are made, the differences between them are computed and applied to the current file. If only one is given, then the common ancestor of the sandbox revision and the specified revision is used as a basis for computing differences to be merged.

For example, suppose a project has an experimental branch, and important changes to the file foo.c were introduced between revisions 1.2.2.1 and 1.2.2.2. Once those changes have proven stable, you want them reflected in the main line of development. From a sandbox with the head revisions checked out, we run:

user@localhost$ cvs update -j 1.2.2.1 -j 1.2.2.2 foo.c

CVS finds the differences between the two revisions and applies those differences to the file in our sandbox.

The spec used with -W is in the same format as entries in the cvswrappers administrative file (see Section 14.3.3.6, "The cvswrappers file").

The status codes listed in Table 14-38 are used to describe the action taken on each file encountered in the repository and the sandbox.

Table 14-38. update Status Codes

Status Code

Description

A

Added. Server took no action because there was no repository file. Indicates that cvs add, but not cvs commit, has been run.

C

Conflict. Sandbox copy is modified (it has been edited since it was checked out or last committed). There was a new revision in the repository, and there were conflicts when CVS merged its changes into the sandbox version.

M

Modified. Sandbox copy is modified (it has been edited since it was checked out or last committed). If there was a new revision in the repository, its changes were successfully merged into the file (no conflicts).

P

Patched. Same as U but indicates the server used a patch.

R

Removed. Server took no action. Indicates that cvs remove, but not cvs commit, has been run.

U

Updated. The file was brought up-to-date.

?

File is present in sandbox but not in repository.

14.4.7.23. watch

watch
  { { on | off } | { add | remove } [ -a action ] }
  [ -l | -R ]
  file ...

The watch command controls CVS's edit-tracking mechanism. By default, CVS operates in its concurrent development mode, allowing any user to edit any file at any time. CVS includes this watch mechanism to support developers who would rather be notified of edits made by others proactively than discover them when doing an update.

The CVSROOT/notify file determines how notifications are performed.

Table 14-39 shows the watch sub-commands and their uses.

Table 14-39. watch Sub-commands

Sub-command

Description

add

Start watching files.

off

Turn off watching.

on

Turn on watching.

remove

Stop watching files.

The standard meanings of the common client options -l and -R apply. The only other option that can be used with the watch command is -a action. The -a option is used in conjunction with one of the actions listed in Table 14-40.

Table 14-40. watch Actions

Action

Description

all

All of the following.

commit

A user has committed changes.

edit

A user ran cvs edit.

none

Don't watch. Used by the edit command.

unedit

A user ran cvs unedit, cvs release, or deleted the file and ran cvs update, re-creating it.

See also the descriptions of the edit, editors, unedit, and watchers commands.

14.4.7.24. watchers

watchers
  [ -l | -R ]
  [ file ... ]

Display a list of users watching the specified files. This is determined by checking which users have run the watch command on a particular file (or set of files). If the watch command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.