Setting Up Subversion for Development on Windows

Introducing Subversion

When developing web applications on your own, a common challenge is keeping track of your changes. Mature version control systems make it easier to manage development as projects increase in size and complexity. In this tutorial, I’ll show you how to set up Subversion on a Windows machine and get started with a simple project.

Subversion, or SVN, is a stable version control system designed for maintaining versions over files. As a very mature project, having started in 2000, Subversion is the generally accepted standard for managing versions of files in software projects. A number of plugins and interfaces are available for Subversion; for example, the Eclipse IDE has near-seamless integration with Subversion through the Subclipse plugin. While a number of newer version control systems, known as distributed version control systems, are better suited for managing a team of distributed developers, Subversion remains the standard for ease of installation and use in single developer environments.

Why use a version control system?

When developing software individually, development processes are often very experimental. For example, one might put together some mock-ups of a feature to explore if it can be implemented. Problems arise when changes cause existing code to break, and it is often easier to start over with the “last good” version – but how do we keep track of these versions? This brings us to the core role of version control in single user environments: maintaining copies of files and the changes made to them, usually in such a way that they can easily be restored as the need arises. A version control system can monitor changes to a file over time, and quickly reset all copies of a file back to an earlier state.

There are a number of additional benefits to version control systems such as Subversion. For example, projects can be “forked” or “branched” on demand – that is, major changes can be made in a copy of the project code independent of the main working copy (the “trunk”) and merged back later. Complex projects can benefit considerably from this feature, allowing developers to make non-destructive changes to their codebase knowing that they can easily revert to a stable version or merge changes almost seamlessly.

Subversion 101

Subversion works around repositories, or complex data stores holding all the versioning information about a codebase. Repositories are simply file structures on disk, and can be interfaced through an SVN server. SVN servers provide a layer on top of these repositories, serving to both expose the repository to the world – e.g. over a network – and to maintain access controls over the repository. Once we have an account with the server that has access to a particular repository, we can then get started with versioning our software project.

We start by importing the existing codebase into the repostiory, from the latest “HEAD” revision. As we make changes, we commit them to the repository. For each of the files that has changed, a new version is stored in the repository, and a new revision is created. A local data store with some meta data about the repository (and spare copies of files) is updated. These data stores are found in hidden .svn directories, which you may notice around your filesystem. Subversion doesn’t usually touch your local copies of files when making commits, it simply records some information in the .svn directories.

For more information on Subversion, have a look through the book Version Control with Subversion, available free online thanks to O’Reilly.

Setting up a Subversion server on Windows

We have a number of options for installing an SVN server under Windows. One of them involves integrating with Apache, which offers some advantages in terms of integration with existing files. However, it requires some additional configuration – and, of course, a working install of Apache. Instead, we’re going to use an easy to use server package endorsed by Collabnet, the company behind Subversion. The VisualSVN Server allows us to quickly install a Subversion server just like any other application under Windows, then manage it via a familiar interface – a snap-in for the MS Management Console (mmc).

Installing the server

Head over to the download page of VisualSVN Server and grab the latest copy; I’m working with 1.5. Run through the install procedure till you see this screen:

You can leave these settings as they are, and you can always change them after installation, but it’s worth giving them some thought at this point.

There are two options you may consider for configuration; the first is repository location. If your projects tend to grow in size, and you typically store code on a seperate partition as a result, you may wish to choose a different drive for your repositories as well. This can also help manage backups; you can backup your repositories just by making a copy of the server’s repository folder. If you regularly backup a particular partition, placing your repositories there is always a good idea.

The second consideration is authentication method. We’ll be using simple Subversion authentication here. However, if you will only ever access your repositories locally via your Windows machine, you may find it easier to use Windows authentication. In this case, when you login to the server to make code changes, you can use your existing login credentials for the local machine.

Once these two options are out of the way, continue with the installation process till the end.

Creating our first repository

Once VisualSVN Server is installed, open up the server manager. If this doesn’t happen automatically after the install process, you can find it in your Start menu under “VisualSVN”. You should see something like this:

VisualSVN Server Manager

The server management interface is simply a snap-in for the standard Microsoft Management Console; the interface will be quite familiar if you’ve delved into the administrative tools on your Windows machine.

Your interface will be slightly different, as we haven’t yet setup any repositories – so let’s create one now! Click “Create new repository…”, name our new repository “test” and click OK.

Creating a new repository

By creating the “default structure”, the server will create three folders in our repository: trunk, branches and tags. These are designed to organise your code more effectively. Your main working copy is always stored in the trunk, while forking your project for major experimental changes is generally done by creating a new folder under branches. When you reach a stable version of your project, ready for release or just internal use, you can store that state in a “tag” so that you can easily recreate a copy of the code at a particular milestone when needed.

We’ll also need to create a new user so that we can access the repository. Head back to the main server management page and create a new user named “test”. (If you chose to use Windows authentication, you can skip this step.)

Creating a user for our SVN server

Now, we have an SVN repository ready to go!

Working with Subversion

To manage our code using our SVN server, we’re going to need a client. One of the most popular clients for Windows, which we’ll be using today, is TortoiseSVN. Tortoise integrates well with the Windows shell: we’ll generally be using it through the right-click context menu in Windows Explorer. Tortoise is fairly transparent, integrating cleanly while providing helpful information all over your project. It also works out of the box with IDEs that provide access to the shell menu, such as PhpED.

Download the latest copy of TortoiseSVN from the project page – I’m using v1.5.0. Install it with all the default options.

Importing our project into the repository

We’ll use TortoiseSVN to place a particular folder under version control. Let’s create a sample project with a PHP script in it. I’m storing my project in C:projectshelloworld with an index.php file inside, although it doesn’t matter where you store your project or what files are inside it.

Load up a Windows Explorer window and navigate to the folder above your project folder – for example, C:projects. Right-click on your project folder – e.g. helloworld – and select TortoiseSVN > Import.

Importing existing code into our repositorty

Importing the folder will place its contents into our SVN repository – we just need to tell it which SVN repository. Head back to your VisualSVN Server Manager, select ‘Repositories’ from the tree on the left and click on our new test repository. This will allow you to view the contents of your repository – currently, it only holds the three default folders. We’re after the URL to the repository, which will depend on your computer name / hostname and the port you chose during installation. In a gray bar above the repository browser, VisualSVN will state the name of the repository and its URL. To save an extra step, right click on the repository in the tree and select “Copy URL to clipboard”:

Identifying the URL of our repository

Then head back to your import dialog, add “trunk” to the end of the URL and hit “OK”:

Importing into our SVN repository

Remember to enter the username and password we set earlier. You’ll see a confirmation dialog, including a note that we’re currently at revision #2. Next, we checkout from the repository to that same folder, so that we have a copy that is offically under version control. You can do this with the right click menu again – right click on “helloworld”, and click “SVN Checkout”. The default settings in this dialog are all fine, except the “Checkout directory” – you may need to remove a “test” from the end. This is automatically added when your folder name is not the same as your repository name. Your Checkout dialog should be similar to this:

Checking out our project from the repository

Hit “OK”, allow TortoiseSVN to overwrite the contents of the directory, and we’re ready to go. The folder will now have a green tick icon on its thumbnail, showing that it is under version control and is at the latest version.

Handling updates

Let’s make some changes to our project files. We’re going to add a line to the source file in our project folder, as well as create an empty file called empty.txt in the same folder. When we want to save the current state of our code in the SVN repository, we commit the changes to the repository. When we’ve made these changes, the icon overlays on the file thumbnails will show us that our files are not at the latest version:

Icon overlays on modified files using Tortoise

The question mark icon on “empty.txt” shows that the file is not versioned – as it’s new – and so SVN doesn’t know what to do with it. The red icon on index.php indicates changes have been made and the file is not the same as the latest in the version control. Right click anywhere in the folder and select “SVN Commit”. We can now enter a human-readable summary message identifying what changes have been made, and select any new files that need to be versioned. Make sure you check the box next to your new file so that it is entered into the repository:

Selecting options for our SVN commit