You are here

Editing and managing www.inf.ed.ac.uk with SVN

Printer-friendly versionPrinter-friendly version

[Note: this is a DRAFT document, and uses test names for services.]


Server names used in this document are svntest.inf for the SVN repository, pubtest.inf for the publishing server, and www2.inf for the web server - although these virtual hosts are all on the same physical host. These names may change when the service goes live.

Introduction to SVN

Subversion (usually referred to as SVN) is a version control system, designed for collaborative maintenance of large collections of data (similar to CVS). As such, it is well suited to managing large web sites. However, with power comes some complexity, so SVN is not ideal for the novice user. Copious information can be found on the Subversion website.

SVN maintains a central repository (hosted on svntest.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 should obtain a "working copy" of these files from the SVN 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 SVN

Unlike CVS, there is no initial configuration to identify a repository to work from - you simply choose your working location and download copies of the files you wish to edit from the SVN server (and push them back to the server when finished). Location-specific configuration files are created in your working location at first download.

Note that, in order to use SVN for web publishing, you will need an Informatics publishing account.

To set up SVN to manage local, "working", copies of web pages, select (cd to) a directory to work from (doesn't matter what it's called), and then run an svn command of the form:

svn co https://svntest.inf.ed.ac.uk/svn/infweb/trunk/<INSTITUTE>/<PATH>

("co" is short for "checkout" - either form can be used).

Note that "<PATH>" is that part of the normal browsing URL after the Institute address (so, for a fictional "INST" Institute page, http://www2.inst.inf.ed.ac.uk/info/rbtest.html, "<PATH>" would be the "info" bit - you can't check out individual files).

As just mentioned, you can't check out individual files - SVN works at the directory level, and so you will normally manage a directory and all its contents. Checking-out a directory will include files and any sub-directories, although there are ways of restricting the recursion.

To check out just files from a directory, use the "--depth" option, as in the following example:

svn co https://svntest.inf.ed.ac.uk/svn/infweb/trunk/inst --depth=files

This downloads top-level files for the fictitious INST web-site, but does not include any top-level sub-directories (for other Institutes, simply substitute the required name as appropriate). This command 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.

Note the additional elements in the URL above, namely "svn", "infweb", and "trunk". The "svn" part refers to the SVN repository hierarchy, "infweb" to the Informatics web repository, and "trunk" to the main revision tree for that repository. All web-editing URLs used with SVN from the command-line should include the same "https://svntest.inf.ed.ac.uk/svn/infweb/trunk" component.

Updating the working copy

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

svn update

in a working copy directory will update that directory and all directories below it (synchronise the files on the server with your local, working copy, files - this does not change any files on the server).

Editing files

You can now edit files in this checked-out location. 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 SVN will detect them and attempt to resolve them itself. If SVN is unable to resolve the conflicts, then it will prompt you for the action you wish it to take.

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 in the top-level "web" location. Note that, as mentioned, SVN does not ordinarily deal with files - trying to check-out a file gives:

% svn co https://svntest.inf.ed.ac.uk/svn/infweb/trunk/web/template.html
svn: E200007: URL 'https://svntest.inf.ed.ac.uk/svn/infweb/trunk/web/template.html' refers to a file, not a directory
% 

- the "--depth" argument should be used to check-out just the files in the given location:

% svn co https://svntest.inf.ed.ac.uk/svn/infweb/trunk/web --depth=files
A    web/problems.html
A    web/robots.txt
...
A    web/index.html
A    web/template.html
...
Checked out revision 227309.
%

(which will include the required "template.html" file), and then use this template as the basis for your new file.

Currently the content of this file is:

<!--#include virtual="/ssi/doctype.inc"-->

<TITLE>No Title</TITLE>

<!--#include virtual="/cgi-bin/metabase"-->
<!--#include virtual="/ssi/header.inc"-->

<h1>No Title</h1>

This page has no left navigation bar. If you want the standard left navigation bar, 
then use <a href="/template-leftnav.html">/template-leftnav.html</a> instead.

Your text goes here.

IMPORTANT NOTE: please do not download this template via web browser as it will contain expanded SSIs,
meaning it will not pass the html validation checks when committing back to the web server.  

Further information can be found on <a href="http://computing.help.inf.ed.ac.uk/informatics-main-website-publishing"> Informatics main website publishing </a> 

<!--#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 tree

SVN 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 SVN to add the file into the repository with:

svn add filename

You then, in addition, 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 svn 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.

Committing changes

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

svn commit -m "info message" <PATH>

For example:

% svn commit -m "updated test file" rbtest.html
Adding         rbtest.html
Transmitting file data .
Committed revision 227309.
%

(where <PATH> in this instance is relative to your current directory)

The info message string is stored in the revision history, and should be a brief description of the reasons for the changes.

The SVN 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.

Last reviewed: 
26/03/2018

System Status

Home dirs (AFS)
Network
Mail
Other services
Scheduled downtime

Choose a topic