GrantPalin.com

Introduction

I’ve recently been reading about using Subversion to manage source code (and related assets) for different projects I have going now. It turns out that Subversion is powerful and flexible software to structure and maintain your versions without having to make extra copies of your files and folders for backup purposes. I had been meaning to install it and experiment with it before moving my projects into source control.

Recently at work, I helped install and configure a Subversion+Apache setup on one of our servers, dedicated at this point to one of our bigger ongoing projects. The process was an illuminating one, and so I proceeded to do a similar setup on my home desktop.

I got it working, but realized it was probably overkill for a few personal projects at home. It is a bit fiddly to get working properly, and you have to maintain a backup routine of your repositories, else you risk losing your revision history if your computer’s hard drive (or other similarly important component) dies. Did I go back to the old-fashioned way of doing backups? Oh no.

I’m going to cover the basics of setting up a Subversion repository on DreamHost, checking it out, and making additions and changes to the local copy. I will be writing more articles on Subversion usage and techniques in the future.

Hosted Subversion

After some more reading, it turns out that numerous web hosts and services provide Subversion hosting via the web. I am hosted on DreamHost, and one of the benefits of their hosting plan is (supposedly) unlimited repositories. So this would eliminate the majority of the setup and maintenance work, as well as handle the backup process. This is perfect for my needs right now. And I suspect it would be for many other people as well, at least until they they have specific needs.

So to start, log onto your DreamHost control panel, and navigate to the Goodies->Subversion page. On this page, you can create your hosted Subversion repositories.

The form is pretty straightforward, there is not too much to do here. I’ve shown an image above of how I filled out my form for the purpose of this tutorial (no the repository is not actually there, so don’t bother checking it).

Fill in your preferred settings and click “Create my new project repository now!”. You will have to wait a bit before the repository is accessible - you should receive an email from DreamHost when this is done. Then you can move on. Note that you can view the repository via your preferred web browser. Simply enter the URL you specified during the creation process. There’s not much to see now, since the repository was just created.

It is a good idea to have a subdomain dedicated to holding your repositories, although it isn’t necessary. You can access your repositories through a subdirectory of a domain if desired, but I decided to go the dedicated subdomain route. It keeps things a little more organized.

There are multiple ways you can use your repository. If you like the command line, that option is available. But there is a neat application for Windows called TortoiseSVN. It integrates into Windows Explorer, and adds some entries to the context menu (appears when the mouse is right-clicked). Also, there are icon overlays on files and folders within a working copy to indicate their versioning status.

Like Subversion itself, TortoiseSVN is free open-source software. You can download an installer from the TortoiseSVN website. Simply run the installer and follow the prompts to the end.

So you now have a repository set up, and a useful graphical interface to the repository…What next?

How to use it?

Navigate to a folder (create one if desired) in Windows Explorer, right-click the folder, and choose SVN Checkout... Enter the URL to your repository, and click OK. If prompted, enter the credentials you specified when creating the repository on DreamHost. Because the repository is currently empty, not much happens here. But you should see a little green and white check mark overlay on the folder you checked the repository into. Note that the folder you checked into is not itself part of the repository - it is just a container for the local copy.

Keep in mind that when you check out a repository to your computer, you have what is called a Working Copy, being that it is a local copy of the repository. Any changes will be performed on the working copy, and will eventually be sent back to the repository.

Once again, your repository is empty at this point, but you can easily start adding files. You can set up a folder hierarchy here too, if you wanted to. Subversion preserves folder structure. So, either by creating files in your checkout folder, or by copying in files from elsewhere, you can add them into Subversion with just one extra step.

Right-click on any file or folder, within your checkout folder, and choose TortoiseSVN->Add... You can select multiple files and folders on the same level, and add them all with one trip to the menu. Or they can be done one by one, if desired. When you add folders this way, any files and folders within are also added. You’ll be shown a list of files/folders being added, just click OK. You’ll then see a summary of what was added. Having done this, you’ll notice that the just-added items are overlaid with a blue cross icon. You files and folders are not in Subversion yet at this point! The blue cross is TortoiseSVN’s way of showing that you have marked files/folders that are to be added to your repository.

To actually add the added items to your repository, you should right-click your top-level folder (the one you checked your repository into a few steps previously) and click SVN Commit... You’ll see a listing of added files/folders. Type a message if you like. This is recorded by Subversion so you can keep track of what each commit was for. Then click OK. You should receive a success message. Also note that the blue cross icon overlays will have changed to the green check marks. The files and folders are now in Subversion.

You can, if preferred, commit just a bunch of files at a time, but that could get tedious, and it is best to commit a set of related changes/additions as a unit. You can do a commit on any sub folder within your working copy, and any files and folders within will be committed. And, of course, you can commit at the top level (as done above), where all pending commits are done at the same time.

Now suppose you make a change to one of your previously-committed files. That file’s icon will then have a red exclamation mark overlay, indicating that a versioned file has been changed. Also note that the containing folder, and successive containing folders up to the root of your working copy, if applicable, will also have the same overlays. This is a great visual indicator that something, somewhere, in your working copy, has been changed. As mentioned above, you can commit updated files individually, at a folder level, and at the root level of the working copy.

This goes to show that you can do what ever you like to your working copy, such as adding, deleting, or modifying files, without Subversion ever knowing about it. That is, until you do a commit. Then Subversion will know about your changes.

What if you want to eliminate a file or folder from the repository? Your first thought might be to just use Windows Explorer’s file deleting feature, but that would not tell Subversion of your intent! The relevant file/folder would still be in the repository. To really delete a file, right-click, and choose TortoiseSVN->Delete. The file will be deleted from Windows Explorer, AND TortoiseSVN will make a record of your action. The next time you do a commit, TortoiseSVN will include that file deletion record in the log file - it will be visible in the list. Note that after the commit is done, the file will still be in your repository in the previous revisions! It has just been removed at the current revision, and will not be included when moving forward.

You may notice folders named .svn, and set as hidden folders (they are visible if you configure Explorer to show hidden files and folders) throughout your local copy. This is so TortoiseSVN can keep track of the changes you make, and to update file status appropriately. If you delete those folders, updates and commits may not work properly.

Try visiting your repository via the web, using the same URL as you have been using to check out your working copy. You’ll see the version number increment with each commit. This number is based on number of commits to the repository, not the number of files committed (there’s a difference). You can navigate through the listings, and view the latest versions of your files.

That is the basics of setting up and using TortoiseSVN and Subversion. I will be writing more in the future on this subject, mainly as I figure things out myself.

Conclusion

So is it worth it?

Oh my yes.

Subversion (and source control in general) is a great thing to know and use. It simplifies the process of keeping track of code revisions, and allows you to roll back specific changes or to work on specific branches of the code base, and even tag known working revisions of code so they can quickly be located.

Having it hosted on the web is even better, as web-based repositories can be accessed from anywhere with internet access, which is great for distributed teams. This is evident in the web repository browsers for various popular open source projects, such as WordPress, and Subversion itself. Many other open source projects do this as well. Go to those sites, and you can get a full copy of the code in a specific branch or tag, or even from the trunk.

Anyways, if you are looking for a way to have your source code repositories to be easily accessible, web-based repositories are the way to go. And, as I mentioned earlier, there are numerous hosting services out there that make this easy for you. DreamHost is one, but there are many others as well.