Using Subversion at CSAIL

What is Subversion?

Subversion, or svn, is a version control system which intelligently tracks and combines changes made across many files (usually text files) by many collaborators (or sometimes a single person). The master database of all files and changes is called the repository. Viewing and modifying files can only be done from working copies that are checked out from the repository.

CSAIL's subversion server provides:
  • tested and maintained version of subversion (As of Feb. 2011: 1.5.1 with debian patches and security fixes)
  • svn+ssh:// access, allowing you to share your repository with other CSAIL accountholders
  • https:// (WebDAV?) access, allowing you to share your repository with collaborators outside CSAIL
  • a stable, single location for "hooks" that run on checkout or checkin, allowing automatic emails to be generated on each checkin.

Recommended links:


If you're starting out a new project, create a repository before reading further.

0. Make sure subversion is installed on the workstation(s) you will use
  • Subversion is installed by default on all CSAIL Debian workstations.
  • For Windows, TortoiseSVN is recommended, which integrates into Windows Explorer (so that checkout, update, and similar operations are accessible by right-clicking a file or folder). Currently "built against Subversion 1.6.x".
  • Mac OS provides subversion via XCode / Developer Tools; it should already be in /usr/bin/svn. We recommend new users use SCPlugin which integrates into the Mac OS Finder. Mac OS 10.5 provides svn 1.4; 10.6 provides svn 1.6. ZigVersion is also available (a standalone application).
  • Ubuntu provides the subversion package (may need to be manually selected). Ubuntu 9.10 and later provide subversion 1.6.
  • Other OSes: see If you have a choice, we suggest version 1.5.

1. Get (or create) your Repository's URL
  • This may mean asking a fellow project member for the URL that starts with svn+ssh:// or https://
  • Or see SubversionRepositories to set up your own new repository

2a. If using svn+ssh:// from Mac OS or other non-CSAIL *nix
  • Make sure Kerberos is installed properly (Mac, Ubuntu) and that you have valid Kerberos tickets
  • Configure ssh to forward Kerberos credentials (bottom of the appropriate Kerberos page above)
  • If your login name on your local name is different from your CSAIL username, add the line User yourcsailusername to your /Users/yourlocalusername/.ssh/config file, within the * section you just created in the previous step.
  • Make sure the subversion command-line binary is installed and accessible -- which svn should return a full path, like /usr/bin/svn.

2b. If using svn+ssh:// access from Windows
  • Make sure Kerberos is installed properly, and that you have valid CSAIL Kerberos tickets before each SVN session
  • Install PuTTY >= 0.61
    • be sure to customize Auth/GSSAPI and add your username to a custom "csail" profile as described there
    • Accept the host key for Connect to svn.csail by initiating a New Connection, clicking "csail" then "Load", and entering the host name "". Click Yes to the Security Alert (as of May 2012, the fingerprint should match ssh-rsa 1024 19:36:f7:58:ab:84:78:0b:f1:ae:53:7e:28:62:e6:13)
  • Install the version of TortoiseSVN that matches your OS (32- or 64-bit), then configure it to use PuTTY's plink.exe:
    1. Start -> Programs -> TortoiseSVN -> Settings -> Network
    2. For "SSH client", use "C:\Program Files (x86)\PuTTY\plink.exe" -load csail (modify the path to PuTTY\ as appropriate)
  • (Optional) It is possible to use Subversion integrated into Eclipse with the Subclipse plugin. Please contribute full directions. As an outline: you will want to add the PuTTY directory to the PATH environment variable (My Computer -> Properties -> Advanced -> Environment Variables) and set the SVN_SSH variable to something like plink.exe -load csail

2c. If using https://

Note: non-CSAIL users may receive "untrusted certificate" errors, which are expected because they haven't installed the Master CA that allows CSAIL users to distinguish legitimate CSAIL https:// sites.

Check out a copy of the repository

csailuser@somehost:~$ mkdir checkouts
csailuser@somehost:~$ cd checkouts
csailuser@somehost:~/checkouts$ ls
csailuser@somehost:~/checkouts$ svn checkout svn+ssh://
A  test_repo/foo
A  test_repo/bar
A  test_repo/pub
A  test_repo/pub/beer
A  test_repo/baz
Checked out revision 1.

We now have a local working copy of the repository, and we can share the URL of the repository with our group mates so they can also check out a copy and begin working.

Make edits and commit changes

There's no particular magic to editing a working copy; just use your favorite editor and hack away. Note that renaming and moving files must be done within subversion, for example svn rm <file> and svn mv <item> <new_name_or_location> When you're done, you will want to commit your changes. In the following example, we've edited the file pub/beer, and want to push the change to the repository.

csailuser@somehost:~/checkouts/test_repo/pub$ svn commit -m "added more beer"
Sending        pub/beer
Transmitting file data .
Committed revision 2.

Bring updated files down into my working copy

Use svn status -u to show all edits (local and remote) that are pending, or just svn update to refresh the local copy from the repository.

csailuser@somehost:~/checkouts/test_repo$ svn update
U  bar
Updated to revision 3.

Hmmm, someone else went to the bar. Now I have an updated version of that file, which has version number 3.

Warnings and Problems

  • If your svn client version is different than 1.5, it is important that you do not share working copies (checkouts) in AFS with CSAIL Debian users. Checkouts will become unusable to svn clients < 1.6. Subversion designers expect you to only create separate checkouts for each machine, on local storage.
  • Years ago, TIG recommended using file:// repository URLs in simple cases. This is no longer recommended in any circumstance. For example, hooks will not run predictably. If, checking a repository need to preserve, svn info returns "URL: file:///...", please investigate the svn switch --relocate command or email help.

  • "permission denied" or "forbidden" errors
    • AFS permissions may be incorrect: compare to SubversionRepositories#Creating_a_Subversion_repository
    • You may have expired AFS tokens and/or Kerberos tickets. Try renew or kinit && aklog
    • You may have attempted to use public-key authentication, for example ~/.ssh/authorized_keys. This is not supported at CSAIL because it leaves you without AFS tokens and unable to write any files. See Prerequisites 2a/2b, above.
  • "fs: You don't have the required access rights" updating AFS permissions
    • You don't have AFS administer permissions -- a -- on the directory you're trying to fix.

Important note about SVN repositories on network filesystems

Older versions of Subversion used BerkeleyDB as their back-end storage mechanism. Newer versions (1.6) use SQLite. Neither mixes well with network filesystems like AFS or NFS, and their use on these filesystems could result in data loss. We strongly recommend that you convert any repositories with the BerkeleyDB backend to the FSFS backend, and that you avoid creating repositories using client versions >= 1.6. You can find out which backend you're using by examining the db/fs-type file in your repository. If it contains the string bdb, you're using the BerkeleyDB format. Instructions for converting a bdb repository to fsfs are given in the following example:

  • correct any errors in place
svnadmin recover /afs/ 

  • dump all svn actions to a log
svnadmin dump /afs/ > svn.dump 

  • move existing repos out of the way
cd /afs/
mv papers papers.bdb

  • recreate repos; default type is FSFS
svnadmin create papers

  • replay the log
svnadmin load /afs/ < svn.dump

  • if everything worked
rm svn.dump
rm -rf papers.bdb
Topic revision: 20 Aug 2014, JasonDorfman

MIT Computer Science and Artificial Intelligence Laboratory


  • About CSAIL
  • Research
  • News + Events
  • Resources
  • People

This site is powered by Foswiki MIT: Massachusetts Institute of Technology