Subversion is an open-source Revision Control System (RCS). With Subversion you will be able to make time-based snapshots of your files and folders. This is especially useful for creating time-based snapshots of source code. In most of my code work, I use Subversion (or svn) for my code repositories. Installing and maintaining an svn repository is very simple and straightforward.

Installing Subversion

This tutorial will show you how a simple svn repsitory is created and mantained in a Debian-based system using svn 1.2 and up. For this, we will be using Ubuntu 5.10 server. First thing to do is update the software repositories. From the console, you can download and install svn. You need to have sudo privileges to install packages into the system.

jerome@pingu64:~$ sudo apt-get update
jerome@pingu64:~$ sudo apt-get install subversion

Apt should be able to resolve and install dependencies of svn when you apt-get install it (these are libapr0 and libsvn0).

Creating the code repository

After installing svn, we will now create our first code repository. We will be storing our source files locally but version control will be handled by svn. Let's say we'll be creating a repository to store our source code for catpants inventory. We will be creating our catpants code repository in our $home directory (/home/$user). To create the repository, we will be using the svnadmin tool.

jerome@pingu64:~$ svnadmin create /home/jerome/catpantscode

You might want to check what's inside the catpantscode folder once it was created by svnadmin:

jerome@pingu64:~$ ls catpantscode/
conf dav db format hooks locks README.txt

The new catpantscode directory in your $home now contains a database which will store the timed-snapshots of the repository. It will not contain the actual source files.

The code repository may exist anywhere in your system. Some svn users create their repositories in their $home, but you can also use /var, /opt or even create an /svn folder in root (/).

You can get more detailed help for svnadmin by invoking svnadmin help on the command line.

jerome@pingu64:~$ svnadmin help

Importing existing code to the repository

Assuming you already have a working project folder in your system, you may want to put those files under revision control with our catpantscode repository. Subversion has no concept of a "project," it merely monitors time-based changes to files and folders stored in the repository. The structure of your repository is up to you.

But for this tutorial, we will be using the trunk, branches and tags folder convention. Let's say we already have a project called catpantsproject in our system that contains our trunk, branches and tags folders:

jerome@pingu64:~$ ls catpantsproject/
branches tags trunk

We will import our catpantsproject folder into the catpantscode repository using the svn import command:

jerome@pingu64:~$ svn import /home/jerome/catpantsproject file:///home/jerome/catpantscode -m "initial import"
Adding /home/jerome/catpantsproject/trunk
Adding /home/jerome/catpantsproject/trunk/README
Adding /home/jerome/catpantsproject/branches
Adding /home/jerome/catpantsprject/tags

Committed revision 1
jerome@pingu64:~$

The svn import command instructs svn to import the catpantsproject folder to the catpantscode repository. The -m flag means we would like to create a memo telling the repository that this is our "initial import".

Doing a repository checkout

The next thing you would have to do is create a local Working Copy or wc of the catpantscode. The wc is your local copy where you can manipulate the files and folders you checked out from the catpantscode repository. This is where you should mess up your code before submitting it for revision control. Do not directly manipulate the repository itself or you'll mess up the revision control system.

To do a checkout, just invoke svn checkout followed by the path of the catpantscode repository and the name of your choice for the local wc.

jerome@pingu64:~$ svn checkout file:///home/jerome/catpantscode pinkcatpantscode
A pinkcatpantscode/trunk
A pinkcatpantscode/trunk/README
A pinkcatpantscode/branches
A pinkcatpantscode/tags
Checked out revision 1.
jerome@pingu64:~$

A pinkcatpantscode folder will be created along with the checked out files from the catpantscode repository. This would be your local wc folder where all work will be done.

No you have a local wc, you can now manipulate the files and folders inside. Here are the most common commands you will use when making changes and submitting them back to the repository:

* Run svn diff to see unified diff output of your changes.
* Run svn commit to commit the new version of your file to the repository.
* Run svn update to bring your working copy “up-to-date” with the repository.

Allowing network access to the svn repository

Subversion ships with svnserve, a lightweight custom server that can be used for allowing network access via TCP/IP of the svn server. This allows remote clients to work on a single svn server and work from a corporate LAN or have true global collaboration via the Internet. Clients contact the svnserve server with the svn:// schema. Clients will also need an svn client to be able to access svnserve.

Subversion's svnserve listens on port 3690 (tcp/udp) by default and it should already be assgined to use that port in /etc/services.

Running svnserve as a stand-alone daemon process

To make our catpantscode repository as well as other future repositories to be created in this server, we'll need to run svnserve and limit it to run repositories listed on a certain path. To do this, run svnserve as show below:

jerome@pingu64:~$ svnserve -d -r /home/jerome

Since our catpantscode repository is under /home/jerome, it will now be available to svn-aware clients as:

svn://pingu64/catpantscode

pingu64 is the hostname of the machine where svnserve is running. It could also be a fully-qualified domain name or an IP address.

If you're using the subversion client from console, you can now checkout the catpantscode from a network(assuming it has already been configured and resolves):

jsg@barney:~$ svn checkout svn://pingu64.gametel.com/catpantscode chilicatcodes
A chilicatcodes/trunk
A chilicatcodes/trunk/README
A chilicatcodes/branches
A chilicatcodes/tags
Checked out revision 1.
jsg@barney:~$

If you're in a Windows system, make sure you download TortoiseSVN. If you're using Linux, you can either use the console-only client or download a graphical front-end like eSVN.

Built-in authentication and authorization of svnserve

Our svnserve also has built-in authentication and authorization when needed. This is especially useful when we need to limit access to the files and folders of the repositories. Inside the catpantscode folder, are two files that needs to be modified in order for this to work. These are svnserve.conf and passwd:

jerome@pingu64:~$ ls catpantscode/
conf dav db format hooks locks README.txt
jerome@pingu64:~$ cd conf
jerome@pingu64:~$ ls
authz passwd svnserve.conf

the svnserve.conf is the configuration file and is fairly simple to modify. To make your svnserve run as a daemon process with no read-only access and full write access to a few people, make sure the following lines are uncommented:

[general]
anon-access = none
auth-access = write
password-db = passwd
realm = The Catpants Source Code Repository

Save svnserve.conf. We did not remove the comment of the authz-db = authz line because this is a different setup for svnserve that allows for path-based access control. Using authz is beyond the scope of the current requirements for gametel so we'll skip this entirely.

The last file that needs to be edited is the passwd file to make it possible for svnserve.conf to work. The passwd file is referenced by the passwd-db line in svnserve.conf and contains a flat file of the users and their respective passwords. It is very simple and may look something like this:

[users]
harry = pantsonfire
sally = catonfire

Save the passwd file and you're all good to go.

Once these files and their respective entries have been added, restart the svnserve daemon and you'll be able to connect once again but now with tighter access control. Depending on your configuration, checking out, committing new code, merging, etc., may require user credentials.

Tools used for this tutorial

* Subversion 1.2 or higher
* eSVN - graphical svn client for Linux
* TortoiseSVN - graphical svn client for Windows

References

* http://subversion.tigris.org - Subversion homepage
* Version Control with Subversion - the authoritative reference for all things svn, published by O'Reilly Media.