Using Subversion at CSAIL
What is Subversion?
, 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.
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
1. Get (or create) your Repository's URL
- 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 http://subversion.tigris.org/getting.html. If you have a choice, we suggest version 1.5.
2a. If using svn+ssh:// from Mac OS or other non-CSAIL *nix
- 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
2b. If using svn+ssh:// access from Windows
- Make sure Kerberos is installed properly (Mac, Ubuntu) and that you have valid Kerberos tickets
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
*.csail.mit.edu 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
2c. If using https://
- 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 svn.csail.mit.edu: Connect to svn.csail by initiating a New Connection, clicking "csail" then "Load", and entering the host name "svn.csail.mit.edu". 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
- Start -> Programs -> TortoiseSVN -> Settings -> Network
- 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
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://
Check out a copy of the repository
csailuser@somehost:~$ mkdir checkouts
csailuser@somehost:~$ cd checkouts
csailuser@somehost:~/checkouts$ svn checkout svn+ssh://svn.csail.mit.edu/afs/csail.mit.edu/group/tig/REPOS/test_repo
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>
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"
Transmitting file data .
Committed revision 2.
Bring updated files down into my working copy
svn status -u
to show all edits (local and remote) that are pending, or just
to refresh the local copy from the repository.
csailuser@somehost:~/checkouts/test_repo$ svn update
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
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
file in your repository. If it contains the string
, 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/csail.mit.edu/group/rvsn/papers
- dump all svn actions to a log
svnadmin dump /afs/csail.mit.edu/group/rvsn/papers > svn.dump
- move existing repos out of the way
mv papers papers.bdb
- recreate repos; default type is FSFS
svnadmin create papers
svnadmin load /afs/csail.mit.edu/group/rvsn/papers < svn.dump
rm -rf papers.bdb