Valhalla Island

Subversion is fantastic. If you’re working on a group project and not using it you’re insane, if you’re developing a solo project and not using it, you’re crazy. While it’s ideally suited to code, it makes sense to have any kind of project in version control, essays, design mockups, technical documents, theses, anything you can complete to a level and then make revisions to.

I won’t go into too much detail on what version control really is, you can read about it at Wikipedia. Basically it allows you to commit versions of information and then roll back to those if you screw up beyond command + Z’s functionality. Say you’re working on a report, 3000 words, you’re done and happy with it, a day later you decide to add a section which also involves changing existing parts, next day you want to remove it but there’s so many changes you wouldn’t know where to start re-modifying, you pull the previous revision out of Subversion, problem solved.

It may seem like an unlikely situation written out like that but it’s a common situation when adding features to software, you try to add a feature but end up breaking so many other parts you need to start over.

Subversion is at it’s most useful when working in teams but that’s also when it gets a little more complicated. It’s simpler and still has strong advantages for the individual user. For someone who’s never used the command line before Subversion can be a daunting prospect, especially for the OS X operator who’s graphical options are the unbelievably complicated, confusing and ugly svnX or the perpetual private beta Versions. I hear ToroiseSVN on Windows is extremely good but I’ve never personally used it. This how to covers how to setup and use subversion on your local computer and use it simply.

Much of this how to is taken from the brilliant Introduction to Subversion screencast by Clickable Bliss. It goes into much more detail than what I would and went over my head when I first watched it over a year ago. While it’s an introduction, it may make command line Subversion look even more daunting to the new user and it’s also good to have a text based tutorial for copy and pasting purposes.

1. Download and install Martin Ott’s Subversion package. This is simple, just like any other application with an installer, next your way through it.

2. Pick a place you want to store your repositories. I store mine in a directory called “Subversion” in the “Documents” directory. You might want to put them somewhere else, if so you’ll have to modify the paths throughout.

3. Now we want to create a repository, you should to this for each new project you want to control with Subversion. Open Terminal.app and type in this and press return:

   svnadmin create --fs-type fsfs ~/Documents/Subversion/projectname

4. Now you have to make an initial import of the project into Subversion, we’ll pretend it’s on the desktop but you can drill down to it wherever it is by changing the path. Type this into the terminal and press return:

   svn import ~/Desktop/projectname file:///Users/yourusername/Documents/Subversion/projectname/ -m "Initial import"

   The -m "Initial import" is us adding a message with the import so later we can tell what we did. I’ve also used an absolute path after file:/// because I’ve had errors when using relative paths.

5. Next we want to make a working copy, this is the copy of the files we’ll be doing additional work on, you can leave this in the same place and just go there to work on the files, like you already do or you can delete them when you’re done and just make a new working copy from Subversion whenever you need it. Run this command in the terminal:

   svn checkout file:///Users/yourusername/Documents/Subversion/projectname/ ~/Desktop/workingcopies/projectname

   ~/Desktop/workingcopies/projectname is the place where you want the working copies stored. I’ve put it on the desktop here but you can put it anywhere.

6. Now you’ll probably want to do some work on your documents, code, files, images, whatever.

7. With the Terminal still open we want to navigate to our working copy like this:

   cd ~/Desktop/workingcopies/projectname

8. Now it’s a good idea to run:

   svn status

   This will show you which files in your project have been modified, which have been deleted and which have been added.

9. If you’ve added, deleted moved or copied a file you have to tell Subversion about it with one of these commands:

   svn add file.txt

   svn delete file.txt

   svn copy file.txt /dir/file.txt

   svn move file.txt /dir/file.txt

   You can also use the move command to change the name of a file. If you’ve modified files and nothing more you won’t have to worry about this.

10. When you’re satisfied you’ve made another revision to your project and you want to log the changes you’ve made, run this command in the Terminal:

    svn commit -m "Description of the changes I made"

11. Your workflow should then loop around from steps 6–10. Making changes and then committing the changes to your subversion repository.

To roll back your working copy to a previous version you can run svn log to see your revision history along with your handy commit messages, you can then run svn update -r 5, the number after the -r being which revision you want to roll back to.

It’s a really quick and simple process once you get in the groove. I hope it helps people out on it’s own or at least acts as a good supplement to the Introduction to Subversion screencast.