CVS Destillate

• This is an extremely short quick introduction to CVS.
• This introduction assumes you are familiar with UNIX and know how to adopt the examples for your needs.
• Further, this introduction assumes you are familiar with configuration management in general.

Basics

CVS is a version control system. A version control system performs the task of tracking changes and versions of files. Usually, version control systems are mainly used by software developers.

A CVS Repository is a kind of virtual server for version control. A CVS Module resides in a CVS Repository and holds files and directories of a project or a sub project under version control with all their versioned history. A CVS Sandbox is a local copy of a CVS Module; it holds the files and directories from the CVS Repository in a particular version, usually the latest. A CVS Sandbox is created by Checking Out a CVS Module. The files in the CVS Sandbox are kept up to date by Updating the Sandbox regularly. Changes made within a Sandbox are made available to the co-developers by Committing them, which copies them to the Module in the Repository. The latest version is called CVS HEAD or simply HEAD. There are several possibilities to identify a particular version: A timestamp (date and / or time), a version or a label / tag.

CVS applies versions to individual files. CVS calls these versions Revision. Revisions start at 1.1.

When working with CVS, you'll work like this:

1. Create a Sandbox.
2. Make local Changes.
3. Regularly Update your sandbox.
4. Delete changes you don't feel content with.
5. Commit changes you're content with.
6. Repeat 2. through 5. as required.

For migrators from other version control / configuration management systems

• CVS is optimistic: No locking, CVS tries to solve conflicts using intelligent diffs first.
• One machine can hold several repositories.
• One repository can hold several modules.
• One module consists of any number of directories (perhaps submodules) and files.
• A module is a project (simply spoken).
• A sandbox is a user's local recursive copy of a module's contents.
• All work is done in a sandbox.
• CVS is text- and line-based and uses diff. A tab or 8 spaces makes a difference.
• Successful usage of CVS is based on strict conventions for code style and CVS rules.
• CVS supports branching and merging.
• CVS versions files, neither directories nor whole projects.

User Commands

Create a sandbox

That differs between local access and several forms of remote access

Local access

cvs -d /home/cvsroot checkout myModule

Remote access using pserver

cvs -d :pserver:user@host:/home/cvsroot checkout myModule

Remote access using rsh

cvs -d :ext:user@host:/home/cvsroot checkout myModule

Remote access using ssh

export CVS_RSH=ssh
Then use the same command as with rsh.

If the user on the local and the remote machine use the same name, user@ can be omitted.

To execute the following commands, you must be in a sandbox.

Add a file

1. Create the file
2. Add the file: cvs add file
3. Commit the file: cvs commit file

Add a binary file

Like adding a normal file, but use cvs add -kb file.

Accomplish Changes

1. Change file
2. Commit changes: cvs commit file

Be sure to commit only changes that work: Minimum is that they compile, Optimum is they pass all tests. Not doing so will surely make your teammates very angry.

Update sandbox

This cannot be done often enough, especially on large distributed teams!
cvs update
Per default no new directories will be created in a sandbox. If you want newly created directories, too, use:
cvs update -d
Hint: Usually you always want to use update -d.

View differences

cvs diff

The golden rules

• Only commit working changes.
• Commit often, Commit early.
• Write reasonable log entries.

Update Output

The characters printed by the commands update and commit have the following meaning:

• ? File unknown to CVS.
• A File locally added. commit is required to permanently add the file to the repository.
• C File caused a conflict. Look at the file and change it.
• M File locally modified. commit is required to permanently let the changes take effect.
• P File updated using a patch.
• R File locally removed. commit is required to permanently remove the file from the repository.
• U File updated by copy.

Server Admin

Create a repository

1. mkdir /home/cvsroot
2. cvs -d /home/cvsroot init

Hints on permissions: chmod the repository 2770 or 2776 permissions. Create a group containing all users that should be able to access the repository (in the simplest case use users). If you want that only a module owner can delete a module, set the sticky bit, too, so use 3770 or 3776 then.

Even better use ACLs for permission control. It's recommended to assign repository ACLs after initialization only, so ACLs will affect normal modules but not CVSROOT. The following default ACL is suited: setfacl -m d:u::rwx -m d:g::rwx repository. Advantage: Users now only need to assign the appropriate group, everything else already is done. The default ACL will automatically be inherited on all newly created directories (modules). Exception: Sticky-Bit (makes sense not to inherit).

Create a module

mkdir /home/cvsroot/myModule, don't forget to assign useful permissions (simpliest case chmod g+w module).

Run pserver (optional, only for pserver access)

Add the following lines to /etc/services:

cvspserver      2401/tcp        # cvspserver
cvspserver      2401/udp        # cvspserver

Add the following line to /etc/inetd.conf:
cvspserver stream tcp nowait cvsowner /usr/sbin/tcpd /usr/bin/cvs -f --allow-root=/home/cvsroot pserver
With cvsowner being a user with appropriate permissions to access your repositories.
You may repeat the --allow-root=repositorylocation argument to enable remote access to more than one repository.