gods wear hats

I’ve started working on some projects with a bunch of guys who are not used to using version control systems. This post is as much for them as it is for anyone else. I won’t go into how to install subversion, because that is covered by many other people elsewhere. I also don’t touch on how to administer subversion for the same reason. This simple guide is purely for how to be a subversion user. It assumes that you know how to access and use a Unix command line. There are GUIs out there for handling these activities, but I’m working from the perspective that (a) “In the beginning was the command line…” and (b) the principle is the same regardless of the interface.

Getting started

If you are about to use subversion, your administrator has probably given you a URL for your repository. This could have a number of forms, but for our purposes they can all be treated identically - I’m going to use the fictitious URL http://example.com/svn/repo/trunk/project. The repository (as you probably know) is just a central store for all the files for a given project, along with version information. The first thing you’ll do is create a working copy of the repository on your computer.


svn co http://example.com/svn/repo/trunk/next_big_thing


Subversion will spit out some information about what it’s doing - ignore that for now. What’s happening here? It’s very simple.svn is the subversion command line application. The co command is short for checkout, which tells subversion to go the URL supplied and bring back a copy of the latest version of what’s there. This will create a directory (or folder if you prefer that term) with the same name as the bit after the last / of the URL - in this example: next_big_thing. That next_big_thing directory is your working copy of the repository.

Everyone who works on the Next Big Thing project will need to perform this same sort of checkout to their local computer. What lives in a working copy? Any sorts of files that you like: documents, source code, images, etc.

Editing and changing your working copy

Go ahead and fiddle with stuff in your working copy - you can do anything you like because none of it will affect anyone else until you commit your changes back to the repository. Put some files into the directory, edit what’s already there, delete some as well - you can get it all back the way it was very easily. But first, let’s take a look at what’s changed (yes, that means you actually do have to go and change some things in your working copy: go on, I’ll go get a cup of coffee while you’re doing that … ready? OK, good). Run this command (from within your working copy - anywhere will do, but the top-level folder is best):

svn status

You should see a list of the changes you’ve made, with one of three characters beside them. Don’t worry about anything else that is spat out at this point (if anything).

? foo.txt - a file you’ve added that subversion doesn’t know about (yet)
M bar.txt - a file you’ve changed (M stands for merge, which is what happens to this file if you commit your changes)
! baz.txt - a file you’ve deleted

Adding files to a repository

You’ve put some files into your working copy, but there’s another step that needs to happen before they can be committed to the central repository.

svn add mynewfile.txt

Naturally, you substitute “mynewfile.txt” for the name of your actual file. This tells subversion that you want to add the file to the repository the next time that you perform a commit (which we’ll get to in a moment). Why is this step necessary? There are any number of reasons why you wouldn’t want to automatically commit any file in your repository. The most common is probably that many programs create backup or temporary copies of files in a directory while you’re working on them - it wouldn’t be good to clutter up the repository with cruft. Subversion itself creates temporary files when there’s a conflict (yes, even in version control there is conflict - I may do another guide on how to deal with that).

Likewise, to delete a file you need to use:

svn delete myoldfile.txt

otherwise subversion gets confused. When you use add and delete, you’ll get a different status beside your file when you run that command - it’ll be A and D respectively (instead of the ? and ! that we saw above).

Holy crap! I didn’t want to do that!

As I mentioned above, it’s easy to get things back the way they were. If you want to back out any changes you’ve made to the whole project, do this in the top-level directory:

svn revert

You can also use svn revert myfile.txt to revert individual files (or directories).

Committing to the repository, and getting updates

So, now you’ve made all the changes you want to make, it’s time to commit them back to the central repository. This is where all the actual version control magic actually happens. Run this command from the top-level directory of your working copy:

svn commit

The first thing that will happen here is that a text editor will start up (usually vi). Enter a comment describing your change and then save and exit (in vi that means typing ZZ in command mode).

This will take all the changes you’ve made and upload them into the repository, commented with what you wrote. Now the next time someone runs svn co ... all your changes will be visible to them. If someone else has also committed some changes, you can get the latest version with (from the top-level directory):

svn update

You will probably need to run the update command before you do a commit so that you have the latest version of the repository before trying to change it. Any time you (or anyone else) runs svn commit, the version number of the repository goes up by one. In this way, it’s easy to tell the state of every file in the repository at any particular point in the repository’s history, and it’s how you avoid having one person overwrite all (or worse: some) of the work done by someone else.

What’s changed?

You can see the changes that people have made by using

svn log

Be careful with running this in the top-level directory of your working copy - you’ll get every commit message for the project since the first revision. Usually this is run on an individual file to see the history of that file.

And I’m spent …

That’s it - you now know the absolute basics of subversion. For more detail, I suggest reading the online Subversion Book. Any questions, comments or inaccuracies can be sent my way.