Basic CVS Tutorial
by David Martin (w/ additions by Sara McMains)
CREATING THE REPOSITORY
The first step is to create a source repository.
(1) Create a directory to serve as the repository.
(2) Set the environment variable CVSROOT to the name
of the repository directory.
(3) Execute "cvs init".
The final step installs some useful CVS bookkeeping stuff.
The environment variable CVSROOT must be set by all clients of the
repository.
(We've already done this. You should add the line
setenv CVSROOT /home/cadml/testdir/cvsroot
to your .cshrc file. Make sure that the EDIT environment variable is
set to your favorite editor because CVS will bring it up for you to
add comments every time you commit changes. E.g. add
setenv EDIT emacs
to your .cshrc file.)
ADDING TO THE REPOSITORY
There are two ways to add stuff to the repository. Adding a new
directory or a new file to an already checked out module is described
below. This section shows how to easily bootstrap an entire source
tree into the repository.
(1) cd into the root directory of the source tree
to be added.
(2) Execute "cvs import
".
The directory is a directory name relative to
CVSROOT. This directory CVSROOT/ is created,
and everything in PWD is added (recursively) to
CVSROOT/ under CVS control.
The gives a symbolic name to the new version of the entire
source tree. I don't know what is for, yet it must be
specified.... The man page says:
You must also specify at least one releasetag to iden-
tify the files at the leaves created each time you exe-
cute `cvs import'.
(eg cvs import cadml r1)
(We set the sticky bit on the CVSROOT directory, so that all the
directories checked in will be cadml group owned and writable. If you
import subdirectories, you may need to manually do a chgrp cadml to
them. Otherwise other group members may have problems with permissions
when they check in files.)
CHECKING OUT MODULES
A module is a collection of stuff in the repository. Each directory
in the repository is a module. Modules can be more complex, but that
is not important here.
If you want to work on a module that is in the repository:
(1) Go to some private directory where you want to
work.
(2) Execute "cvs checkout ". This will
create the directory in PWD and in it
place a checked-out copy of CVSROOT/.
(3) Change files at will. No special CVS commands
are needed for simple editing.
(If you want to check out a subdirectory, eg sif/include, & you
already have sif checked out into ~/projects, go to ~/projects and do
cvs checkout sif/include.)
CVS will give you a line for each file "", where status
if one of {U M C A R ?}. If you are checking out a module for the
first time, status should always be "U".
You can run "cvs checkout" on an already checked-out module to bring
it up-to-date. This is nearly identical to running "cvs update -d".
However, for basic CVS use, I recommend using "cvs checkout" to create
a local copy of a module, and "cvs update -d" (see below) to
subsequently bring it up-to-date with the repository.
ADDING AND DELETING FILES FROM A CHECKED-OUT MODULE
Once you have checked out a module, you may not only edit files,
but add and delete files as well. To add a file:
(1) Create the file in your checked-out module.
(2) Execute "cvs add ". There can be no "/"s in
, so you must be in the same directory.
To delete a file:
(1) Delete the file from your checked-out module.
(2) Execute "cvs rm ". "rm", "remove", and "delete"
are all synonyms. There can be no "/"s in , so you
must be in the same directory.
Note that simply creating or removing a file is not enough. You
*must* execute the cvs commands.
UPDATING THE REPOSITORY
Editing, adding, or deleting a file in a checked out module as per the
above directions does not affect the repository in any way. If you
want to bring the repository up-to-date with your checked-out module,
thereby publishing your changes to the module:
(1) cd into your check-out module, or a subdirectory
thereof.
(2) Execute "cvs commit".
(This will bring up a file in your default editor, to which you should
add short, meaningful comments about the changes you are checking
in. Then save the file and exit the editor.)
This will merge your changes to PWD and below into the repository.
UPDATING YOUR CHECKED-OUT MODULE
If you want to bring your checked-out module up-to-date with
the repository:
(1) cd into your check-out module, or a subdirectory
thereof.
(2) Execute "cvs update -d".
This will *merge* anything new in the repository into your local
copy. Note that if you have made uncommitted changes locally,
they will still exist, and the repository will not see them.
The "-d" option is needed in order to receive directories that
have been added to the repository that don't exist in your local
area.
For each file in the repository and in your local area, CVS
prints a line "", where status is one of:
U : [Up-to-date]
You have not modified your local copy of the file.
Changes in the repository were successfully merged
into your local copy.
M : [Modified]
You have modified your local copy of the file,
but have not run "cvs commit".
Changes in the repository were successfully merged
into your local copy.
C : [Conflict]
You have modified your local copy of the file,
but have not run "cvs commit".
Local changes conflicted with the repository version.
Your local copy now contains the merged data.
Your old local copy is in ".#.".
A : [Added]
You have cvs-added this file but have not run "cvs commit".
R : [Removed]
You have cvs-removed this file but have not run "cvs commit".
? : This file exists in your local area but does not
exist in the repository.
The status of a file is presented from the point of view of the
local copy. Thus, "added" means that it has been added to the
local area (not that it has been added to the repository).
ADDING AND DELETING DIRECTORIES TO A CHECKED-OUT MODULE
Adding a directory to a checked-out module is just like adding a file:
(1) Create the directory in your checked-out module.
(2) Execute "cvs add ". There can be no "/"s in
, so you must be in the same directory.
Note that the "cvs add " command is *not* recursive. If there
are new files in , they they must be "cvs add"ed afterwards.
You can delete a directory from a checked-out module, but since there
is no such command "cvs rm ", "cvs commit" does not commit the
deletion. You can delete all the files from the directory (and commit
those deletions), but the directory will remain in the repository.
This has the annoying side-effect of creating that directory in your
checked-out copy whenever you do a "cvs update -d". These placeholder
directories are needed in order to check out old versions that use
them.
(If you you use -P as well this should prune those placeholder
directories.)
DELETING YOUR LOCAL COPY
Since CVS does not lock files on checkout, you can, at any time,
simply delete your local copies of files. You risk losing any
un-committed changes, however. To avoid this problem, execute:
cvs release -d
This will delete your local copy iff you have no un-committed
changes.
FILE VERSIONS
Normally, each file is assigned a new version only when it is
modified and committed. It is useful to synchronize all files
at a new version number:
cvs commit -r2.0
This command will ensure that all files (modified or not) are
assigned a new version.
A similar command that assigned a symbolic tag is:
cvs tag