Getting Started with Subversion

Subversion – The primary download is source code, but there are binary versions available for different operating systems, including Windows, Mac OS and most common flavours of Linux.

If you intend to use Subversion mostly from the command line, you might want to add the Subversion binaries directory to your Windows PATH variable.

You can think of a repository as a database where all the information about versioned files is stored. You can either create your repositories in lots of different folders, or select one folder and create all repositories within it. The second option is better if you want the same server to handle multiple projects.

Repositories can be created using the command line, or by using TortoiseSVN. The examples below show how to create "Repository4" in our example layout.

Subversion is based on a client/server model, where the server takes care of storing versioned files and keeping logs of what has changed.

There are two ways to run a subversion server. The first is to install it as a module on an Apache 2 server. If you already run a local web-server, this might be the best option for you.

The second method is to use svnserve, which comes with the main Subversion package. It's a simple command line tool, and is useful if you're only a single developer or if you don't want Apache running. There are different ways to run svnserve too, but we'll concentrate on using it as a "daemon" process. In other words, once it's started it will run quietly in the background.

You'll need to specify the folder which contains your repository (or repositories), and specify a run mode. You can also supply an optional port number, instead of the default one (3690).

The following command will run a server that will serve our repositories, and will listen on port 85.

svnserve --daemon --listen-port 85 --root "c:\repositories\"

To check if it's working, open up a web browser and navigate to 127.0.0.1:85 (or 127.0.0.1:3690 if you didn't specify a port number). You should see something like the following in your browser:

( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline svndiff1 absent-entries ) ) ) 

If you don't wish to set up a local server, you can use a professional subversion hosting service, such as wush.net or CVSDude. They take care of all of the server-side stuff, so you can concentrate on more fun jobs.

If you're intending to allow other people to access your repository, you may want to add password protection to stop unwanted guests. Thankfully this is quite easy if using svnserve, and it only takes a few steps.

1. Open up your repository folder, such as "Repository1". You should see several files and folders, including a folder called "conf"
2. Open the "conf" folder, open the file "svnserve.conf" in a text editor.
3. Find the line "# password-db = passwd" and remove the # at the beginning. Save and close.
4. Open up the "passwd" file in a text editor. This file will contain an unencrypted list of usernames and passwords. To add a new user, add the line "user = password" after [users].

Now that we have a repository set up and a server listening for our requests, it's time to add some files. There isn't a rigid format for Subversion repositories, but the recommended structure involves creating three folders: trunk, branches and tags.

• Trunk – All of your files will go in this folder. It represents the main part of the project that is being worked on.
• Branches – This is used to store alternative versions of the project for experimental purposes. For example, you can create a branch of your project to test a new map rendering component. Checking in files will go to the branch and not the trunk, so your work won't affect the main project. If the experiment works, you can then merge the branch with the main project.
• Tags – Use tags for storing a copy of the source at a particular milestone. For example, you could create a tags for version 1.0, 1.1 etc. This is useful for keeping track of changes, as well as making backups in case a bug creeps in.

To set up your repository with these folders, perform the following:

1. Create a new folder. For this example, we'll call it "c:\myproject".
2. Inside this new folder, create three new folders. One called trunk, one called branches and one called tags.
3. Optional step: Copy your project files into "trunk".

Once your folder scheme is set up, you're ready to import it into your repository. You can do this from the command line or using TortoiseSVN.

"Checking out" is often referred to as "creating a working copy". When you check files out of the repository, you create a copy of the files on your own machine. You can edit them freely without changing anything on the main server. When you've made the changes you wish and everything is working, you can check the files in, or "commit" them.

To check out via the command line, use something similar to:

svn checkout svn://127.0.0.1/Repository1/trunk/

This will check out the latest files from the trunk of Repository1. If you're using TortoiseSVN, right click and select "SVN Checkout" and enter the URL you wish to checkout from.

Checking-in is just as simple. To commit changes using the command line, navigate to the folder your working copy is stored in and enter:

svn commit --message "Why I made these changes"

The message is optional, but it's extremely useful to make a note of what was changed, and more importantly why it was changed. Nothing is more annoying than changing between two methods because you forgot why it was such a bad idea.

If you're using TortoiseSVN, right click and select "SVN Commit".

Tags are useful for creating a record of the source at a set release, such as version 1.0 of your project. A branch is used to create an offshoot of the project, such as testing a new algorithm.

The Subversion book is available online at http://svnbook.red-bean.com/, and it contains just about everything you'll ever need to know. There are some very powerful features, such as setting up scripts to run before and after a commit (useful for parsing comments to see if it was a bug fix).

Hopefully this article has given you all you need to set-up and use Subversion in your daily development work. It may seem like a lot of effort at the start, but it's an incredibly useful skill to learn, and even if you only use it as an extra safety net, it's worth the time to set up.