source files. It stores the files by using stroing the delta’s from the original file to the current version, the composite of the origianl file and these delta’s is the current version of the file.

CVS is not a build, management sytem, it does not control or influence how you structure your make files or any of the layout of your projects within the code storage. IT does allow multiple users to work on multiple files and even the same file and then merges the changes from each developmer in to the database. This is not without problems since CVS can not tell you wether or not your changes are compatible with the changes from a coworker.

set CVSROOT = /usr/proj3/case/95s523/95sbde/base/Master,

willset the line that will point to the CVS repository. You could also specify the path on the cvs command line by specifying

CVS allows you to isolate changes onto a separate l ine of development, known as a branch. When you change files on a branch, those changes do not appear on the main trunk or other branches.

Later you can move changes from one branch to another branch (or the main trunk) by merging. Merging involves first running cvs update -j, to merge the changes into the working directory. You can then commit that revision, and thus effectively copy the changes onto another branch.

Suppose that release 1.0 of BDE has been made. You are continuing to develop BDE, planning to create release 1.1 in a couple of months. After a while your customers start to complain about a fatal bug. You check out release 1.0 and find the bug (which turns out to have a trivial fix). However, the current revision of the sources are in a state of flux and are not expected to be stable for at least another month. There is no way to make a bugfix release based on the newest sources.

The thing to do in a situation like this is to create a branch on the revision trees for all the files that make up release 1.0 of BDE. You can then make modifications to the branch without disturbing the main trunk. When the modifications are finished you can elect to either incorporate them on the main trunk, or leave them on the branch.

This splits off a branch based on the current revisions in the working copy, assigning that branch the name `rel-1-0-patches'.

It is important to understand that branches get created in the repository, not in the working copy. Creating a branch based on current revisions, as the above example does, will not automatically switch the working copy to be on the new branch.

You can also create a branch without reference to any working copy, by using rtag:

$ cvs rtag -b -r rel-1-0 rel-1-0-patches BDE`-r rel-1-0'

says that this branch should be rooted at the revision that corresponds to the tag `rel-1-0'. It need not be the most recent revision -- it's often useful to split a branch off an old revision (for example, when fixing a bug in a past release otherwise known to be stable).

As with `tag', the `-b' flag tells rtag to create a branch (rather than just a symbolic revision name). Note that the numeric revision number that matches `rel-1-0' will probably be different from file to file.

So, the full effect of the command is to create a new branch -- named `rel-1-0-patches' -- in module `tc', rooted in the revision tree at the point tagged by `rel-1-0'.

You can retrieve a branch in one of two ways: by checking it out fresh from the repository, or by switching an existing working copy over to the branch.

To check out a branch from the repository, invoke `checkout' with the `-r' flag, followed by the tag name of the branch

$ cvs checkout -r rel-1-0-patches BDE

Or, if you already have a working copy, you can switch it to a given branch with `update -r':

$ cvs update -r rel-1-0-patches BDE

or equivalently:

$ cd BDE

$ cvs update -r rel-1-0-patches

It does not matter if the working copy was originally on the main trunk or on some other branch -- the above command will switch it to the named branch. And similarly to a regular `update' command, `update -r' merges any changes you have made, notifying you of conflicts where they occur.

Once you have a working copy tied to a particular branch, it remains there until you tell it otherwise. This means that changes checked in from the working copy will add new revisions on that branch, while leaving the main trunk and other branches unaffected.

To find out what branch a working copy is on, you can use the `status' command. In its output, look for the field named `Sticky tag' that's CVS's way of telling you the branch, if any, of the current working files:

Ordinarily, a file's revision history is a linear series of increments:

+-----+ +-----+ +-----+ +-----+ +-----+

! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !

+-----+ +-----+ +-----+ +-----+ +-----+

However, CVS is not limited to linear development. The revision tree can be split into branches, where each branch is a self-maintained line of development. Changes made on one branch can easily be moved back to the main trunk.

Each branch has a branch number, consisting of an odd number of period-separated decimal integers. The branch number is created by appending an integer to the revision number where the corresponding branch forked off. Having branch numbers allows more than one branch to be forked off from a certain revision.

All revisions on a branch have revision numbers formed by appending an ordinal number to the branch number. The following figure illustrates branching with an example.

+-------------+

Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !

/ +-------------+

/

/

+---------+ +---------+ +---------+

Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !

/ +---------+ +---------+ +---------+

/

/

+-----+ +-----+ +-----+ +-----+ +-----+

! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk

+-----+ +-----+ +-----+ +-----+ +-----+

!

!

! +---------+ +---------+ +---------+

Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !

+---------+ +---------+ +---------+

When CVS creates a branch number it picks the first unused even integer, starting with 2. So when you want to create a branch from revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a zero (such as 6.4.0) are used internally by CVS The branch 1.1.1 has a special meaning.

This section describes a CVS feature called magic branches. For most purposes, you need not worry about magic branches; CVS handles them for you. However, they are visible to you in certain circumstances, so it may be useful to have some idea of how it works.

Externally, branch numbers consist of an odd number of dot-separated decimal integers That is not the whole truth, however. For efficiency reasons CVS sometimes inserts an extra 0 in the second rightmost position (1.2.4 becomes 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so on).

CVS does a pretty good job at hiding these so called magic branches, but in a few places the hiding is incomplete:

The magic branch number appears in the output from cvs log.

You cannot specify a symbolic branch name to cvs admin.

You can use the admin command to reassign a symbolic name to a branch the way RCS expects it to be. If R4patches is assigned to the branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can do this:

cvs admin -NR4patches:1.4.2 numbers.c

It only works if at least one revision is already committed on the branch. Be very careful so that you do not assign the tag to the wrong number. (There is no way to see how the tag was assigned yesterday).

These standard options are supported by commit (see section Common command options, for a complete description of them):

-l Local; run only in current working directory.

-n Do not run any module program.

-R Commit directories recursively. This is on by default.

-r revision Commit to revision. revision must be either a branch, or a revision on the main trunk that is higher than any existing revision number. You cannot commit to a specific revision on a branch.

commit also supports these options:

-F file Read the log message from file, instead of invoking an editor.

-f Note that this is not the standard behavior of the -f

Force CVS to commit a new revision even if you haven't made any changes to the file. If the current revision of file is 1.7, then the following two commands are equivalent:

$ cvs commit -f file

$ cvs commit -r 1.8 file

The `-f' option disables recursion (i.e., it implies `-l'). To force CVS to commit a new revision for all files in all subdirectories, you must use `-f -R'.

-m message Use message as the log message, instead of invoking an editor.

You can commit to a branch revision (one that has an even number of dots) with the `-r' option. To create a branch revision, use the `-b' option of the rtag or tag commands. Then, either checkout or update can be used to base your sources on the newly created branch. From that point on, all commit changes made within these working sources will be automatically added to a branch revision, thereby not disturbing main-line development in any way. For example, if you had to create a patch to the 1.2 version of the product, even though the 2.0 version is already under development, you might do:

$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module

$ cvs checkout -r FCS1_2_Patch product_module

$ cd product_module

$ cvs commit

This works automatically since the `-r' option is sticky.

Synopsis: diff [-lR] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files...]

Requires: working directory, repository.

Changes: nothing.

The diff command is used to compare different revisions of files. The default action is to compare your working files with the revisions they were based on, and report any differences that are found.

If any file names are given, only those files are compared. If any directories are given, all files under them will be compared.

The exit status for diff is different than for other CVS commands.

-D date Use the most recent revision no later than date. See `-r' for how this affects the comparison.

-k kflag Process keywords according to kflag.

-l Local; run only in current working directory.

-R Examine directories recursively. This option is on by default.

-r tag Compare with revision tag. Zero, one or two `-r' options can be present. With no `-r' option, the working file will be compared with the revision it was based on. With one `-r', that revision will be compared to your current working file. With two `-r' options those two revisions will be compared (and your working file will not affect the outcome in any way).

One or both `-r' options can be replaced by a `-D date' option, described above.

The following options specify the format of the output. They have the same meaning as in GNU diff.

-0 -1 -2 -3 -4 -5 -6 -7 -8 -9

--binary

--brief

--changed-group-format=arg

-c

-C nlines

--context[=lines]

-e --ed

-t --expand-tabs

-f --forward-ed

--horizon-lines=arg

--ifdef=arg

-w --ignore-all-space

-B --ignore-blank-lines

-i --ignore-case

-I regexp

--ignore-matching-lines=regexp

-h

-b --ignore-space-change

-T --initial-tab

-L label

--label=label

--left-column

-d --minimal

-N --new-file

--new-line-format=arg

--old-line-format=arg

--paginate

-n --rcs

-s --report-identical-files

-p

--show-c-function

-y --side-by-side

-F regexp

--show-function-line=regexp

-H --speed-large-files

--suppress-common-lines

-a --text

--unchanged-group-format=arg

-u

-U nlines

--unified[=lines]

-V arg

-W columns

--width=columns

Synopsis: history [-report] [-flags] [-options args] [files...]

Requires: the file `$CVSROOT/CVSROOT/history'

Changes: nothing.

CVS can keep a history file that tracks each use of the checkout, commit, rtag, update, and release commands. You can use history to display this information in various formats.

Logging must be enabled by creating the file `$CVSROOT/CVSROOT/history'.

Warning: history uses `-f', `-l', `-n', and `-p' in ways that conflict with the normal use inside CVS

Several options (shown above as `-report') control what kind of report is generated:

-c Report on each time commit was used (i.e., each time the repository was modified).

-e Everything (all record types). Equivalent to specifying `-x' with all record types. Of course, `-e' will also include record types which are added in a future version of CVS; if you are writing a script which can only handle certain record types, you'll want to specify `-x'.

-m module Report on a particular module. (You can meaningfully use `-m' more than once on the command line.)

-o Report on checked-out modules.

-T Report on all tags.

-x type Extract a particular set of record types type from the CVS history. The types are indicated by single letters, which you may specify in combination.

Certain commands have a single record type:

F release

O checkout

E export

T rtag

One of four record types may result from an update:

C A merge was necessary but collisions were detected (requiring manual merging).

G A merge was necessary and it succeeded.

U A working file was copied from the repository.

W The working copy of a file was deleted during update (because it was gone from the repository).

One of three record types results from commit:

A A file was added for the first time.

M A file was modified.

R A file was removed.

The options shown as `-flags' constrain or expand the report without requiring option arguments:

-a Show data for all users (the default is to show data only for the user executing history).

-l Show last modification only.

-w Show only the records for modifications done from the same working directory where history

is executing.

The options shown as `-options args' constrain the report based on an argument:

-b str Show data back to a record containing the string str in either the module name, the file name, or the repository path.

-r rev Show records referring to revisions since the revision or tag named rev appears in individual RCS files. Each RCS file is searched for the revision or tag.

-t tag Show records since tag tag was last added to the history file. This differs from the `-r' flag above in that it reads only the history file, not the RCS files, and is much faster.

rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules...

Requires: repository.

Changes: repository.

Synonym: rfreeze

You can use this command to assign symbolic tags to particular, explicitly specified source revisions in the repository. rtag works directly on the repository contents (and requires no prior checkout). Use tag instead to base the selection of revisions on the contents of your working directory.

If you attempt to use a tag name that already exists, CVS will complain and not overwrite that tag. Use the `-F' option to force the new tag value.

These standard options are supported by rtag -D date

Tag the most recent revision no later than date.

-f Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, use the most recent revision (instead of ignoring the file).

-F Overwrite an existing tag of the same name on a different revision.

-l Local; run only in current working directory.

-n Do not run any tag program that was specified with the `-t' flag inside the `modules' file.

-R Tag directories recursively. This is on by default.

-r tag Only tag those files that contain tag. This can be used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the same files as the old tag.

In addition to the above common options, these options are available:

-a Use the `-a' option to have rtag look in the `Attic' for removed files that contain the specified tag. The tag is removed from these files, which makes it convenient to re-use a symbolic tag as development continues (and files get removed from the up-coming distribution).

-b Make the tag a branch tag

-d Delete the tag instead of creating it.

In general, tags (often the symbolic names of software distributions) should not be removed, but the `-d' option is available as a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, or if you mistagged a module).

tag [-lR] [-b] [-c] [-d] symbolic_tag [files...]

Requires: working directory, repository.

Changes: repository.

Synonym: freeze

Use this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied immediately to the repository, as with rtag, but the versions are supplied implicitly by the CVS records of your working files' history rather than applied explicitly.

One use for tags is to record a snapshot of the current sources when the software freeze date of a project arrives. As bugs are fixed after the freeze date, only those changed sources that are to be part of the release need be re-tagged.

The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The checkout and update commands allow you to extract an exact copy of a tagged release at any time in the future, regardless of whether files have been changed, added, or removed since the release was tagged.

This command can also be used to delete a symbolic tag, or to create a branch.

If you attempt to use a tag name that already exists, CVS will complain and not overwrite that tag. Use the `-F' option to force the new tag value.

These standard options are supported by tag

-F Overwrite an existing tag of the same name on a different revision.

-l Local; run only in current working directory.

-R Tag directories recursively. This is on by default.

Two special options are available:

-b Make the tag a branch tag allowing concurrent, isolated development. This is most useful for creating a patch to a previously released software distribution.

-c Check that all files which are to be tagged are unmodified. This can be used to make sure that you can reconstruct the current file contents.

-d Delete a tag.

If you use `cvs tag -d symbolic_tag', the symbolic tag you specify is deleted instead of being added. Warning: Be very certain of your ground before you delete a tag; doing this permanently discards some historical information, which may later turn out to be valuable.

To enable the watch features, you first specify that certain files are to be watched.

Command: cvs watch on [-lR] files ...

Specify that developers should run cvs edit before editing files. CVS will create working copies of files read-only, to remind developers to run the cvs edit command before working on them.

If files includes the name of a directory, CVS arranges to watch all files added to the corresponding repository directory, and sets a default for files added in the future; this allows the user to set notification policies on a per-directory basis. The contents of the directory are processed recursively, unless the -l option is given. The -R option can be used to force recursion if the -l option is set in `~/.cvsrc' If files is omitted, it defaults to the current directory.

You can tell CVS that you want to receive notifications about various actions taken on a file. You can do this without using cvs watch on for the file, but generally you will want to use cvs watch on, so that developers use the cvs edit command.

Command: cvs watch add [-a action] [-lR] files ...

Add the current user to the list of people to receive notification of work done on files.

The -a option specifies what kinds of events CVS should notify the user about. action is one of the following:

edit

Another user has applied the cvs edit command (described below) to a file.

unedit

Another user has applied the cvs unedit command (described below) or the cvs release command to a file, or has deleted the file and allowed cvs update to recreate it.

commit

Another user has committed changes to a file.

all

All of the above.

none

None of the above. (This is useful with cvs edit, described below.)

The -a option may appear more than once, or not at all. If omitted, the action defaults to all.

The files and options are processed as for the cvs watch commands.

Command: cvs watch remove [-a action] [-lR] files ...

Remove a notification request established using cvs watch add; the arguments are the same. If the -a option is present, only watches for the specified actions are removed.

This is a complete list of all environment variables that affect CVS.

$CVSIGNORE

A whitespace-separated list of file name patterns that CVS should ignore.

$CVSWRAPPERS

A whitespace-separated list of file name patterns that CVS should treat as wrappers.

$CVSREAD

If this is set, checkout and update will try hard to make the files in your working directory read-only. When this is not set, the default behavior is to permit modification of your working files.

$CVSUMASK

Controls permissions of files in the repository.

$CVSROOT

Should contain the full pathname to the root of the CVS source repository (where the RCS files are kept). This information must be available to CVS for most commands to execute; if $CVSROOT is not set, or if you wish to override it for one invocation, you can supply it on the command line: `cvs -d cvsroot cvs_command...' Once you have checked out a working directory, CVS stores the appropriate root (in the file `CVS/Root'), so normally you only need to worry about this when initially checking out a working directory.

$EDITOR

$CVSEDITOR

Specifies the program to use for recording log messages during commit. $CVSEDITOR overrides $EDITOR.

$PATH

If $RCSBIN is not set, and no path is compiled into CVS, it will use $PATH to try to find all programs it uses.

$HOME

$HOMEPATH

$HOMEDRIVE

Used to locate the directory where the `.cvsrc' file, and other such files, are searched. On Unix, CVS just checks for HOME. On Windows NT, the system will set HOMEDRIVE, for example to `d:' and HOMEPATH, for example to `\joe'. On Windows 95, you'll probably need to set HOMEDRIVE and HOMEPATH yourself.

$CVS_RSH

Specifies the external program which CVS connects with, when :ext: access method is specified.

$CVS_SERVER

Used in client-server mode when accessing a remote repository using RSH. It specifies the name of the program to start on the server side when accessing a remote repository using RSH. The default value is cvs.

$CVS_PASSFILE

Used in client-server mode when accessing the cvs login server. Default value is `$HOME/.cvspass'.

$CVS_CLIENT_PORT

Used in client-server mode when accessing the server via Kerberos.

$CVS_CLIENT_LOG

Used for debugging only in client-server mode. If set, everything send to the server is logged into `$CVS_CLIENT_LOG.in' and everything send from the server is logged into `$CVS_CLIENT_LOG.out'.

$CVS_SERVER_SLEEP

Used only for debugging the server side in client-server mode. If set, delays the start of the server child process the specified amount of seconds so that you can attach to it with a debugger.

$TMPDIR

$TMP

$TEMP

Directory in which temporary files are located. The CVS server uses TMPDIR. Some parts of CVS will always use `/tmp' (via the tmpnam function provided by the system).

On Windows NT, TMP is used (via the _tempnam function provided by the system).

The patch program which is used by the CVS client uses TMPDIR, and if it is not set, uses `/tmp' (at least with GNU patch 2.1). Note that if your server and client are both running CVS 1.9.10 or later, CVS will not invoke an external patch program.

This appendix describes how to invoke CVS, with references to where each command or feature is described in detail. For other references run the cvs --help command, or see section ..

A CVS command looks like:

cvs [ global_options ] command [ command_options ] [ command_args ]

Global options:

-a

Authenticate all communication (client only) (not in CVS 1.9 and older).

-b

Specify RCS location (CVS 1.9 and older).

-d root

Specify the CVSROOT.

-e editor

Edit messages with editor.

-f

Do not read the `~/.cvsrc' file.

-H

--help

Print a help message.

-l

Do not log in CVSROOT/history file.

-n

Do not change any files.

-Q

Be really quiet.

-q

Be somewhat quiet.

-r

Make new working files read-only.

-s variable=value

Set a user variable.

-T tempdir

Put temporary files in tempdir.

-t

Trace CVS execution.

-v

--version

Display version and copyright information for CVS.

-w

Make new working files read-write.

-x

Encrypt all communication (client only).

-z gzip-level

Set the compression level (client only).

Keyword expansion modes

-kkv $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $

-kkvl $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $

-kk $Id$

-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp

-ko no expansion

-kb no expansion, file is binary

Keywords

$Author: joe $

$Date: 1993/12/09 03:21:13 $

$Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $

$Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $

$Locker: harry $

$Name: snapshot_1_14 $

$RCSfile: file1,v $

$Revision: 1.1 $

$Source: /home/files/file1,v $

$State: Exp $

$Log: file1,v $

Revision 1.1 1993/12/09 03:30:17 joe

Initial revision

-l Local; run only in current working directory.

-R Operate recursively (default).

-W spec More wrappers.

-d Delete the given directory.

-f Delete the file before removing it.

-l Local; run only in current working directory.

-R Operate recursively (default).

-l Local; run only in current working directory.

-R Operate recursively (default).

-v Include tag information for file.

-R Operate recursively (default)..

-l Local; run only in current working directory..

-R Operate recursively (default)..