CVS stands for Concurrent Version System. It is a version control system that has
been developed in the public domain by many people beginning in 1986. Currently, CVS
is maintained by Cyclic Software and there is lots of information of their web site
at http://www.cvshome.org/.
Using CVS, you can record the history of your source files (normally text files,
binary files are handled with some restrictions). Instead of save every version of
every file, CVS stores only the differences between the versions. CVS also helps you
if you are working in a group on the same project: CVS merges the work when each
developer has done its work.
Moreover, CVS allows you to isolate changes onto a separate line of development,
known as a branch. When you change files on a branch, the changes do not
appear on the main trunk. Later you can move the changes from one branch to
another branch (or the main trunk) by merging.
The CVS repository stores a complete copy of all the files and directories
which are under version control. Normally, you never access any of the files in the
repository directly. Instead, you use CVS commands to get your own copy of the files
into a working directory, and then work on that copy.
CVS can access a repository by a variety of means. It might be on the local computer,
or it might be on a computer across the room or across the world. Using CVS
with a remote repository we talk about client/server operation. Several
protocols are supported to connect to the remote repository, e.g. rsh, password
authentication, GSSAPI, kerberos.
You can define several repositories if you have different development groups that
work on separate projects without sharing any code. All you have to do is to specify
the appropriate repository when you are starting the session.
If you want to keep track of a set of revisions involving more than one file, you can
use tags to give a symbolic name to a certain revision of each file. You can
think of the tag as a handle. When you pull on that handle, you get all the tagged
revisions.
file1 file2 file3 file4 file5
1.1
1.1
1.2 1.1
1.2 *** 1.1 *** 1.3 *** 1.2 *** 1.1 *** <*** tag ***>
1.3 1.2 1.4
1.5
So it's a good idea to tag every software release, patch, or merge with its unique
tag.
Often, two developers try to edit the same file simultaneously. CVS supports some
solutions for this situation, e.g.
-
File locking or reserved checkouts: Only one person is allowed to
edit each file at a time.
-
Use watches: Watched files are checked out read-only. To make them
read-write (and inform others watchers) the cvs edit command is used.
-
Unreserved checkouts: The rarity of serious conflicts may be surprising, so
often neither file locks nor watches are used. If an overlap occurs, CVS prints a
warning and the resulting file includes both versions of the lines that overlap,
delimited by special markers.
Note: In some cases unreserved checkouts are clearly inappropriate (e.g. if no
merging tool exists).
3. A Sample Session
To learn the most used CVS commands, we are walking through a typical work session.
The commands are shown as CVS command line and over WinCVS menus. Note that the most
used WinCVS commands have short cuts or context sensitive popup menus (by clicking
the right mouse button).
The first thing you must set-up your CVS session. Set your environment and login to
the server.
CVS commands
Set $CVSROOT for local access...
> CVSROOT=<cvs_root>
> export CVSROOT
... or remote access and connect to the CVS server:
> CVSROOT=:pserver:<username>@<servername>:<cvs_root>
> export CVSROOT
> cvs login
WinCVS commands
Start your WinCVS client program. First time you must set-up your preferences.
Admin -> Preferences -> General Settings
Admin -> Preferences -> Global Settings
Admin -> Preferences -> WinCVS Settings
Then you can login to the CVS server:
Admin -> Login
Remarks
The repository's root directory <cvs_root> is defined either on the local
server or on the remote server <servername>. After the successful login, you
are ready to work under CVS.
Next thing you must do is to get your own working copy of the source. Change to your
working directory and use the checkout command to do this (option -r for read-only).
CVS commands
> cd <work_dir>
> cvs -r checkout <module>
WinCVS commands
Create -> Checkout module ...
Choose your working area
Choose your module
Use the default settings in this example. By default,
files are checked out as read-only.
Remarks
After the successful login, the sources of <module> will be copied into your
local working area <work_dir>. <module> is either a valid module name or
a relative path in the repository.
If you have already checked out the sources you can update your working area with the
newest checked-in files:
CVS commands
> cvs update
WinCVS commands
Select the <module> in the module tree, then the menu Modify à Update
selection...
Remarks
The default directory for the update command is always the current working directory.
The command updates the subdirectories recursively.
In this chapter we describe the normal way to edit a source file using reserved
checkout (file locking). Change to the working directory where the file to edit
exists.
CVS commands
> cd <work_subdir>
> cvs admin -l <filename>
> cvs update <filename>
> cvs edit <filename>
> vi <filename>
WinCVS commands
Select the file <filename> in the file list, then the menus
-
Trace -> Lock selection
-
Modify -> Update selection ...
-
Trace -> Edit
-
Query -> View selection or View with <default_editor>
You have decided to make a new version of the file <filename>. This will store
your new file in the repository and make it available to other developers. For the
undo of changes see the next chapter.
CVS commands
> cvs commit -m "<log_message>" <filename>
> cvs unedit <filename>
WinCVS commands
Select the file <filename> in the file list, then the menu Modify -> Commit
selection...
Commit settings, Enter the log message
The commit command automatically unlocks the file
<filename>. The unedit command is only
successful if watches are in use. WinCVS also automatically makes the file read-only.
You have decided to undo the changes of the file <filename>. In this case, all
the commands should be reverted. For the commit of changes see the previous chapter.
CVS commands
> cvs unedit <filename>
> cvs update <filename>
> cvs admin -u <filename>
WinCVS commands
Select the file <filename> in the file list, then the menus
-
Trace -> Unedit selection
-
Trace -> Unlock selection
You can finish your session with the cleanup of your working area. Use the release
command therefore. This command checks that all your modifications have been
committed.
CVS commands
> cd <work_dir>
> cvs release -d <module>
WinCVS commands
Select the <module> in the module tree, then the menu Trace à Release
selection.
Remarks
The -d option removes your working copy too. Otherwise you can remove the working
area manually.
4. Advanced Commands
In this chapter some further CVS commands are described. This commands are very
useful but not used in the daily business. Most of this commands have a variety of
options so we recommend to look up in [CVS] as well.
To add a new file to a directory, follow these steps:
-
You must have a working copy of the directory.
-
Create the new file inside your working copy of the directory.
-
Use the command cvs add <filename> to add
this file to version control. For binary files use the option -kb.
-
Use the command cvs commit <filename> to
actually check in the file into the repository. Other developers cannot see the
file until your perform this step.
You can also use the command cvs add to add a new
directory as well. Note: Unlike most other command the add command is not recursive.
New files are added, and old files disappear. But you want to be able to retrieve an
exact copy of old releases everytime.
Here is what you can do to remove a file:
-
Make sure that you have not made any uncommitted changes to the file.
-
Remove the file from your working copy of the directory (use rm or delete).
-
Use cvs remove <filename> to tell CVS that
you really want to delete the file.
-
User cvs commit <filename> to actually
perform the removal of the file form the repository.
Removing directories is similar to removing files: The way that you remove a
directory is to remove all the files in it. You don't remove the directory itself.
Instead you specify the option -P to cvs update, cvs checkout, or cvs export, which
will cause CVS to remove empty directories from working directories.
Tags are symbolic names to a certain revision of each file. We recommend to tag all
software releases, patches, or merges with its unique tag.
You have two possibilities to tag: Running the cvs
tag command causes CVS to select the revisions which are checked out in the
current working directory. The cvs rtag command works
directly on the repository contents and requires no prior checkout and does not look
for a working directory.
Using the Working Directory
For the following cvs command tags the current working directory.
CVS commands
> cd <work_dir>
> cvs tag -c <tag_name> [file | directory | module]
WinCVS commands
Select the module in the module tree or the file in the file list, then the menu
Modify -> Create a tag on selection...
Remarks
You can use the option -c to check for uncommitted changes
(locally modified files).
Using the Repository
The cvs rtag command tags the repository as of a
certain date or time. This is useful to tag the latest version. rtag works directly on the repository and requires no prior
checkout. This command is not supported by WinCVS. Tag the most recent revision no
later than <date> ...
> cvs rtag -f -D <date> <new_tag> [file | directory | module]
... or tag those files that contain existing tag <existing_tag>
> cvs rtag -f -r <existing_tag> <new_tag>
[file | directory | module]
CVS allows you to isolate changes onto a separate line of development, known as a
branch. When you change files on a branch, those changes do not appear on the
main trunk.
Create a Branch
Again you will use the cvs tag or cvs rtag commands to create a branch. The tag
command uses the current revisions in the working copy, the rtag command works
directly in the repository:
> cvs tag –b <branch_tag>
... or tag those files that contain existing tag <existing_tag>
> cvs rtag -f -r <existing_tag> <branch_tag>
[file | directory | module]
Note that branches always get created in the repository, not in the working copy. So
you must checkout the branch files to your working directory explicit:
> cvs -r checkout -r <branch_tag> <module>
or switch the working directory to a given branch with the cvs update command:
> cvs -r update -r <branch_tag> <module>
Now you can work on the branch files and commit your changes back to repository.
Merging a Branch
You can merge changes made on a branch into your working copy. The working copy could
be either the main trunk or another branch.
> cvs update -j <branch_tag> [file | directory | module]
The option -j merges the changes made between up to the newest revision on that
branch into your working copy. Conflicts can result from the merge operation. This
conflicts should be resolved before committing the changes to the repository.
If the development continuos on that branch, you may want to merge those changes
again. As recommended earlier each merged revision should be tagged in the branch.
Use that tag for subsequent merges:
> cvs update -j <merge_tag> -j <branch_tag>
[file | directory | module]
The most common use for CVS is to store text files. If you are willing to give up a
few of CVS' abilities (such as display differences, merging revisions), CVS can store
binary files as well.
The -kb option available in some CVS commands insures
that neither line ending conversion nor keyword expansion will be done. New files can
be added as follows:
> cvs add -kb -m "A binary file" <filename>
Or you can use the following commands to recover the binary file:
> cvs admin -kb <filename>
> cvs update -A <filename>
> cvs commit -m "Make it binary" <filename>
CVS can use a mechanism known as keyword substitution or keyword
expansion to help identifying delivered files. Embedded strings of the form
$keyword$ in the source file are expanded to strings of the form
$keyword:value$.
This is a list of the keywords. For full explanation, please refer to [CVS].
|
$Author$
|
The login name of user who checked in the
revision.
|
|
$Date$
|
Date and time (UTC) the revision was checked
in.
|
|
$Header$
|
A standard header.
|
|
$Id$
|
Same as $Header$ (except RCS file without
path).
|
|
$Name$
|
Tag name used to checkout this file.
|
|
$Locker$
|
The login name of the user who locked the
revision.
|
|
$Log$
|
The log message supplied during commit.
|
|
$RCSfile$
|
The name of the RCS file without a path.
|
|
$Revision$
|
The revision number assigned to the
revision.
|
|
$Source$
|
The full pathname of the RCS file.
|
|
$State$
|
The state assigned to the revision.
|
5. Administrator Tasks
In this chapter some administrator tasks are discussed. The directory $CVSROOT/CVSROOT contains some administrative files. You can
edit this files in the same way that you would edit any other module: Get a working
copy, edit it, and commit your changes in the normal way. When you check in an
administrative file, CVS rebuilds the administrative file database.
The most important of the administrative files is the modules file. It defines all
modules in the repository. This is not strictly necessary, but modules can be
convenient in grouping together related files and directories.
Three different line formats are valid:
# key -a aliases...
# key [options] directory
# key [options] directory files...
This is a sample of modules file:
CVSROOT CVSROOT
modules CVSROOT modules
test projects/test1
One could write books about security issues... Here are only some recommendations.
The directory $CVSROOT/CVSROOT contains confidential
information. You must control the permissions on this directory very restrictive,
specially if you are using the password authenticated server.
It is possible to grant read-only access to the repository using the password
authenticated server. There are two ways to do this: by inclusion and by exclusion.
Inclusion means listing all users with read-only access in the $CVSROOT/CVSROOT/readers file. Exclusion means explicitly
listing everyone who has write access in the $CVSROOT/CVSROOT/writers file. Please refer to the following
rules:
-
If readers exists, and the user is listed in it,
then the user gets read-only access.
-
If writers exists, and the user is not listed in
it, then the user gets read-only access. This is true even if readers exists, and
the user is not listed in it.
-
If both files exist and the user is listed in them, CVS resolves this conflict in
a conservative way: such a user gets read-only access.
When authenticating a password, the server first checks for the user in the file. If
it finds the user, it will use that entry for authentication, else the server can try
to authenticate user name and password using the operating system's identification
(fall back behaviour). Please find further information in [CVS].
In a first step the files must be created in the repository. The next step is to
define the module in the modules file. This step is
not strictly necessary, but modules can be convenient in grouping together related
files and directories.
Creating the Repository from Existing Files
You will probably already have several projects that can be put under CVS control. In
this case you will use the import command:
> cd <working_dir>
> cvs import -m "Imported sources"
<repository_dir> <vendor_tag> <release_tag>
The files in the working directory <working_dir> are imported in the CVS
repository as $CVSROOT/<repository_dir>. <repository_dir>
could contain a directory structure as well.
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.
If some of the files you want to import are binary, you may want to use the wrappers
features or to change them manually to binary.
Create an empty directory structure and import this structure to create the
corresponding directory structure in the repository. Then use the add command to add
files as they appear.
Check that the permissions CVS sets on the directories inside $CVSROOT are
reasonable.
Creating the Repository from Other Version Control Systems
If you have a project which you are maintaining with another version control system,
you may wish to put the files from that project into CVS and preserve the revision
history of the files. Here the way for RCS is shown, please see [CVS] for other
systems.
This is one of the few times when it is a good idea to access the CVS repository
directly: Create the appropriate directories in CVS if they do not already exit. Then
copy the files in the appropriate directories in the CVS repository without changing
the file name.
Note that the RCS files are not locked when you copy them into CVS.
5.4 Backing Up the Repository
For the most part it is possible to backup the repository just like any other files.
However, there are a few issues to consider:
To get a consistent state of the repository, one should not use CVS during backup. To
not use CVS, you might forbid logins or turn off your CVS server. Another idea is to
lock CVS.
6. Examples
- Go to the top of the project tree: cd
/home/myproj
- cvs import -m "Initial Import into CVS" myproj
akadia start
myproj = Name under which you will check out the project
akadia = vendortag
start = releasetag
The directory tree in now imported in the CVS, however you must now checking out a
working copy, the current directory tree is still not a CVS working copy.
- Go to another empty directory
Local Repository
- cvs checkout myproj
Remote Repository
- cvs -q -d
:pserver:zahn@rabbit.akadia.com:/opt/cvs-root \
checkout myproj
You get the same as what you imported, with the addition of a subdirectory named CVS
- cd CVS (In the working CVS directory)
- ls -l
-rw-r--r-- 1 zahn dba 134 Aug 29 13:56 Entries
-rw-r--r-- 1 zahn dba 7 Aug 29 13:56 Repository
-rw-r--r-- 1 zahn dba 14 Aug 29 13:56 Root
- cat Repository
myproj
- cat Entries
/README.txt/1.1.1.1/Tue Aug 29 10:30:36 2000//
/hello.c/1.1.1.1/Tue Aug 29 10:30:36 2000//
D/a-subdir////
D/b-subdir////
D/myproj////
- cat Root
/opt/cvs-root
Make a change on hello.c, even if nothing in the repository has changed since checkout,
something in the working copy may have, and update will show that.
- cvs update
cvs update: Updating .
M hello.c
cvs update: Updating a-subdir
cvs update: Updating a-subdir/subsubdir
cvs update: Updating b-subdir
cvs update: Updating myproj
The M next to hello.c means the file has been modified. If you want a
more detailed look at the changes, you can get a full report in diff format.
- cvs diff
- cvs -Q diff (Shorter
Output)
- cvs -Q diff -c (Display some lines of
context on either side of a change)
The commit command send modifications to the repository.
- cvs commit -m "Error corrected in explain()"
cvs commit: Examining .
cvs commit: Examining a-subdir
cvs commit: Examining a-subdir/subsubdir
cvs commit: Examining b-subdir
cvs commit: Examining myproj
Checking in hello.c;
/opt/cvs-root/myproj/hello.c,v <-- hello.c
new revision: 1.2; previous revision: 1.1
done
Check the status of the files in the CVS repository
- cvs status
Finding out who did what (Browsing Log Messages)
- cvs log
Create the new file in the working CVS directory, add and commit it in CVS:
- cvs add newfile.c
cvs server: use 'cvs commit' to add this file permanently
- cvs ci -m "Added newfile.c" newfile.c
RCS file: /opt/cvs-root/myproj/newfile.c,v
done
Checking in newfile.c;
/opt/cvs-root/myproj/newfile.c,v <-- newfile.c
initial revision: 1.1
done
Unlike adding files, adding a new directory is done in one step:
- mkdir c-subdir
- cvs add c-subdir
Directory /opt/cvs-root/myproj/c-subdir added to the repositor
CVS handles CRLF correctly on textfiles, but this is not desired for binary files,
therefore use the -kb option. For Textfiles you may disable the keyword expansion as
well: use -ko.
cvs add -kb who
cvs ci -m "Binary File added" who
Removing a file is similar to adding one, except there's an extra step: You have to
remove the file from the working copy first.
rm newfile.c
cvs remove newfile.c
cvs ci -m "removed newfile.c" newfile.c
Removing newfile.c;
/opt/cvs-root/myproj/newfile.c,v <-- newfile.c
new revision: delete; previous revision: 1.1
done
CVS doesn't really keep directories under version control. If you want to remove a
directory from a project, you first remove all the files in it, then use update -P to
remove the directory from the working directory.
cd a-subdir
rm file1 file2 file3
cvs remove file1 file2 file3
cvs ci -m "Removed all files"
Now remove empty directory from working copy
cvs update -P
CVS does not automatically bring new directories from the repository into your working
copy. From time to time you should run update -d, telling to bring down any new
directories from the repository.
cvs update -d
All empty directories from the repository are now rebuild in the working copy.
Renaming a file is equivalent to creating it under the new name and removing the old
file.
mv README.txt INSTALL.txt
cvs remove README.txt
cvs add INSTALL.txt
cvs ci -m "renamed README.txt to INSTALL.txt" README.txt INSTALL.tt
Removing README.txt;
/opt/cvs-root/myproj/README.txt,v <-- README.txt
new revision: delete; previous revision: 1.2
done
RCS file: /opt/cvs-root/myproj/INSTALL.txt,v
done
Checking in INSTALL.txt;
/opt/cvs-root/myproj/INSTALL.txt,v <-- INSTALL.txt
initial revision: 1.1
done
Renaming Directories is a bit cumbersome. The best policy is to try to come up with a
good layout when you initially import the project. One solution to rename one or more
directories is to checkout the project, make the changes on the local working copy,
delete the CVS project in the repository and import the changed project again.
cd myproj
mv a-subdir z-subdir
find . -name CVS -exec rm -rf {} \;
cd /opt/cvs-root
rm -rf myproj
cd /home/zahn/myproj
cvs import -m "Test Projekt" myproj akadia start
rm -r myproj
cvs checkout myproj
The date-based retrieval are done by passing update the -D flag. With the -D option,
update retrieves the highest revision of each file as of the given date and it will
revert the files in the working copy to prior revisions if necessary. Retrieving by
date is useful when the mere passage of time is your main concern.
cvs -q update -D "2000-09-14"
Often you really want to retrieve the project as it was at the time of a specific event
-- perhaps a public release, a known stable point in the software development or the
addition or removal of some major feature. The method CVS offers for making such marks
is known as tagging.
Setting a Tag (Snapshot):
cvs rtag Final-Release myproj
Retrieving the tagged release (Snapshot):
cvs checkout -P -r Final-Release myproj
Removing Tags (untagging)
cvs rtag -d Final-Release myproj
|
