Knowledge base CVS Concurrent Versions System
Manual
Creating a repository
- Taken from Section 2.6 of CVS Manual
- To create a repository, run the
cvs init
command. It will set up an empty repository in the cvs root ( <CVS root Directory> ) specified in the usual way.
-
cvs -d <CVS root Directory> init
- NOTE:
-
cvs init
is careful to never overwrite any existing files in the repository, so no harm is done if you run cvs init on an already set-up repository.
-
cvs init
will enable history logging; if you dont want that, remove the history file after running cvs init
Telling CVS where your repository is
There are several ways to tell cvs where to find the repository. You can name the repository
on the command line explicitly, with the -d (for "directory") option:
cvs -d <CVS root Directory> checkout yoyodyne/tc
Or you can set the $CVSROOT
environment variable to an absolute path to the root of the
repository, <CVS root Directory>
in this example. To set $CVSROOT
, csh and tcsh users
should have this line in their .cshrc
or .tcshrc
files:
setenv CVSROOT <CVS root Directory>
sh and bash users should instead have these lines in their .profile
or .bashrc
:
CVSROOT= <CVS root Directory>
export CVSROOT
A repository specified with -d
will override the $CVSROOT
environment variable. Once
youve checked a working copy out from the repository, it will remember where its repository
is (the information is recorded in the CVS/Root
file in the working copy).
The -d
option and the CVS/Root
file both override the $CVSROOT
environment variable.
If -d
option differs from CVS/Root
, the former is used. Of course, for proper operation
they should be two ways of referring to the same repository.
Creating a directory tree from a number of files
When you begin using cvs, you will probably already have several projects that can be
put under cvs control. In these cases the easiest way is to use the import command.
An example is probably the easiest way to explain how to use it. If the files you want
to install in cvs reside in wdir
, and you want them to appear in the repository as
$CVSROOT/yoyodyne/rdir
, you can do this:
$ cd wdir
$ cvs import -m "Imported sources" yoyodyne/rdir yoyo start
Unless you supply a log message with the -m
flag, cvs starts an editor and prompts for
a message. The string yoyo
is a vendor tag, and start
is a release tag. They may fill no
purpose in this context, but since cvs requires them they must be present.
You can now verify that it worked, and remove your original source directory.
$ cd ..
$ cvs checkout yoyodyne/rdir # Explanation below
$ diff -r wdir yoyodyne/rdir
$ rm -r wdir
Erasing the original sources is a good idea, to make sure that you do not accidentally edit
them in wdir, bypassing cvs. Of course, it would be wise to make sure that you have a
backup of the sources before you remove them.
The checkout command can either take a module name as argument (as it has done in
all previous examples) or a path name relative to $CVSROOT
, as it did in the example above.
It is a good idea to check that the permissions cvs sets on the directories inside $CVSROOT
are reasonable, and that they belong to the proper groups.
Ignoring files via cvsignore
There are certain file names that frequently occur inside your working copy, but that you dont want to put under cvs control. Examples are all the object files that you get while you compile your sources. Normally, when you run cvs update
, it prints a line for each file it encounters that it doesnt know about (see Section A.19.2 [update output], page 124).
cvs has a list of files (or sh(1) file name patterns) that it should ignore while running update, import and release. This list is constructed in the following way.
- The list is initialized to include certain file name patterns: names associated with cvs administration, or with other common source control systems; common names for patch files, object files, archive files, and editor backup files; and other names that are usually artifacts of assorted utilities. Currently, the default list of ignored file name patterns is:
RCS SCCS CVS CVS.adm
RCSLOG cvslog.*
tags TAGS
.make.state .nse_depinfo
*~ #* .#* ,* _$* *$
*.old *.bak *.BAK *.orig *.rej .del-*
*.a *.olb *.o *.obj *.so *.exe
*.Z *.elc *.ln
core
- The per-repository list in
$CVSROOT/CVSROOT/cvsignore
is appended to the list, if that file exists.
- The per-user list in
.cvsignore
in your home directory is appended to the list, if it exists.
- Any entries in the environment variable
$CVSIGNORE
is appended to the list.
- Any
-I
options given to cvs is appended.
- As cvs traverses through your directories, the contents of any
.cvsignore
will be appended to the list. The patterns found in .cvsignore
are only valid for the directory that contains them, not for any sub-directories.
In any of the 5 places listed above, a single exclamation mark (!
) clears the ignore list. This can be used if you want to store any file which normally is ignored by cvs.
Specifying -I !
to cvs import will import everything, which is generally what you want
to do if you are importing files from a pristine distribution or any other source which is
known to not contain any extraneous files. However, looking at the rules above you will see
there is a fly in the ointment; if the distribution contains any .cvsignore
files, then the
patterns from those files will be processed even if -I !
is specified. The only workaround
is to remove the .cvsignore
files in order to do the import. Because this is awkward, in
the future -I !
might be modified to override .cvsignore
files in each directory.
Note that the syntax of the ignore files consists of a series of lines, each of which contains a
space separated list of filenames. This offers no clean way to specify filenames which contain
spaces, but you can use a workaround like foo?bar
to match a file named foo bar
(it
also matches fooxbar
and the like). Also note that there is currently no way to specify
comments.
Modules
The administrative files
The directory $CVSROOT/CVSROOT
contains some administrative files. [...]
The most important of these files is the modules
file. It defines all modules in the
repository. This is a sample modules
file.
CVSROOT CVSROOT
modules CVSROOT modules
cvs gnu/cvs
rcs gnu/rcs
diff gnu/diff
tc yoyodyne/tc
The modules
file is line oriented. In its simplest form each line contains the name of
the module, whitespace, and the directory where the module resides. The directory is a
path relative to $CVSROOT
. The last four lines in the example above are examples of such
lines.
The line that defines the module called modules
uses features that are not explained
here. See [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]], for a full explanation of all the available features.
NOTE: Editing administrative files
You edit the administrative files in the same way that you would edit any other module.
Use cvs checkout CVSROOT
to get a working copy, edit it, and commit your changes in
the normal way.
It is possible to commit an erroneous administrative file. You can often fix the error
and check in a new revision, but sometimes a particularly bad error in the administrative
file makes it impossible to commit new revisions. If and when this happens, you can
correct the problem by temporarily copying a corrected administrative file directly into
the $CVSROOT/CVSROOT
repository directory, then committing the same correction via a
checkout of the CVSROOT
module. It is important that the correction also be made via
the checked out copy, or the next checkout and commit to the CVSROOT
module will overwrite the correction that was copied directly into the repository, possibly
breaking things in such a way as to prevent commits again.
The module file
- Taken from [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]]
The modules
file records your definitions of names for collections of source code. cvs will
use these definitions if you use cvs to update the modules file (use normal commands like
add, commit, etc).
The modules
file may contain blank lines and comments (lines beginning with #
) as
well as module definitions. Long lines can be continued on the next line by specifying a
backslash (\
) as the last character on the line.
There are three basic types of modules: alias modules, regular modules, and ampersand
modules. The difference between them is the way that they map files in the repository
to files in the working directory. In all of the following examples, the top-level repository
contains a directory called first-dir
, which contains two files, file1
and file2
, and
a directory sdir
. first-dir/sdir
contains a file sfile
.
Alias modules
Alias modules are the simplest kind of module:
mname -a aliases...
This represents the simplest way of defining a module mname. The -a
flags
the definition as a simple alias: cvs will treat any use of mname (as a command
argument) as if the list of names aliases had been specified instead. aliases may
contain either other module names or paths. When you use paths in aliases,
checkout creates all intermediate directories in the working directory, just as
if the path had been specified explicitly in the cvs arguments.
For example, if the modules file contains:
amodule -a first-dir
then the following two commands are equivalent:
$ cvs co amodule
$ cvs co first-dir
and they each would provide output such as:
cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile
Regular modules
mname [ options ] dir [ files... ]
In the simplest case, this form of module definition reduces to mname dir
.
This defines all the files in directory dir as module mname. dir is a relative
path (from $CVSROOT) to a directory of source in the source repository. In
this case, on checkout, a single directory called mname is created as a working
directory; no intermediate directory levels are used by default, even if dir was
a path involving several directory levels.
For example, if a module is defined by:
regmodule first-dir
then regmodule will contain the files from first-dir:
$ cvs co regmodule
cvs checkout: Updating regmodule
U regmodule/file1
U regmodule/file2
cvs checkout: Updating regmodule/sdir
U regmodule/sdir/sfile
By explicitly specifying files in the module definition after dir, you can select particular
files from directory dir. Here is an example:
regfiles first-dir/sdir sfile
With this definition, getting the regfiles module will create a single working directory
regfiles
containing the file listed, which comes from a directory deeper in the cvs source
repository:
$ cvs co regfiles
U regfiles/sfile
Ampersand modules
A module definition can refer to other modules by including &module
in its definition.
mname [ options ] &module...
Then getting the module creates a subdirectory for each such module, in the directory
containing the module. For example, if modules contains
ampermod &first-dir
then a checkout will create an ampermod directory which contains a directory called firstdir,
which in turns contains all the directories and files which live there. For example, the command
$ cvs co ampermod
will create the following files:
ampermod/first-dir/file1
ampermod/first-dir/file2
ampermod/first-dir/sdir/sfile
There is one quirk/bug: the messages that cvs prints omit the ampermod
, and thus do
not correctly display the location to which it is checking out the files:
$ cvs co ampermod
cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile
Do not rely on this buggy behavior; it may get fixed in a future release of cvs.
Excluding directories
An alias module may exclude particular directories from other modules by using an exclamation
mark (!
) before the name of each directory to be excluded.
For example, if the modules file contains:
exmodule -a !first-dir/sdir first-dir
then checking out the module exmodule
will check out everything in first-dir
except
any files in the subdirectory first-dir/sdir
.
Troubleshooting
For troubleshooting have a look at the
Appendix F Troubleshooting of the manual.
--
PeterZumbruch - 16 Jun 2008