You are here
Editing and managing www.inf.ed.ac.uk with CVS
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 CVSCVS should be available on Unix machines across the School. It is also available for Macs and Windows 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 CVSThe 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:firstname.lastname@example.org:/cvsrootThis 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:email@example.com:/cvsroot
You then need to login to the server.
cvs loginThis 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, as CVS stores the password in your home directory. 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 copyYou 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 (this is for illustration, and is not recommended - see note below) 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 reason 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 inf2c-cs teaching course pages, then you would do the following:
cvs checkout web/teaching/courses/inf2c-cs
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/teaching/courses/inf2c-csThis version of the command will not checkout the web/teaching/courses/inf2c-cs/12-13 sub-directory (and all the files that it contains). Unlike the previous example, which would.
Updating the working copyHaving created a working copy, you will need to keep it up to date with changes that others are making to the tree. Running
cvs updatein 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 -dbut 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 filesIf you want to delete a file, do this:
cd into your working copy area
cvs remove filenameor as an atomic operation:
cvs remove -f filenameYou 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, once removed, it will then no longer be possible to checkout any files that were in that directory.
Editing filesYou 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 should 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.
cvs checkout web/template.htmland 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, and some more information on the main web template.
Adding a new file to the treeCVS 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 filenameYou 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 directoryNew 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".
Committing changesOnce you have finished editing, you can commit changes to the tree using
cvs commitYou 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 specify the log message on the command line with the -m "text here" 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 versionCVS allows you to revert to an earlier version of a file you have previously committed.
Getting CVSCVS should be installed on most, if not all, School unix machines. It is also available for PC and Mac (though MacCVS seems rather old these days, the PC link contains links to new versions of CVS for Macs).
Using MacCVSThe 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
- Save these settings
Use the Action menu to checkout parts of the tree, and the Commit option to commit them back to the repository.