Subversion for Beginners

I mentioned previously that I wanted to post how Subversion works (on the surface, for beginners) and how I use it for my development needs.

To create my WordPress plugins, Simpler iPaper and Simpler CSS, using SVN has been a must; after all, the only way to release new versions of the plugins is through SVN. I also keep this site’s WordPress installation up-to-date on the development version using Subversion. Additionally, in my current efforts to develop a working solution for HDTV’s in business and organizational settings, Display UI is being developed using Subversion for version control.

You get the idea. I use it on a daily basis, and for practical purposes. I don’t claim to understand the fine details, but hopefully this post gives you an idea of how I use it and how you can, too.

So what is version control? Simply put, it’s a way of keeping track of the changes made to files. It’s often impractical to make manual backups of a file before every set of changes to it, so version control systems like CVS and SVN emerged to help people — especially developers and programmers — keep track of their files, share changes with team members, and prevent stupid mistakes.

Accidentally deleted your code? Revert your changes. Came up with an ingenious way (that works) to do something? Commit your changes. Need to get the latest revision of all the files? Update the working copy.

Perhaps the most practical application of systems like Subversion is in team development. When three or more people are working on the same set of files, it’s useful to be able to merge the changes seamlessly, see the changes others have made, or even work separately on branches (kind of like forks) and tags (usually released versions that are being maintained).

I did write that I don’t claim to understand the fine details. If you really want to understand Subversion, I highly recommend this book by members of the development team: Version Control with Subversion, or the book online.

Let’s talk about how to use it. Hard-core programmers often choose to use the command line tools, where they type commands like svn up to update the files. Beginners will be glad to know that there are implementations with GUI‘s, like RapidSVN and TortoiseSVN. Eclipse users may use Subversive or Subclipse, “team providers” that let coders easily perform version control tasks inside the IDE.

Assuming that you’re using the command line binaries — which you can get from the Subversion site, and I recommend official CollabNet builds where possible — most of the basic tasks are rather easy.

Instead of right-clicking and picking options from a menu, tasks are done by typing commands.

First of all, a ‘repository’ is a hosted location containing all of the code, revisions and metadata. Often, one can access a repository via HTTP, as in the case of WordPress, which is found at http://core.svn.wordpress.org/ .

To ‘checkout’ a repository means to make a local copy (known as a ‘working copy’) of the contents. That’s what we have to do first when working with an established project: get the code from the repository.

To do so, type the following at an open shell (on Linux/Mac OS X) or command prompt: (don’t type the ‘$’ — that’s just a placeholder for the prompt you’ll see, such as frederick@ubuntu-pc:~# or [frederick@fedora-vm Desktop]$ — the specific prompt will differ depending on your machine and platform)

$ svn checkout http://core.svn.wordpress.org/trunk/ wordpress/

Windows users would do the same, but at a command prompt — again, without the dollar sign.

That command invokes the svn executable and tells it to checkout the WordPress trunk directory to the local folder wordpress.

Once you’ve done that, you’ve got a working copy, which you can update to the latest at any time after making sure your current directory is the working copy

$ cd wordpress
$ svn update

svn update can be shortened to svn up.

Now go ahead and delete the index.php file in the working copy. It’s conceivable that one might accidentally do this at some point. (On Linux/Mac OS X, one would type rm index.php, whereas on Windows, the del command is used instead.)

No worries. You have an option here: revert or update. Reverting will simply undo your local changes to the last downloaded revision, while updating will fetch the newest version of the deleted index.php file from the repository. Go ahead, get it back!

$ svn revert index.php

What about making some changes to the files and committing them to the repository? In these examples, we’ve been using WordPress, to which anonymous users don’t have write access. I’ll still show you how a change is committed, regardless.

After making your change, type the following (where filename is, obviously, the actual filename).

$ svn commit filename

This usually opens up the system default editor (often vim or nano on Unix systems), into which one enters a log message; that’s used as the log message when you save and quit the editor. In case you’re on Windows or some weird Linux distribution, this might not work for you, so you’ll have to specify another flag.

$ svn commit --message="Change summary" filename
Sending filename
Transmitting file data .
Committed revision 1234.

(Here the dollar sign, the placeholder for the prompt, is useful to indicate lines of user input vs. lines of output — the second to fourth lines are output, without the dollar sign.)

By this point you’ve done the most common tasks with Subversion: committing and updating. What about adding new files to the repository? After all, you’ll have to do that at some point.

After, for example, creating the file asdf.txt inside the working copy, we only need to make Subversion aware of its existence. Type the following command, and you’ll get the desired result.

$ svn add asdf.txt
A asdf.txt

To remove the file, it’s best that the removal is done through the Subversion executable, since it needs to keep track of all the files and could be confused if it can’t find the file. (Here I’m using the --force flag because the change hasn’t been committed.)

$ svn rm --force asdf.txt
D asdf.txt

That’s as much as most beginners need to know about Subversion. Of course, I make use of properties all the time, occasionally tag releases, and sometimes lock and unlock files.

If you want to learn more about the specifics of Subversion, try reading the book I mentioned online. It’s an excellent resource, and can be complemented by other books such as Practical Subversion, Second Edition.

… that was a long post. I hope it enriched your knowledge.