Subversion: Not Just for Code Anymore

Here is a subversive way to handle multiple versions of your personal information instead of just versions of code.
Basics of Using Subversion

Now that you have Subversion set up, let's take a look at some of the basic commands you'll need to know. The basic command-line Subversion client program is called svn, and all of the client commands that you'll use are accessed through that program. To get a complete list of the commands that are available, you can run svn help. You can also run svn help [command] to get help on a particular command.

The first basic command that you need to know is svn add. When you create a new file in a working copy, Subversion doesn't add it to the repository automatically. That way, you can control what gets versioned. For example, it usually would be a waste of space to add an emacs scratch file to your repository. Using svn add is easy. You simply need to give it the names of any files or directories to be added, and they will be scheduled for addition to the repository, assuming they reside inside of a valid working copy. Note though, that I said “scheduled”. When you issue the svn add command, Subversion doesn't actually add the files to the repository yet. Instead, it schedules them to be added at the next commit. That way, you add multiple files with several svn add commands and still batch them together so that they are committed as a single revision, along with any already-versioned files that have been locally modified.

So what's a commit? Well, when you modify files inside a working copy, the data isn't sent to the repository automatically. You need to commit your changes to the repository with svn commit. The commit command performs the work of actually sending your local changes to the repository to create a new revision. Normally, if you're in the working copy, you can simply issue svn commit with no options, and it will recursively commit all changed files under your current directory. However, if you don't want to commit all of the local changes, you can specify only certain files by listing them on the command line.

Once a file has been added to the repository, it can be freely modified locally and Subversion automatically determines what changes have been made in order to send them to the repository when you perform a commit. There is a restriction though. You can't just copy, move or delete files with the standard cp, mv or rm commands. If you do, Subversion won't know about the change and will lose track of the file. Instead, you need to use the Subversion equivalents svn cp, svn mv and svn rm. Syntactically, they work about the same as the local versions that you're used to, but they also schedule their respective actions to be applied to the repository on the next commit.

To find out the current status of a file in your working copy, you can use svn status. The status command shows you information such as which files are not under version control, which files have been modified and which files are scheduled for addition. For instance, the following output shows two modified files and one that hasn't been added to the repository:

$ svn status
?         .GroceryList.txt.swp
M         Frogs.png
M         GroceryList.txt

You also can use the svn update command to update your working copy to the latest revision. If you're accessing only the Subversion repository from a single computer, updating isn't necessary. However, if files are being modified from multiple computers, you need to run svn update in your working copy to get any changes that have been committed from a different computer.


Now that I've explained the hard way of using Subversion to keep track of your files, let's take a look at autoversioning. When you use Apache as your Subversion repository server, it uses an extension of the WebDAV protocol for transferring files to and from the repository. An interesting side effect of this is that most operating systems can mount shared WebDAV directories as a network filesystem, much like Samba or NFS. That means you can mount a Subversion repository and directly access the files without needing to store them locally in a working copy. This can have several advantages that make it really nice for dealing with your personal files. For one, a new version is created every time a file is saved. That way, you have a complete save history of your files without worrying about whether you've done a commit recently. You also add files to the repository merely by creating them, and can do copies, moves or deletes with the standard filesystem commands. Furthermore, if you access your repository from multiple computers, you always know that you're accessing the most recent version without remembering to run svn update.

Of course, autoversioning does have its downsides. For one, it requires a reasonably fast network connection to the computer that's serving the repository, so it may not be practical for a laptop that's frequently used away from home; although if you have access to a network connection back to the server, it's always possible to copy files to your local hard drive, edit them and then copy them back to the repository. Another downside to autoversioning is that you can access only the most recent repository revision. If you want to access older revisions of files, you have to download them locally, which can be done either by checking out a directory at a specific revision:

$ svn checkout -r 1563 http://$MY_SERVER/docs/pics/



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Labels for certain important changes

Alvaro Arenas's picture


Good article. However, I was missing a little paragraph about labelling some important versions of a file. For example, I am trying to modify my grandmother’s cake receipt. I made some changes and I got a good receipt, but still I am not totally satisfied. I would like to save this version of the receipt with a label "good-enough" and continue trying. Can I do this? How do I do it?



Re: Labels for certain important changes

William Nagel's picture

Thanks, I'm glad you enjoyed the article.

Creating a "label" of a version of your file couldn't be easier. All you have to do is make a copy of the file and rename it to whatever you want. Subversion uses what it calls "cheap copies" when you make a copy of a file in the repository. Basically what that means is that it doesn't really make a copy of the file. Instead all it does is make a new entry under the new filename that points back to the revision of the original file from which it was created, which uses almost zero extra space on disk.

Assuming you are using WebDAV, you can do the copy by just copying the file as you would any other file and Subversion will "do the right thing" (don't create the copy by using Save As from the text editor though, as that will create a copy of the file's contents in the repository). On the other hand, if you're using a working copy of the repository you can do the copy from the command line using "svn copy" followed by "svn commit".

import syntax

padyer's picture

I think you need to use file:/// (3 /'s instead of 2) when not including a hostname.

Awesome article. I really want to try the webdav stuff.


Re: import syntax

William Nagel's picture

I think you need to use file:/// (3 /'s instead of 2) when not including a hostname.

You are correct. However if you look back at the article you'll notice that I use $HOME, which includes the leading slash so that file://$HOME will expand to file:///home/bill (with the correct number of /'s).

Awesome article. I really want to try the webdav stuff.

Thank you very much! I'm glad you enjoyed it and I with you luck with getting WebDAV going.