SVN 101

Subversion is one of the most powerful open-source version control systems available on the net, but it can often be intimidating for new users to get to grips with. Find out how, and more importantly why you should use Subversion in this tutorial.

Why Subversion?

We all know the scenario. You've been painlessly coding away at a file for ages. You make a last minute change to that uber-special design that's been eating away at your social time. You update that tiring documentation you've been forced to write.

Then comes the horrible bit. You're excited, possibly nervous. You save-as, navigate to the desired directory. Then reality bites. Filtering through hundreds of folders, deciphering the cryptic, confusing file names – suffixed with enough question marks and scary titles to make David Blain look timid.

It's all such a mess.

This is where Subversion steps in. Subversion, or SVN is a powerful version control system which makes it really easy to organize your workflow and work on collaborative projects simply and easily. Gone are the days of version headaches and deathly file names. SVN clears your head and allows you to focus on the project at hand.

Installing

Installing Subversion, on whatever platform of your choosing is a really easy process. If you are using Mac OS 10.5+, you can skip this step as Subversion is already installed, and it may be on other platforms.

If you are running linux, or a similar *NIX based system, the following command should work (replace

apt-get

with your package manager):

sudo apt-get install svn

This should download, compile and install Subversion onto your system. If you are running windows, you can get the latest binaries from here. Download the installer, run and SVN should be installed on your system!

To check that SVN is installed and working, run this simple command at the shell:

svn help

If everything is successful, you should get an output similar to the following:

Lingo

I'm gonna be using some terms and phrases specific to Subversion throughout this tutorial, so here is a quick glossary to make sure you can understand any terms you may come across.

  • Repository (or repo) – the location on the server (accessible by SVN) where files are stored;
  • Commit – when you send changes on your local copy of the repo to the remote repo;
  • Checkout – creating a local copy of the repository;

Checking out

In SVN, when you want to access the files in the repository, you need to check out the remote repository, and you are essentially creating a copy of the remote repo. Checking out a repository is really easy, you just have to know the URL (which will be found on many 'download' pages on sites, or under the 'Source' tab in Google Code). For this example, we will be using the SVN repository of Wordpress, a popular open source blogging system.

The URL for the Wordpress repo is http://svn.automattic.com/wordpress/trunk/, so you'll need to copy that (or remember it).

Open a terminal window, and type the following command:

svn checkout http://svn.automattic.com/wordpress/trunk/
/PATH/TO/YOUR/HTDOCS/SITES/DIRECTORY

Obviously you need to replace the /PATH/TO/YOUR/HTDOCS/SITES/DIRECTORY with the path to the directory you want to check out the source to, and hit enter. This should show lots of files being downloaded.

After this process is finished, navigate to the directory that you typed and you will see the entire Wordpress system! Well that was easy!

Creating Your Own Repo

As we can't make changes to the Wordpress repository, we are going to need to create our own repository so that we can commit, and test about with SVN's other features.

To create a SVN repository you can use the svnadmin command line tool. Open a terminal, navigate to the directory you want to open the repo in, and run the following command:

svnadmin create .

And that has created our repository on our machine. Please bear in mind this won't actually work from remote machines as you will have to configure a firewall, open network sockets and a lot of other stuff and this is outside the scope of this tutorial. However, we can still access it on our local network.

Adding Files and Committing

Firstly, checkout your newly created repository by running the following command:

svn checkout 127.0.0.1 .

…and create some blank text files, some images and some other files/directories in the local copy. Add them all by running this command:

svn add .

This should add the entire directory, but then you need to commit that to the repository to see any changes reflected across the network of checked out repos. You can commit it using the commit function, and optionally add a message using the -m operator:

svn commit -m "Added lots of files for tutorial"

This should then upload the files to the repository.

Updating and Changing

You can now make certain changes to the files in your local copy and subversion will intelligently pick up the changes and update only the new files when you next commit. The same works with updating.

Commit again by running the svn commit function again. This will then upload the files to the repository and

Updating a repository is easily done with the update command. This will query the Subversion repo and find out what new files have been updated, and then update them! This saves your computer downloading the entire repository in one go – especially with big repositories such as wordpress this can be really helpful.

The command's syntax is so:

svn update

And the system will do the rest.

Updating

Rolling Back

This is where SVN really starts to get useful. You have full control over your commits, and the Subversion server keeps a history of what changed between each commit, allowing you to “roll back” to a previous version if something goes wrong.

Like everything else in SVN, rolling back requires one command:

svn merge -c -REVISION_NUMBER

Simply call merge and enter a previous version number and it will roll back to that version.

Differences

Another great thing about SVN is that you can easily see what differences there are between the current version on your local, and the most recent version on the repo – allowing you to look at the changes between revisions.

To do this, you can run the diff command:

svn diff

Differences

That's all, folks!

So, hopefully you will have learned the basic idea of how to use Subversion. A definitive guide to SVN – The Subversion Book – is free to read online and highly recommended.


31

Comments
  • Awesome! Exactly what I needed now! But how about a video tutorial on how to use this on a regular basis?

  • Thanks a lot for putting this together. I have been wanting to get started with SVN for a while now and didn’t really know where to start. This will be really helpful and will finally get me into version control mode…

  • I have been using SVN for many years now but lately am hearing that GIT is the next thing. Would be greatful for such a post!

  • Meshach says:

    Awesome! Thanks.

  • sven says:

    for mac os x users i’d recommend to upgrade to version 1.5 of subversion using the macports.
    Since subversion 1.5 performance is a lot better.

  • Nathan says:

    Tortoise SVN is a must for Windows users. It’s a shell extension that makes all commands extremely easy and intuitive.

    http://tortoisesvn.tigris.org/

  • shin says:

    I am not sure which one I need to install for my laptop which is vista.
    I get http://www.collab.net/downloads/subversion/ and there are three kinds,
    1. CollabNet Subversion Server and Client v1.5.5 (for Windows),
    2. CollabNet Subversion Command-Line Client v1.5.5 (for Windows) and
    3. CollabNet Subversion Source Code v1.5.5 (for Windows).

    Can anyone help me which one I need to install?
    Thanks.

  • Geno says:

    @Shin – I’m getting the first version – Server and Client

    I’m probably going to install the server onto my main server and just keep the client for my laptop.

    If you don’t have a dedicated server, you should be able to install both, the client and server on your laptop.

  • Use SVN on a daily basis, would definitely recommend it in conjunction with Trac for development

  • Wassim says:

    @shin: If you’d like to access an SVN repository I recommend you to just install TortoiseCVS which let you do that directly from Windows Explorer.

  • Wassim says:

    @shin: If you need to setup an SVN repository you need actually to install an SVN Server, CollabNet Subversion Server and Client package gives you that. Also, there’s a difference between Shared Repository which needs an SVN server, and a Local SVN Repository which you can create with a simple SVN client software like TortoiseCVS.

    Hope that helps shin :-)

  • Ignacio says:

    I use Versions for Mac. http://www.versionsapp.com, great soft.

  • Great! A 101 for svn+trac would be interesting.

  • Coda has very nice Subversion integration, although I don’t use it too often anymore. The other thing I noticed is that you refer to Subversion and SVN as the same thing. I’m pretty sure that Subversion is the main software framework and SVN is the command-line interface used to interact with it. SVN isn’t always necessary to use Subversion, if you have a capable Subversion desktop client, you can work directly from that without using the command line.

    I may be wrong.

    Anyway, this is a great intro for beginners. Thanks!

  • M.A.Yoosuf says:

    @Christopher Francis O’Donnell, why only coda, Dreamweaver and rest of non Microsoft product has the SVN feature.

    @All, there is a Free SVN client. thats Tortoise SVN, try it, got so-many features

    http://tortoisesvn.tigris.org/

    M.A.Yoosuf

  • Nic says:

    Very useful, thanks!

  • Dean says:

    What would you recommend for people who develop using shared hosting accounts on Linux servers and don’t have (or want) shell access?

  • Wassim says:

    @Dean: You don’t have to issue commands via the commands line to access and manage files in any SVN repo; any SVN client will do the job for you; and there’s of SVN Client Software out there. I don’t know if that answers your question but hope that helps :-)

  • Wassim says:

    @Dean: You don’t have to issue commands via the command line to access and manage files in any SVN repo; any SVN client will do the job for you; and there’s plenty of SVN Client Software out there. I don’t know if that answers your question but hope that helps :-)

  • A popular new alternative is Dropbox. It’s alot like SVN, except rather then creating repositories that anyone can access with the address, you share the folders with other Dropbox users. There’s linux, osx, and window versions. Not exactly useful for uploading files to servers, but it integrates straight into the file explorer (aka finder, nautilus, etc) and is more useful for in-house or team collaborations, as well as off site backups. (it uses the Dropbox servers for file storage, which is really the Amazon S3 repository.)

  • shin says:

    Thanks Wassim and Geno for your help.

  • A Hassan says:

    kewl dude!

  • Tom says:

    Pretty disappointed by this article. Very basic, discussed how to get it running, which isn’t a mammoth task providing you are reasonably tech savvy (we are developers/designers after all aren’t we?), and a few commands. Didn’t explain the larger concepts of it thoroughly enough for it to be of any use really.

    It may have been the authors intention to provide a brief introduction to SVN and it’s uses, in which case the title should not have been ‘SVN 101′.

  • I’ve had no luck using the graphical tools for Windows to upload my Wordpress plugins to their repository. All of the tutorials I’ve seen point to command line utilities, but I haven’t see where to download those. I’m going to try out your tutorial here to see if that works for my needs. Thanks for the great articles on your site.

  • Ram says:

    I get an error when I try to check out my local repository

    svn co 127.0.0.1 .
    svn: ‘127.0.0.1′ does not appear to be a URL

    also what if I want to use local repository for more than one project? do I use svnadmin to create a repo for each one or use the same repo and have multiple folders?

  • sefat says:

    Im on a windows machine and using Wamp server..this process didnt quite work for me…!!:(
    A video tutorial might help..!

  • petri says:

    GIT is the better way to go in so many ways. It’s faster than SVN and a lot smarter too.

    http://git-scm.com/

  • (zoe) says:

    I definitely have to write tutorial: GIT for web designers.
    Guys I’m sorry, but SVN sucks.

  • Sumesh says:

    That’s a useful tutorial, I’ve been a bit messed up with dozens of file variations in my WP themes and such (sidebar.php, sidebar_withads.php, sidebar_withtabs.php, you get the point….).

    There are GUI SVN apps for OSX, I believe, what are the disadvantages (if any) of using them over learning to do it manually over the CLI?

  • Awesome! I was looking forward such a tutorial for a long time.

    Thank you very much!

  • sasdaman says:

    A video tutorial is desperately needed for a fairly complex install. I’m also using WAMP Server. Has anyone had any joy installing on WAMP!?