Ask SIPB - November 11, 2007

If you've used a computer for any length of time, you've undoubtedly wanted to have a backup of older version of the files you're working on. You may also have wanted to let multiple people edit a document and track the changes each has made. In this week's Ask SIPB, we'll discuss version control, the traditional solution to these two problems, and walk through using Subversion, a popular, modern version control system.

What is version control?

Version control is widely accepted as one of the top 5 things that have improved the productivity of computer programmers since the invention of computer programming. It's saved me many times by being able to find when and why I made a certain change in the past. Likewise, I've been burned when I refused to use it, came back several months later, and couldn't figure out what I had changed since then that made my code no longer work. If you've used "Save As" several times while making changes to a file, you already know the benefits of the most naive form of version control, and using a standard system will make you much happier and more productive.

All version control systems work by keeping a central database, known as a repository, that tracks the entire edit history of each file. Typically, the repository will only store the changed text (the diff) between each version, making it far more efficient than a complete backup of each version. The repository also stores the editor's name, the time, and a log message summarizing the changes. The repository is not supposed to be edited directly, only through version control commands. It should be located somewhere that all editors can access.

To edit a file under version control, you check out files from the repository, make your changes, and check in or commit the new version. You can continue to commit further changes from the same working copy, which contains your copy of the actual files in the repository. Also, you can check out an older revision to examine files at a previous state.

Why should I use Subversion?

Subversion (commonly abbreviated SVN) is one of the most popular version control systems today. It evolved from RCS (the Revision Control System), an early, simple version control system that kept a history of each file in a subdirectory called RCS. This works fine for documents with few (often just one) editors who have access to the same directory; in fact, "Ask SIPB" is still edited and proofread with the help of RCS. CVS, the Concurrent Versions System, was a major modification of RCS that added support for multiple independent editors, and is the system used in 6.170. Subversion is a newer system, inspired by CVS, that addresses many of ts deficiencies by starting from scratch and rewriting some issues that CVS could not work around. For example, Subversion tracks new and removed directories and renamed files in addition to just file contents, a notable missing feature in CVS.

This column will provide a quick introduction on how to set up Subversion for use from Athena. For an excellent reference on the details of Subversion, check out the online Subversion book at svnbook.red-bean.com.

How do I get started with Subversion on Athena?

All contributors will need to add the svn locker, both for the current session and for future logins. You can do this by typing add svn, and placing that command in the .environment file in your home directory.

To create your repository, run

athena% svnadmin create --fs-type fsfs /mit/joeuser/myproject-repo
athena% athrun consult fsr sa /mit/joeuser/myproject-repo user1 write user2 write
athena% svn mkdir file:///mit/joeuser/myproject-repo/trunk -m trunk
Replace user1, user2, etc. with the usernames of people who should be able to contribute to the project, and /mit/joeuser/myproject-repo with the path to some (new) directory in your locker. This will store the repository, not the working copy.

The last line will create a directory called trunk, with a terse commit message of "trunk". Traditionally, all files in the project are stored within the trunk. This allows you to later create branches (work on the project that is experimental or otherwise should not yet go in the trunk) or tags (checkpoints of the project at a certain state) outside of the trunk.

Each contributor can now check out the repository with

athena% mkdir project
athena% cd project
athena% svn co file:///mit/joeuser/myproject-repo/trunk

How do I check files in and out?

First, cd to the trunk directory you just checked out, and run svn update to ensure that you have the latest working copy. Add or edit files as usual. If you've added a file, run svn add filename to make sure it goes into the repository. Then, run the command svn commit (aka svn ci) to commit your changes. This will bring up an editor, by default Emacs, to record a log message. You should give a descriptive summary of your changes so others will know what you did. (If you're not familiar with Emacs, you can hit Ctrl-X Ctrl-C to save and quit.)

Can I retrieve an older version of my files?

You can look at the history of any specific file with the command svn log filename. Once you've identified the revision, you can add the -r flag to the svn update command:
athena% svn update -r10 Foo.java
U Foo.java
Updated to revision 10.
If you just want to see the difference between two versions, you can use the svn diff command. Like svn update, give it the revision flag and the name of the file. If you want to diff between two old revisions, rather than your working copy and an old revision, use syntax such as svn diff -r10:22. Both svn update and svn diff will operate on the entire directory if you do not give them a filename.

Can I use Subversion on Windows?

Yes. You can use TortoiseSVN (tortoisesvn.tigris.org) to add SVN support to the Windows Explorer. All Subversion operations become part of the standard right-click menu, so you can select files to check in, diff, etc. Files in version control will also gain little overlay icons, such as a green check, mark indicating whether they're up to date or have been modified. TortoiseSVN is good if you're trying to start using Subversion with your regular documents.

Another popular option is the Subclipse plugin to Eclipse (subclipse.tigris.org). Eclipse is commonly used for development in Java and other languages. Once you have Subclipse installed, you may need to change the default interface (in Preferences | Team | SVN) to JavaSVN in order for it to work with SSH. Then you can run File | Import to import an existing project from SVN.

In both of these cases, you'll need to use svn+ssh access on your repository, since you probably don't have AFS installed. Specify the repository as, e.g., svn+ssh://athena.dialup.mit.edu/afs/athena/user/j/o/joeuser/myproject-repo.


To ask us a question, send email to sipb@mit.edu. We'll try to answer you quickly, and we can address your question in our next column. You can also stop by our office in W20-557 or call us at x3-7788 if you need help. Copies of each column and pointers to additional information are posted on our website: http://www.mit.edu/~asksipb/