Using CVS on the Informatics Server

Author Simon Wilkinson. Updated by Neil Brown
Revision 1.32
Please send comments/corrections to webadmin @ inf.ed.ac.uk

CVS is a version control system, designed for collaborative maintenance of large collections of data. As such it is well suited to managing large web sites. However, with power comes some complexity, so CVS is not ideal for the novice user.

Introduction to CVS

CVS should be available on Unix machines across the School. It is also available for Macs and Win32 PCs. For more details see the section on Getting CVS at the end of this document. These instructions assume that the Unix version of CVS is in use - details on how to convert these to the Mac and PC version are contained later in this document.

CVS maintains a central repository (hosted on www.inf.ed.ac.uk), which is the definitive copy of all of the files held by the web server. In order to edit these files you obtain a working copy of these files from the CVS repository. You can then make whatever changes you wish to those files, and send them back to the server, along with a log message, detailing the changes you made and any reasons for them. The new files will not appear on the web server until you have carried out this step.

Configuring CVS

The first step is to configure CVS so that it knows about our repository, and about your identity on it. You will need an Informatics publishing account to do this. On Unix, type the following command into the shell in which you intend working (or place it in your Bash RC file so it is always run).

export CVSROOT=:pserver:user@www.inf.ed.ac.uk:/cvsroot

This tells CVS to look on the machine www.inf.ed.ac.uk, and to use the username user.

If you are using a csh-like shell instead of bash, you should use the csh syntax instead - that is:

setenv CVSROOT :pserver:user@www.inf.ed.ac.uk:/cvsroot

You then need to login to the server.

cvs login 

This will prompt you for a password, which is the password you entered when you requested your Informatics publishing account. You need only login once, however CVS stores the password in your homedirectory. If you are worried about this you can use cvs logout to remove the stored copy, and then use cvs login again, later.

Creating a working copy

You will now want to checkout a copy of those files in the tree which you wish to edit. This creates a local copy of the files concerned, but does not in anyway "lock" them on the server. In other words, this operation does not give you exclusive write access.

The www.inf.ed.ac.uk tree is rooted at the 'web' directory, so to checkout everything in it use:

  cvs checkout web/

As the tree gets larger, the amount of time, disk space, and processor power used to do this will increase. Please do not checkout the entire tree unless you have a legitimate reson for doing so.

The above checkout operation will create files in a subdirectory called "web/" of the current directory. If you wish to checkout into a different directory (this is especially useful when checking out small sections of the tree) you can use the -d option. For example

cvs checkout -d mycopy web/

Of course, it is preferable not to checkout the entire tree, and in general you should checkout only the sections that you intend on working on. For instance, if you wanted the Computing Committee pages, then you would do the following:

cvs checkout web/admin/committees/computing

The above examples checkout the specified directory, and all sub-directories and files contained with in it. If you want to checkout just that directory and the files it contains, without also checking out any further subdirectories, then add the -l option to the command. Eg:

cvs checkout -l web/admin/committees/computing

This version of the command will not checkout the web/admin/committees/computing/meetings/ sub-directory (and all the files that it contains). Unlike the previous example, which would.

Updating the working copy

Having created a working copy, you will need to keep it up to date with changes that others are making to the tree. Running

cvs update

in a directory in your working copy will update that directory and all directories below it. However, it will not create any new directories that did not exist in your working copy when you checked it out from the server. You can create these directories with

cvs update -d

but you may find that it pulls in files that you didn't originally have. This isn't a problem, because you don't have any exclusive rights to files in your working copy.

Deleting files

If you want to delete a file, do this:
cd into your working copy area

rm filename

cvs remove filename

or as an atomic operation:

cvs remove -f filename

You then still need to commit your delete/remove:

cvs commit filename

Deleting directories - you can't

You cannot cvs remove directories.

CVS allows you to undelete files, by checking out the last version prior to the cvs remove. It stores this undelete history in the directory, so to be able to provide this undelete facility, cvs can't let you remove the file's parent directory.

If you really do want a directory removed, perhaps because you created one accidentally, then contact support and we can do it behind the scenes. However, it will then nolonger be possible to checkout any files that were in that directory.

Editing files

You can now edit files in this checked out section. However, remember that you do not have exclusive access - it is possible that other people could be editing the same document as you. The best way to resolve this is through communication - the number of people editing files that you are authorised to edit should be small. If conflicts do occur, which they may do very rarely, then CVS will detect them and attempt to resolve them itself. If CVS is unable to resolve the conflicts, then it will prompt you for the action you wish it to take.

Note for manpage hawks: CVS does support notification of edits using cvs edit and cvs watch. Feel free to use these within your areas of the site, but we do not recommend them for general use.

Please remember the tips in the guide to the Informatics web server when editing HTML content.

The Standard Header and Footer

If you would like to create a new file that uses the standard Informatics header and footer, then checkout the standard template file with:

cvs checkout web/template.html

and use this template as the basis for your new file. Currently the content of this file is:

<!--#include virtual="/ssi/doctype.inc"-->
<TITLE>Put your title here</TITLE>
<!--#include virtual="/cgi-bin/metabase"-->
<!--#include virtual="/ssi/header.inc"-->
Content goes here

<!--#include virtual="/cgi-bin/locationbar"-->
<!--#include virtual="/ssi/footer.inc"-->

If you wish to use your own include files, then see the FAQ on the subject of SSIs.

Adding a new file to the tree

CVS does not automatically add new files back into the repository. So, to create a new file, you must first create the file, with your desired content, then explicitly tell CVS to add the file into the repository with

cvs add filename

You still need to commit your changes, as detailed below.

Please consult the Informatics web server guide section on file naming before creating new files.

Adding a new directory

New directories can be added in the same way as new files - create the directory (usually with the mkdir command), then add it to the repository with cvs add. Again, please follow the recommendations on directory naming.

Remember that a directory/container must contain an index.html file. Otherwise people will receive a "Forbidden" error message when they browse to that container.

See above about deleting directories, which simply says "You can't".

Commiting changes

Once you have finished editing, you can commit changes to the tree using

cvs commit

You will be prompted for a revision log message. This is stored in the revision history, and should be a brief description of the reasons for the changes. You can specifiy the log message on the command line with the -m option. The CVS repository validates all HTML documents submitted to it. You may see error messages detailing faults in your HTML, which will need to be fixed before they will be accepted for publishing.

Backing out changes - reverting to an older version

CVS allows you to revert to an earlier version of a file you have previously committed.

Getting CVS

CVS should be installed on most, if not all, School unix machines. It is also available for PC and Mac

Using MacCVS

The logical steps in using CVS on the Macintosh are the same as outlined above, however interaction takes place using a graphical interface.

To configure your working copy:

• Create a new session (File/New) and save it to give it a name.
• Open the preferences dialog (Edit/Session Settings...)
• In the "Remote Host Information" panel, set the following:

  Server Hostname:	www.inf.ed.ac.uk
  CVS Root:	/cvsroot
  Authentication method:	Password

  and enter your CVS username and password into the boxes provided
• Save these settings

Use the Action menu to checkout parts of the tree, and the Commit option to commit them back to the repository.

Problems

If you have any problems, try looking at the FAQ.