CVS
The Concurrent Versions System (CVS)
provides a framework where multiple users can edit the same files.
As you can imagine, if a group of users edits the files in a single
directory, chaos would reign. Using CVS,
however, a group of people can safely work on the same set of files.
CVS keeps the master copy of the files,
and it records who changed what and when in a central repository. If
conflicts arise, CVS lets you know.
CVS is often used so that programmers can
share code, but it also works well for documentation.
cvsHow CVS Workscvshow it workscvsoverview
In most cases, each set of files that make up a package or project
is stored as a module on the CVS server.
When working with files from CVS, you
checkout a copy of the module on your local
file system. After modifying one or more files, you
commit them back to the central
CVS repository server.
With CVS you may edit a file without
first getting permission or locking the file. The
concurrent part of the
CVS name comes from its ability to
allow several different people to edit different parts of the same
file. As long as none of the changes overlap,
CVS can correctly record their changes.
In case of duplicate changes, they are clearly marked in the files
and the authors must resolve the issue among themselves.
When you commit changes, only changes to files the server knows
about are committed. In other words, if you created a file in your
local checkout of a module, the new file is not automatically
uploaded to the server. You must add the
file to the repository and then commit it. If you remove a file
from your local checkout of a module, you must specify that you
want to remove it from the repository on the CVS server and then
commit the removal of the file.
The specific commands to perform these actions are discussed in
.
If someone has modified the file between the last time you grabbed
the file from CVS and when you try to commit a change,
CVS will try to merge the changes into
the master copy of the CVS server. If
the content you changed is in a different location in the file
than the content changed by someone else, chances are, the commit
action will go through without a conflict.
If someone modified the same content as the content you just
changed and tried to commit, you will see a message that a file
conflict has occurred. Thus, you need to
update your files frequently. It is a good
practice to update them right before you start modifying a file.
Refer to for
instructions on resolving conflicts.
Preparing For CVS Usecvspreparing for use
Before using CVS, you need to establish
an account with the CVS server. After
getting an account, you do not need to perform these actions
again.
Is CVS Installed On Your SystemcvsRPM installation
You must have the CVSRPM package installed. Verify its presence by
typing the command:
$ rpm -q cvs
If you see output similar to
cvs-1.11.19-1, then the package
is installed. A message similar to package cvs
is not installed means you must install the
cvs package before continuing. If you
do not know how to do this, consult your system administrator
who can install it for you.
Generating SSH KeysOpenSSHauthorization keys
The CVS server uses
SSH Protocol 2 keys to authenticate
users. Thus, you need to generate a pair of keys before applying
for a CVS account. If you already
have an SSHDSA key,
you may skip this step.
Tip
You already have a DSA key if you have the
file ~/.ssh/id_dsa.pub on the system.
If your existing DSA key does not require a
passphrase, you are strongly urged to
generate one that does require a passphrase.
Use the following steps to generate a DSA key
used by SSH Protocol 2. It is
required for an
cvs.fedora.redhat.comCVS account.
OpenSSHssh-keygenssh-keygen
To generate a
DSA
key to work with version 2.0 protocol, at a shell prompt,
type the command:
$ ssh-keygen -t dsa
Accept the default file location of
~/.ssh/id_dsa. You are strongly urged
to define and use a passphrase to
enhance the security of your key. Enter a passphrase
different than your account password and confirm it by
entering it again.
Copy your new key to the correct file by typing the
following at a shell prompt.
$ cat ~/.ssh/id_dsa.pub>>~/.ssh/authorized_keys
Check this command carefully before you press the
ENTER
key. If ~/.ssh/authorized_keys
already exists, the contents of
~/.ssh/id_dsa.pub will be appended to
the end of the ~/.ssh/authorized_keys
file.
Change the permissions of your ~/.ssh
directory and your keys with the commands:
$ chmod 755 ~/.ssh$ chmod 644 ~/.ssh/authorized_keysTip
You can have your system remember your passphrase so that you
do not have to type it every time you access the
CVS server. Refer to the
documentation of the ssh-add
program.
Configuring For CVS Accesscvsconfiguring for accesscvsCVSROOTcvsCVS_RSHCVSROOTCVS_RSHcvs.cvsrc.cvsrcAvoiding Repetitive Typingcvsavoiding repetitive typing
Many CVS commands need certain
command line switches to operate consistently. Rather than
typing them every time that command is used, you can save the
switches in a file that CVS will read
before executing your command line.
Create a file named ~/.cvsrc in your home
directory. It should contain the following commands, one per
line:
cvs -z3
diff -uNp
rdiff -uNp
update -dPConfiguring for Read-Only CVS Accesscvsconfiguring read-only accesscvsanonymous access
If your goal is to download the various &FC; documents and to
render them on your system, you only need read-only access to
the CVS repository. Follow the
instructions in this section and then skip directly to
.
Change directories to where you want your files from
CVS to be located, and execute the
following commands:
$ export CVSROOT=:pserver:cvs.fedora.redhat.com:/cvs/docs$ cvs login$ cvs checkout docs-commonmodule-name$ cvs checkoutmodule-name$ cdmodule-name
Once you have checked the module out, it doesn't matter what
your
CVSROOT
is set to because it is stored in the file
CVS/Root for each directory in your local
repository. As long as your current working directory has a
CVS/ directory, the
CVS program will automatically locate
the &FC; repository.
Configuring Read/Write CVS Accesscvsconfiguring read/write accesscvsconfiguring access for authors
To author a new document or to change an existing one, you must
obtain full read/write access to the &FC; Docs
CVS repository. For the full details
on this process, refer to the
http://fedoraproject.org/wiki/DocsProject/NewWriters web site. Below is a summary:
Subscribe to the
fedora-docs-list, which is the main forum for the project.
Generate a GNU Privacy Guard (GPG) key to
identify yourself to the project.
Register for a
Bugzilla account, if you do not have one already.
Bugzilla is how we keep track of bugs,
changes and projects.
Post a
self
introduction to the list.
After your
self
introduction has been approved your
CVS access will be granted.
Every author, and that includes you once your self introduction
has been received, has a unique
$CVSROOT
to access the CVS repository:
$ export CVSROOT=:ext:yourname@cvs.fedora.redhat.com:/cvs/docs$ export CVS_RSH=/usr/bin/ssh
With the
$CVSROOT
and
$CVS_RSH
environment variables in place, you can access the repository:
$ cvs co -c
You will be asked for the passphrase for your
SSH key. Press
ENTER
and you should receive a list of modules already in the
repository.
Basic CVS Commandscvscommands
After configuring your system to work with CVS, checkout the
modules you will be working on.
Tip
To see if you need a correctly-set
$CVSROOT
variable, or the
repository command line switch, see
if you have a CVS/ subdirectory in your
working directory.
If you have a CVS/ directory,
CVS ignores any
$CVSROOT
or command line switch.
Checking Out Modulescvschecking out modules
You only need to checkout a module once. After a local copy of
the module is on your system, it is on your system.
To checkout a module, use the following command:
$ cvs co<module-name>
For example, to checkout the
example-tutorial module, change
to your work directory, and execute the following command:
$ cvs co example-tutorial
A directory called example-tutorial/ is
created in the current directory.
If a branch name is not specified when checking out a module, it
is referred to as the HEAD of the
CVS module.
Checking Out Branches of Modulescvscheck out moduleschecking out branches
Think of a CVS branch as a version
of the files for a particular version of a manual or package.
To checkout a branch of a module, use the following command:
$ cvs co<directory><branchname><module-name>
A directory named <directory>
is created, and the files for the
<branchname> branch of the
<module-name> module are
copied in the directory.
For example, to checkout a branch named BRANCH-VERSION-1.2
from the mymodule module, use
the command:
$ cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule
The BRANCH-VERSION-1.2 branch of the module is checked out in
the mymodule-1.2 directory on your
system.
To determine which branches and tags exist for a file, use the
command:
$ cvs status<filename>
For example, the status of the file
foo.sgml is as follows:
===================================================================
File: foo.sgml Status: Up-to-date
Working revision: 1.47
Repository revision: 1.47 /cvs/docs/custom-guide/rhl-cg-en.sgml,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
BRANCH-VERSION-1.2 (branch: 1.25.2)
Only tags marked as branches in the second column under the
Existing Tags section can be
checked out as a branch.
Updating Filescvsupdating files
To retrieve the latest versions of the files in a module, change
to the directory that contains the files for the module and
execute the command:
cvs update
The latest versions of all the files in the module are
downloaded into your local copy. If you notice a file conflict,
refer to .
Committing Filescvscommitting files
After modifying files in your local version of a module, commit
them to save the changes on the CVS
server:
$ cvs commit "some log message" filename
If you would prefer to write your log message with your
favorite text editor, as defined by the $VISUAL or the $EDITOR
environment variable, just omit the -m "some
log message". The buffer will already contain
comments describing the change; you do not need to delete them
as you enter your own text.
The log message should be as descriptive as possible so that you
and anyone else working on the module understands what changed.
Using a log message such as updated some
files does not accurately describe what has changed
and will not help you in the future. If you are correcting a
bug, use the Bugzilla reference.
The <filename> can be one
filename, a series of filenames separated by spaces, or a group
of filenames specified using wildcards such as
*.png or foo-*.sgml.
If no filename or group of filenames is specified in the
commit command, all outstanding changes of
any kind are committed to the server. The command is recursive
and will include changes in any subdirectories of the module.
Use caution when issuing the commit command
without any filenames because you might not remember exactly
what files changed.
If you notice a file conflict, refer to
.
Adding Filescvsadding files
To add a file to a module, create the file in your local copy
then execute the following command:
$ cvs addfile-to-add
After adding the file, you must commit the
add to copy it to the server:
$ cvs commit "some log message" file-to-addManaging Binary Filescvsbinary files
The most commonly-archived files are simple text files but
sometimes binary files are also archived. The
cvs program recognizes most common
filename extentions such as .png or
.jpg, so cvs
usually "does the right thing".
When a copy of a file is checked out of the repository,
cvs scans it for special keywords,
such as "$id:$" and
replaces the string with a generated value, such as the file
version number.
This keyword substitution usually corrupts binary files, so it
must be turned off if cvs does not
recognize your file as binary. To mark your file as being
binary, and thus needing the keyword expansion turned off, use
the command:
$ cvsfilename
Note that the file must already be checked in to the
CVS repository before the
command can be used. This is OK, since
the keyword expansion is done as the file is checked out and
copied to the local directory, not when the file is committed to
the repository.
Recovering a binary file
If you check a binary file into the repository and then find
it corrupted when it is checked out, do not panic. Simply use
the command as described above, delete
your local file copy, and check it out again.
Removing Filescvsremoving files
If a file is no longer needed in the module, use the
remove command to remove it from your local
copy and then commit the removal to the
server. Even though the file is removed from current version of
the module, an archived copy is still kept on the server and can
be retrieved at any time with the add
command.
$ cvs rm -ffile-to-remove
After removing the file, you must commit the
removal:
$ cvs commit "some log message" file-to-remove
You can not use wildcards in the commit
command to identify removed files. They must be specified with a
exact filename.
If you need to rename a file, it is best to rename the file on
the CVS server so that the history of
the file is preserved. If you need to rename a file, send an
email to
cvsdocs-administrator@fedora.redhat.com asking to have the file renamed.
Status of Filescvsstatus of files
Sometimes it is necessary to view the
status of a file in a
CVS module. To view the status of a
file, use the command:
$ cvs statusfilename
The status report of a repository file is as follows:
Up-to-date
Your revision of the file is identical to the latest
revision on the CVS server.
Locally Modified
You have updated to the latest revision from the server,
but then you modified the file on your system.
Locally Added
You added the file with the cvs add
command but have not yet committed the addition of the
file.
Locally Removed
You removed the file with the cvs
remove command but have not yet committed the
removal.
Needs Checkout
A newer version of the file is on the server and needs to
be retrieved. Even though the status includes the word
checkout, it really means that you need to update your
files with the cvs update command.
Needs Patch
The revision in your local checkout needs a patch to be
the latest revision from the server. Issue the
cvs update command to resolve.
Needs Merge
A newer revision exists on the server and your local
version contains modification not yet committed. This
status usually occurs if you don't have the latest
revision of the file and edit it anyway.
File had conflicts on merge
Similar to Needs Merge,
except when you tried to issue the cvs
update command, the differences could not be
resolved automatically. Refer to
for
more information on resolving conflicts.
Unknown
The CVS server does not know
anything about this file. It has neither been added nor
removed locally and has never been committed to the
server. This status usually occurs for files you should
not commit to CVS such as
generated-index.sgml or for files
that you want to add to the repository but have not yet
issued the cvs add command.
Resolving Conflictscvsresolving conflicts
If you modify a file and the same region is modified by someone
else and committed first, you will probably see a message
similar to the following when committing the file or updating
your local copy of the module:
RCS file: /cvs/docs/module-name/filename.sgml,v
retrieving revision 1.12
retrieving revision 1.13
Merging differences between 1.12 and 1.13 into filename.sgml
rcsmerge: warning: conflicts during merge
cvs server: conflicts found in filename.sgml
C filename.sgml
To resolve the conflict, open the file, search for
<<<<<<<
and determine which version of the content is correct. For
example:
<para>
Some sentence.
<<<<<<< filename.sgml
A sentence that was changed in the working copy.
=======
A same sentence that was changed differently and committed.
>>>>>>> 1.13
</para>
The content between the
<<<<<<<,
and the ======= is the content
from your working copy. The content between the
======= and the
>>>>>>> is
the content from the server.
Resolve the conflict by editing your copy, and commit the file.
Summarycvscommandssummary of
All commands assume you are in the proper directory for the
CVS module.
Basic CVS CommandsCommandDescriptioncvs checkout
<module-name>
or cvs co <module-name>Creates a directory called
<module-name> with the contents of the
module in the directorycvs co -d <directory> -r <branchname><module-name>Creates the <directory> directory
with the contents of the <branchname>
branch of the <module-name> modulecvs update or cvs upUpdate your files with the latest files from the CVS servercvs add <filename>Add a new file "filename" to the CVS servercvs commit -m "My message"
<filename>Update file <filename> with the
latest copy from your computercvs log <filename>View the commit messages for the file <filename>cvs status <filename>View status of the file, such as Locally
Modifiedcvs status -v <filename>View existing tags and branches for filecvs diff <filename>Show diff of the working copy of the file and the latest
version of the file for the branchcvs diff -r1.1 -r1.2 <filename>Show diff of version 1.1 and 1.2 for file
For more information, read the CVS manual available on your
system at
/usr/share/doc/cvs-<version-number>/cvs.ps
(the CVS version might vary) and visit the CVS webpage available
at
http://www.cvshome.org/.
Tip
Since CVS is using
ssh to connect to the
CVS server, you will be prompted
your password before performing your
CVS request. If you want to
configure your machine so that you do not have to enter a
password, refer to the
&RH;
Linux 9 Customization Guide for details
about using ssh-agent.