This micro-howto will canvas, in a short fashion, the necessary commands and configuration details involved in creating a CVS repository and using Unix permissions to enable access for one or more users (i.e., CVS-only accounts or other Unix accounts). It assumes that you are familiar with the process of logging into your Unix shell.

Creating CVS accounts

New CVS accounts are created from the CVS section of the Control Panel, or using the cvs add command from the Shell Interface:

  csoftadm> cvs add mycvsuser1
  csoftadm> cvs add mycvsuser2

Optionally, you can use the cvs pubkey commands (or from the Control Panel, click on the CVS account in the list) to manage a set of SSH public keys for each CVS account. Public keys are used when password-less authentication is needed.

  csoftadm> cvs pubkey add mycvsuser1
  csoftadm> cvs pubkey list mycvsuser1
Creating a new Unix group

CVS requires the use of standard Unix permissions to manage access control over repositories (we recommend converting to SVN where complex access-control schemes are needed).

We will create a new Unix group which will define a set of users with read/write access over the new repository. It is important to add your main username to the group as well.

  csoftadm> group add mycvsgroup
  csoftadm> group user-add mycvsgroup myself
  csoftadm> group user-add mycvsgroup mycvsuser1
  csoftadm> group user-add mycvsgroup mycvsuser2

After having created the new group, make sure to logout of your existing shell session and login again, otherwise the following chgrp command will fail.

Initializing a CVS repository

Now use the cvs init command on the server to create the new CVS repository, and set the appropriate permissions on the newly created directory.

  $ export CVSROOT="/home/myself/MyCVS"
  $ cvs -d $CVSROOT init
  $ chgrp -R mycvsgroup $CVSROOT
  $ chmod 770 $CVSROOT
Connecting remotely

Now that the repository has been created, you can connect using remote CVS client software. Assuming you are connecting from a Unix workstation with the traditional cvs client:

  $ export CVSROOT="mycvsuser1@myhost.csoft.net:/home/myname/cvs"
  $ export CVS_RSH=ssh
  
  $ mkdir test
  $ cd test
  $ cvs import -m "Test" test mycvsuser1 start

In the previous example, substitute mycvsuser1 for the name of the CVS account you want to connect as. Also substitute myhost for the name of your assigned csoft.net server (if you have at minimum a Budget account, you can use your own domain name instead of myhost.csoft.net). Note that the CVSROOT is recorded with your working copy, so you only need to specify it once.

Command-line CVS cheat sheet

Here are a few examples of common operations that can be performed with the traditional command-line CVS client.

Creating a directory and adding files

To create a directory, html on the server and add a file, new.html to the repository, execute -

  $ cd ~/
  $ mkdir html
  $ cp new.html html
  $ cd html
  $ cvs import -m "My website" html mycvsuser start
  

The above commands will create a directory html in and generate a cvs version of the file new.html to /home/myname/cvs. The exact value of the vendor-tag (here "mycvsuser") and release-tag (here "start") parameters are not all that important for most purposes.

Alternatively, the above importation could have been achieved by the import command.

To confim the existence of the directory and file in the repository, download them, after wiping out your local copy of the html directory -

  $ cd ~/
  $ rm -rf html
  $ cvs checkout html

Deleting files

Removing a file from the repository is performed by the remove command. The elimination of the file from the repository does not become permanent, until the commit command is invoked. Removing directory contents recursively is achieved with the -R flag. For example, to remove new.html -

  $ cd ~/html
  $ cvs remove -f new.html
  $ cvs commit new.html

Transferring binary content

Transfering a binary type file to the server requires some consideration to prevent RCS tag substitution. The most practical method is to append the -kb switch to the add command. Suppose you wish to convey the image.jpg image on the local computer to the html directory on the repository, use this set of commands -

  $ cd ~/html
  $ cvs add -kb image.jpg
  $ cvs commit image.jpg

Displaying file differences

Differences between revisions of text files can be reviewed using the diff command -

  $ cvs diff foo.txt
  $ cvs diff -r1.2 -r1.3 foo.txt

Displaying file history

Revision history of files can be reviewed using the log command -

  $ cvs log foo.txt

The ~/.cvsrc preference file

Default flags for cvs commands can be specified in the ~/.cvsrc file. For example -

  # Use compression level 3
  
  cvs -z3

  # Create directories and prune empty directories.
  
  update -dP

  # Prune empty directories.
  
  checkout -P

  # Produce unified diffs, include newly added/removed files.
  
  diff -uN
Troubleshooting

If the error "can't getwd" appears when attempting to commit or even checkout data, check that the CVS account you are using has search (+x) and read (+r) permissions on all parent directories leading up to the repository.

Links

At least, to have an outside shot at operating cvs semi-competently, peruse the FAQ.