How To Setup Subversion

Subversion is a popular source control tool. It is free, open-source, and widely-used by popular project hosting sites such as Google and Sourceforge. But you can also use it to setup your own personal software repositories, which is valuable for medium-to-large programming projects, where you may want to avoid accidentally deleting or breaking code.

This tutorial assumes the user is running Mac OS X, which comes with Subversion installed. Presumably the technique described here is easily modified to work on other operating systems.

First, create a new subversion repository. While you can create a repository on your local disk (such as your laptop), in general it makes much more sense to create your repository on Stanford's servers, so the files are automatically backed up and accessible from anywhere.

You can create the repository anywhere in your home directory. For the examples in this tutorial, the Subversion repository is:

/afs/cs.stanford.edu/u/mbostock/svn

Obviously, you'll want to substitute "mbostock" for your own username. The repository is created using svnadmin on xenon:

cd ~
svnadmin create svn

The svn directory that is created should be considered private (as in, an implementation detail of the source control system); you should not edit any of the contained files manually, because you will be using Subversion to manage them.

Most likely, you'll want your repository to be private from a file-sharing perspective as well, so be sure to set the permissions appropriately using chmod. If you want to share a repository with other users (for example on a group project), you can always create another repository with shared access.

Say we have a directory foo in our local Documents folder that contains all the source files we want to protect with version control. First we make the project's parent folder our working directory, then we import the files recursively:

cd ~/Documents
svn import foo -m "Initial import" \
    svn+ssh://xenon.stanford.edu/afs/cs/u/mbostock/svn/foo

Note that the local directory structure and the repository directory structure don't have to match, though for sanity's sake it's a good idea for them to be similar. You can map a local directory to any directory in the source repository; you can even have multiple checked-out versions of projects if you wanted to. But for now, keep things simple by using the same hierarchy.

If you weren't careful, it's likely that some additional cruft was included in the initial import, like generated Java class files or emacs backup files. Don't worry; you can always delete these in a subsequent revision.

Now, the exciting part. You need to checkout a new working copy to replace the files you were previously working with locally (outside of course control). A safe way to do this is:

mv foo foo-old
svn checkout svn+ssh://xenon.stanford.edu/afs/cs/u/mbostock/svn/foo

Hooray! You can now make edits within source control. And fortunately, this is the last time you'll need to type out the full path to the repository over SSH; once you've checked out a working copy, Subversion internally keeps track of the corresponding repository's location.

Note that by default you will need to enter your password to run most svn commands. However, if you first run kinit to establish Kerberos credentials, you won't be repeatedly prompted for your password. (See How To Setup Kerberos if you have difficulty running kinit.)

Make changes to your files, and then submit:

svn checkin -m "Some new changes"

If you omit the -m parameter, svn will pop up your editor so that you can enter a longer description of the changes.

Sometimes you want to undo changes that are already committed. In this case, you can overwrite the checked-out version with the contents of an earlier version, and then check it back in again:

svn cat Foo.java@1 > Foo.java
svn ci -m "Reverting Foo.java to @1"

You can similarly use this technique to restore deleted files.

If you create a new file and then run svn ci, the new files won't be added to the source repository. You need to add them explicitly. For example, given a few file Bar.java:

svn add Bar.java
svn ci -m "Adding Bar.java"

Similarly, if you remove a file using rm, that file will not be removed from the repository during your next submit. In fact, the removed file will be restored if you run svn update. To delete the file locally and from the repository, use svn delete instead:

svn delete Bar.java
svn ci -m "Deleting Bar.java"