Subversion: Not Just for Code Anymore

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/