Computer Science 237 Computer Organization Williams College Fall 2006

This week's optional lab meeting is intended to introduce you to a modern revision control system called Subversion. The objective of a revision control system is to facilitate the management of a collection of files that evolves over time. The most common use of such systems is to maintain computer source code, but they are more widely applicable. I keep my collection of digital photographs, my lectures, notes, and labs, and several software projects in Subversion repositories.

Like other similar systems, Subversion allows concurrent development on different files in the repository, or even different parts of the same file, and maintains a history for these files. Here, we will be creating a repository that you may find useful to track the development of your microprogram for the WC34000 Design Project.

This handout only covers the basics and should be enough to get you going with an appropriate repository for this project. See the Subversion Manual for many more details.

Creating the Repository

The first step is to create the repository. This step must be performed while logged into the computer where the repository is physically located (and on a local storage device, not on network-mounted storage). Since your home directories on the CS Lab Unix systems are mounted from a file server (eringer), and eringer is not intended for interactive use, you will be given a directory on a local disk on a computer in the CS machine room called svnhost (which is really just an alias for a machine named freiburger).

Your directory (which will be created on request) will be your username, and will be located in /cs_svn. Once this directory is created, log into svnhost.cs.williams.edu and create your new repository. The examples in this document use "09abc" as the username, you should substitute your own username. Examples here use ucode as the repository name.

svnadmin create /cs_svn/09abc/ucode

This will create a collection of files under the path above. You should not need to make any changes here.

Now that you have created your initial repository, you will no longer need to be logged into svnhost. You may log into any CSLab Unix system for the remainder of the setup procedure and to use your repository.

In your home directory, create a directory for your project. A good name might be ucode. And in that directory, create three subdirectories, branches, tags, and trunk. These are used by Subversion to maintain more complex projects, but it will make things more straightforward if we use them even for our simple repositories.

mkdir ucode
cd ucode
mkdir branches tags trunk

You will now import this directory structure into your repository:

svn import ~/ucode svn+ssh://svnhost/cs_svn/09abc/ucode -m "initial import"

This command tells Subversion (svn) to import the files in the ucode directory into the repository found on svnhost in the directory /cs_svn/09abc/ucode using the svn+ssh protocol.

The response should look something like this:

Adding         /home/cs-students/09abc/ucode/trunk
Adding         /home/cs-students/09abc/ucode/branches
Adding         /home/cs-students/09abc/ucode/tags

Committed revision 1.

Next, you need to check out a copy of the repository that will become your working copy. In a directory where you will be doing your work, issue the command:

svn checkout svn+ssh://svnhost/cs_svn/09abc/ucode/trunk ucode

You should see a message:

Checked out revision 1.

and you should now have a subdirectory ucode in your working directory. At first, it may seem empty, but if you issue the command ls -al within the ucode directory, you will find that there is a hidden subdirectory .svn where Subversion will keep information about this working copy of your Subversion repository. You may look at the contents, but do not change them (other than with the Subversion commands you will issue).

Using Your Repository

Now that you have checked out a copy of your still empty repository, you can start using it to store your files. Start by creating a file phase2.mal inside the repository. Add a few lines to the file, perhaps naming a few registers. Now, you can add this file to the repository with the command:

svn add phase2.mal

You should see the response:

A         phase2.mal

This does not actually add the file phase2.mal to the repository, just says that the file should be included the next time you commit your changes in the working copy to the repository.

To commit the file to the repository, you should issue the command:

svn commit -m "Added phase2.mal file"

The string after the -m flag is just a log message - you may replace it with anything you wish.

You should see the output:

Adding         phase2.mal
Transmitting file data .
Committed revision 2.

This means that Subversion has added phase2.mal to the repository and created revision 2 of the repository. If at any point in the future, you wanted to retrieve the state of the repository at this time, you could do so.

From this point on, you will begin a cycle of making changes in your working copy and committing those changes when you are satisfied that they are working. When you have made a change that you wish to commit, again issue the svn commit command above.

You may have multiple working copies, perhaps to work on different parts of your program. If you commit a change from one working copy and wish to update the other working copy to include those changes, change into the directory that you wish to update and issue the command svn update.

You may add more files, but only add those that you wish to track in your repository. Files such as the hmem file generated when you run male or other input or output files should not be added. Subversion will ignore them.

Other Subversion commands you may find useful on a regular basis include the svn status command to learn which files in your repository have changed since the last commit, and the svn diff command to see what those changes are.

Again, this only scratches the surface of what a revision control system such as Subversion can do. You are encouraged to learn more about it from the manual or other web pages or by asking lots of questions about it.