Revision as of 15:23, 30 June 2015 by Lmperry (Talk | contribs)
Jump to: navigation, search

We use SVN (subversion) for managing lab source code (as of August 20, 2008). SVN is usually installed on Linux and run using a set of common SVN commands. On Windows, we recommend installing TortoiseSVN, which provides a simple graphical interface.

Anyone can checkout software from the MrVista repository. You must obtain an account with permission to make changes to the repository.

We are also starting to use GIT for certain repositories. We are guessing that the power of GIT to store our code without us bothering to keep it live on white will prove to be an advantage.


Repository Overview

There are several SVN page repositories stored on white in the directory /var/svn. Administration of these repositories requires logging into white and the ability to perform root (through sudo) operations.

The repositories are separated into three directories. The repositories in these directories have different purposes and access permissions. These three directories contain repositories for the MrVista software (repos), the DARPA Synapse project (repos_darpa), and SCIEN and digital imaging related software (ee). These repositories have different user groups and password access.

The MrVista software in the repos directory is world readable, but you must have a password to write into the repos area.
The ee and repos_darpa directories require passwords for both reading and writing.

Downloading Repositories

Downloading a repository to your local computer is called a checkout. The checkout process means the software is copied onto your local machine in such a way that you can easily update the software to incorporate fixes. The process for checking out software from an SVN repository is described below.

Most MrVista users checkout two repositories: Vistasoft and Vistadisp .

It is less common to checkout the Diffusion Simulator, itkgray or other repositories. It is common to just download the relevant executables which can be found from the Software page.

Most PDC users checkout the ee repository or the repos_darpa repository.

To check out a module, change into the directory in which you wish to store your copy of the repository and use:

svn checkout[NameOfRepository]

For example:

svn checkout
svn checkout
svn checkout
svn checkout

Note that you will get a message telling you that the system was unable to validate white's cirtificate... Press (P) to Accept Permanently or you will get this message every time you update.

To update your copy of the repository to include recent changes to the code, change into the directory in which you wish to store your copy of the repo (e.g., /home/YourUserName/matlab/svn/) and use:

  svn update [NameOfRepository] 

You will see the names of the files that are being updated preceded by a letter indicating if the files have been updated (u) added (a) etc.

  • Useful svn command lines in the Linux environment
    • svn help - list of commands
    • svn info - current revision number and other facts
    • svn export repository new-directory - Get files from the repository


We recommend that you use TortoiseSVN as you SVN client on windows. The home page is TortoiseSVN - you'll need to restart after the install. Here is the the TortoiseSVN download page. When you get there, scroll down towards the bottom of the page. The actual download is at the bottom of the page. For some reason they put a lot of other unrelated stuff at the top.

Once TortoiseSVN is installed on your computer, you are ready to checkout the respository. Please note: You will have to reboot your computer for this install. Also, Tortoise inserts itself into your system so that when you right-click, Tortoise options nearly always appear. If you hate this and want to use another svn method, please do. We don't know any, but we are sure they are out there.

Assuming you have TortoiseSVN installed you are now ready to get the MrVista repository.

  • Navigate to the directory in which you would like to place your copy of the repo
  • Right-click >> SVN Checkout
  • In the Checkout Dialog box enter the url of the repository with the name of the repo you would like to checkout added. See the example below for VISTASOFT

Note that you will get a message telling you that the system was unable to validate white's cirtificate... Click on (Accept Permanently) or you will get this message every time you update.


Using the repository

Updating (from the repository to your local computer) with TortoiseSVN is very simple.

  • Navigate to the directory where you have your copy of the repository saved.
  • Right-Click the folder containing the repo
  • Select SVN-Update

In the Windows environment, SVN repository commands are available through the context-menu (right clicking) when in a directory or with an object selected. The same commands are available through the command line method in Linux/Mac, as explained below.

Editing Repositories

Once a user has been added to the list, they can add new files and commit changes to existing files using the command line (Linux/Mac) or through TortoiseSVN (windows).

To add a file:

  • If you have created a new file, or changed a file name, and want to add it to the repository, you need to use the svn add command before using svn commit:
 svn add filename

To commit changes:

  • Change to the directory that houses your version of vistasoft and type:
 svn commit -m "Type a description of the changes you made" fileName

Browsing Repositories

The subversion repositories can be browsed and changes can be viewed using Trac by clicking on the module and then clicking 'timeline' or 'browse source'. You can also download a zip-archive snapshot from Trac.

Revisions, History, Modifications

In some cases, files are accidentally deleted. In other cases, a fix to one piece of software may cause a bug in another. In these causes you may wish to return to an earlier revision of the repository or file. This is an important feature of SVN.

Accidental file deletion
  • To view changes
    1. Navigate to the file you're interested in and click the revision number in the REV column.
    2. This will take you to the revisions page wherein you can click on the ChgSet number in the ChgSet Column to view the changes.
Revert to a previous version
  • You just SVN updated, something broke but you're not sure which function
    1. Go to the TRAC repository homepage, and on the upper-right-hand side, click on the red link called Revision Log
    2. Alternately, if you want to check for changes made by a particular user, click on the search button and enter a userid
    3. If you want to restore your local copy of the repository to a previous version, find the version number, and, from the command line, type
svn update -r###
(### should be replaced by a number). You can also restore a prior version of one or more files by using the same command plus a file name:
svn update -r### [filename]

To permanently revert an revision using the command line (from Daniel Lemire's blog):

  # Check the most recent versions of your file:
svn log myfile | head -n 10
# Now do the reverse merge. E.g., if the latest revisions are 122 and 227:
svn merge -r 227:122 myfile
# Check that the reverse merge worked:
svn diff myfile
# If all looks good, commit the reverted file:
svn ci
Search text of multiple revisions
  • You are looking for some old code
    1. Navigate to the Source Browser
    2. Click the "View Changes" button at the bottom left of the screen.
    3. Choose from which revisions you would like to see changes. - The latest revision will appear as the default.
    4. All of the revisions will be displayed on the screen.
    5. Use your browser's search/find function to find a specific string. (ctrl + f)

Managing repositories

Adding a User

Adding users to read the WIKI is managed from the Create an account page.

Read below for adding users for SVN checkout.


The default access permissions allow anyone to checkout code from a MrVista repository. However, only users listed in SVN/users/svnpass will be able to check code in. Any white account that is part of fmri group can add a new user to the list.

To add a user to svnpass, log into white and run:

htpasswd /var/svn/users/svnpass USERNAME

(Replacing USERNAME with the desired username. You will be prompted for a new user password.)


For the ISET, PDC, and SYNAPSE projects, only qualified users can check out code. To add a user for one of these projects, a qualified person must add you using

htpasswd /var/svn/users/svnpass_ee USERNAME
htpasswd /var/svn/users/svnpass_darpa USERNAME

Again, replace USERNAME with the desired username. You will be prompted for a new user password.

Password exchanges are relatively secure (because we use SSL), but you still might choose to use a password a little less secure than your unix login password. For white users, this username and password do not have to be the same as your username and password on white, but it can simplify things.

Setting permissions

In the PDC, SYNAPSE, and ISET portions of the pages, there are some viewing restrictions.

A qualified user needs to assign new users viewing restrictions.

There is a user rights page for this purpose. That page is generally available on the wiki tools bar the left.

Creating a new open repository

To add a new (empty) repository called XXXX within the repos directory for MrVista, run the following as root (or with sudo) on white:

  mkdir /var/svn/repos/XXXX
svnadmin create /var/svn/repos/XXXX
chown -R apache.apache /var/svn/repos/XXXX

See below on how to initialize browsing in the repository.

Creating a new read-protected repository

To create a read-protected repository that is only available to people with accounts on white, use the repository directory


but otherwise follow the steps as for the open repository, above.

Important: When you check out the code the URL is a little bit different. Note:   . 

This approach uses the same the same password file used for write-protection of repos, but requires a password for both read and write. (Needs a better explanation).


To import files into a repository on Linux, organize the code so that it is how you want it to look when someone checks it out. The svn gurus suggest a particular directory structure:

  cd /tmp
mkdir XXXX 
mkdir XXXX/branches
mkdir XXXX/tags
mkdir XXXX/trunk

Not all of our repositories are structured this way, however. Sometimes we just put the code in and do not have this extra layer.

Then, copy the files that you want into the trunk and svn import everything:

   cp -r /path/to/project/files XXXX/trunk
   svn import XXXX -m 'Initial repository layout'
   svn list --verbose


From Windows, you should still perform the first step (making the directory) on white (/var/svn). But then rather than structuring your data and so forth on Linux, you can use TortoiseSVN to

  • Checkout the new but empty repository , and
  • Add files from your Windows machine to the repository

Initialize Repository Browsing

To set up a new trac environment for your new svn repo, run this on white:

  trac-admin /var/svn/trac/PROJNAME initenv

replacing PROJNAME with the name or your project (e.g., dSim, itkgray, etc.- no spaces or punctuation). Then answer the questions as best you can. Most of the default answers are fine, except that the "Path to repository" must be set. This should be something like "/var/svn/repos/PROJNAME".

After trac sets up the environment, you need to give apache permission to modify the files. You also need to make sure that the anonymous user can't edit things:

   sudo trac-admin /var/svn/trac/PROJNAME permission remove anonymous WIKI_CREATE WIKI_MODIFY TICKET_CREATE TICKET_MODIFY
sudo chown -R apache /var/svn/trac/PROJNAME

If you don't want the repository to be publicly browsable, then you need to edit (via sudo) trac.conf in the httpd configuration directory on white. Just follow the example for the other secured repos.

SVN Resources

  • For more information, there are many online resources for subversion. E.g., this cheatsheet and the svn book.
  • For Windows/TSVN users, please note the following incompatibility. Microsoft Access Table (MAT) is incompatible with TSVN. When MAT is installed, any file with a .mat extension is treated as a shortcut. This makes no sense, but it is true. Consequently, right-clicking fails to produce the context menu. Uninstalling MAT solves this problem. A discussion thread about MAT and TSVN can be found here.


Of historical Interest:

Personal tools