SVN Repository Access
The SBML Project's software, specification documents, and other materials are stored in a Subversion repository hosted by SourceForge.net. This page provides a basic guide to using the SBML repository with Subversion (SVN).
Subversion has many similarities to CVS (which we used until switching to SVN on 25 June 2008). To download files, you will need an SVN client; the Subversion home page provides information on many different clients for SVN and is a good place to start if you need to find a client. To simply browse the repository, you can use the web interface described below.
Accessing the repository
There are different ways of accessing the repository. The main ones are through a web browser, and directly via SVN software.
Read-only web-browser access
SourceForge kindly provides a web interface for browsing project files. Simply click on the following URL in a web browser, and you will be taken there directly: http://sbml.svn.sourceforge.net/viewvc/sbml/trunk
Read-only and read-write direct SVN access
The software you use for SVN access may have different paradigms for working with SVN repositories. The following information applies to the basic command-line client software. First, create a directory on your local hard disk where you would like to keep your local sandbox copy of the SVN repository. Then do one of the following:
- To download a copy of the subtree for an SBML project module, find out the name of the module you want (perhaps using the web interface mentioned above), and use a command of the following form, replacing module with the name of what you actually want to download:
svn co https://sbml.svn.sourceforge.net/svnroot/sbml/trunk/module
- For example, if you wanted to download a copy of the libSBML subtree, you could use the following command:
svn co https://sbml.svn.sourceforge.net/svnroot/sbml/trunk/libsbml
- To download the entire SBML project tree (warning: this is 2.5 GB of files and takes forever to download):
svn co https://sbml.svn.sourceforge.net/svnroot/sbml/trunk sbml
Email notifications of changes
If you are obtaining your libSBML files from SVN, you may wish to subscribe to the mailing list sbml-svn, to be apprised of changes to the SVN repository as soon as they are committed. You can join the list by visiting the sbml-svn list subscription page on SourceForge.
There is unfortunately no easy facility for limiting the notifications to a particular subproject in SBML (e.g., to get notifications only about SBMLToolbox). The notifications apply to any changes anywhere in the SBML repository.
Important tips for working with SVN
There are many resources on the net explaining how to use SVN, so we will not repeat the information here. However, there are some points that are not immediately obvious unless you run into them or spend a lot more time reading SVN guides. We bring them up here.
- As with CVS, you often need to indicate to SVN when a file is considered binary and SVN should not do line-ending conversion on it. This is best done as part of the initial check-in of a file. The method involves setting the svn:mime-type property to application/octet-stream as in the following example:
svn propset svn:mime-type application/octet-stream file
- Similarly, for text files, you should set the svn:eol-style property to native so that text files do not end up with mixed end-of-line characters. This is particularly important in a team with multiple developers editing the same files, some of whom work in Windows and some in Linux or MacOS.
svn propset svn:eol-style native file
- If you add a shell script or other file that is meant to be executable by anyone who checks out the file, you must set another specific SVN property on the file so that the checked-out version is executable. This is important for things like GNU configure scripts. Use the following command to set the executable property for a file:
svn propset svn:executable file
Finally, it goes without saying that when you commit changes to a file, you should write a non-empty log message for the svn commit action.
Special rules for the SBML project repository
Certain aspects of SVN are unfortunately difficult or awkward. To help with some common situations, the SBML project members implemented the following policies and routines. In the following discussion, "ROOT" refers to the root of the SBML repository, i.e., https://sbml.svn.sourceforge.net/svnroot/sbml/trunk.
Many directories need some files (e.g., files created by a "make" command ) to be ignored and not checked into the repository. CVS had a nice and easy mechanism for doing this (the .cvsignore file), but SVN's mechanism is much more awkward: you must set the svn:ignore property on the directory itself to a newline-separated list of filename patterns. Since the list is not stored in a file, it is awkward to update (for example, to add or delete a file to be ignored).
To cope with this, we implemented a simple scheme. Directories in which files need to be ignored have a special .svnignore file; inside this file is a list of files and subdirectories to be ignored. This file's contents are used as the basis of the directory's svn:ignore property. When a change is needed (to add or delete a file or directory to be ignored), we edit this file's contents, and then run the simple script ROOT/projects/scripts/svn-update-from-svnignore.sh. The script takes care of setting the svn:ignore property and doing svn commit on the directory and .svnignore file.
More about Subversion
The folks at Red Bean have written a free online book on Subversion:
The following sections are most relevant for those switching from CVS:
There is a lengthy FAQ document on Tigris here:
The major improvements of SVN over CVS are: committing a group of changes is atomic, directories can be easily moved, renamed, and copied, branching is trivially easy, and since SVN keeps pristine copies of your last checkout, svn diff, status, and revert do not require connecting to the (remote) repository.