VRL Lab Home


How do I create a Subversion repository for a code project?

0. What is SVN?
1. How do I create an SVN repository?
2. How do I use an existing SVN repository?

0. What is SVN?

SVN is short for Subversion. It is a code repository management solution that is made to both save code persistently and support organized multi-user interaction with the codebase. A central version of the code is saved on a server, and each user has their own "checkout" of the code. Every time the server version is saved, the version number is increased. In the case of major bugs or mistakes, the code can always be reverted to a previous version.

For complete information via the free Subversion book, check out http://svnbook.red-bean.com/.

A very handy cheat card for svn commands can be found here.


1. How do I create an SVN repository?

To create an svn repository requires only 1 simple command line operation on a system that has svn installed. If you are creating this repository on the cs afs space, you will first need to ssh into the machine who's svn installation will be used. You may use any machine (on elements, pishon, blitz, etc), but you must always use the same machine to access the repository or you could corrupt the it. If you log into a set of machines like elements, be sure to find out which specific machine (e.g. arsenic) that you are on using the host command. The reason that this is important is that different machines may have different versions of svn installed and will access the repository in different ways. You will enforce using the same machine later, but when you are creating the repository just take note of the machine you are using. Lately we've been using antimony.

Once you are in the parent directory where you will create your repository, create the actual holding directory and then issue the following command from the parent directory:

svnadmin --fs-type=fsfs create your_svn_directory

The --fs-type=fsfs is very important when creating the repository on afs. This tells SVN to use the Fast Secure File System (FSFS) backend instead of Berkeley Data Base (BDB) because of the way BDB handles file locking.

Then go to your own local workspace, and checkout the svn repo (see item 2. How do I use an existing SVN repository? below). Add your own files and directories to the repo, commit etc.

Hints about setting up svn repos for manuscripts:
* Do not add .pdf, .dvi, .log etc files to the repo. Just the source files. Otherwise we'll always get nasty conflicts as we check in a new version.
* Place figures in a separate figures/ directory
* Convert figures to .eps to avoid bounding boxes problems
* Split the manuscript into subparts. Label the subparts chronologically, starting with 01. or so. This makes it easier to avoid conflicts.

3. How do I use an existing SVN repository?

We will never access the repository directly, but will interact through our own checkouts. We will access the repository using svn+ssh. This method uses the security built in to our cs machines and afs.

To get a checkout,

1. Create a file on your machine that will hold the checkout of the repository.

2. From just inside of that directory, use this command:

svn checkout svn+ssh:// your_cs_username @ machine_name (eg. arsenic.cs.pitt.edu) directory_of_repository (eg. /afs/cs.pitt.edu/public/projects/gfx3/...)

inserting the appropriate directory/machine name/directory.
svn checkout svn+ssh://als152@arsenic.cs.pitt.edu/afs/cs.pitt.edu/projects/vis/visweb/webtest/astro_cs1699/gigi/

If command-line is not your style, then keep in mind that for Windows clients the program TortoiseSvn is available, which integrates the subversion functionality into the Internet Explorer (actually, looking at the page, this might work pretty nicely with OSX and Linux too).

You will be asked for your password twice.

The repository is available from anywhere, but again it is important to check it out from the machine that it was originally created on. This is so that there is only 1 instance of the svn server software accessing the repository files at one time. The server location is stored once the checkout is acquired, so you only have to specify it at this step and it will be automatic after that point.

Now you should have the contents of the repository in your local directory. You interact with the checkout as you would any directory structure on your system. These changes will not effect what is on the repository server until you use special svn commands:

svn add &lang file or directory &rang - This adds file or directory to the subversion management system.

svn delete &lang file or directory &rang - This removes the file or directory from the subversion management system *and also deletes it from your filesystem*.

svn commit -m "&lang message &rang" - This finalization step uploads the changes to the server. So you will add files, and then commit to send them to the server. The -m "&lang message &rang" adds a description to your upload. It's best if you create a detailed description for every commit.

To get all of the uploads that other users have committed to the repository, use

svn update - Gets all changes from the server and applies them to your local checkout.

Commit and update actions will require you to enter your password again. Each commit results in creating a new revision with a unique id.

You can revert back to any previous revision if need be using the svn revert command.

If multiple people end up editing the same file, you will encounter a "collision". If you do have to edit a lot of the same code as other team members, then you can "branch" the codebase so you each have your own copies of the whole system that you "merge" later.

For more details, check out the free svn book or, of course, Google.