BitWorking

Sourceforge, Subversion and svn:externals

Sourceforge now supports Subversion. This isn't new, I blogged about it back in February. What is still unfolding is the impact of that change, and one aspect of subversion that is plum full of potential is also one of its best kept secrets, svn:externals.

svn:externals

Subversion supports setting properties on files and directories, bits of information about the file. You can store any information you want there for your own use. There are several predefined properties that Subversion knows about that modify how files or directories are handled. For example, the svn:keywords property controls which keywords are expanded when a file is checked in. The property I want to draw attention to today is svn:externals:

The svn:externals property contains instructions for Subversion to populate a versioned directory with one or more other checked-out Subversion working copies.

Using this property you can rip, mix, and blend source as long as you can get read access to all the Subversion repositories involved. Let's look at a concrete example of how I use this in the Atom Publishing Protocol Test Suite. The APP Test Suite relies heavily on httplib and also feedvalidator. You are unlikely to have current versions of those modules installed so let's make svn do all the heavy lifting for us. Here we see a checked out copy of the APP Test Suite:


jcgregorio@scandium ~/web/bitworking.org/projects/apptestsuite/client
$ svn info
Path: .
URL: https://svn.sourceforge.net/svnroot/feedvalidator/trunk/apptestsuite/client
Repository UUID: 51a99c5e-f20d-0410-a720-9ba508ce125a
Revision: 596
Node Kind: directory
Schedule: normal
Last Changed Author: jcgregorio
Last Changed Rev: 596
Last Changed Date: 2006-04-03 23:42:34 -0400 (Mon, 03 Apr 2006)
Properties Last Updated: 2006-03-12 17:01:43 -0500 (Sun, 12 Mar 2006)

There is a single property set on the directory:


jcgregorio@scandium ~/web/bitworking.org/projects/apptestsuite/client
$ svn proplist .
Properties on '.':
  svn:externals

We can inspect that value of that property:


jcgregorio@scandium ~/web/bitworking.org/projects/apptestsuite/client
$ svn propget svn:externals .
httplib2 https://svn.sourceforge.net/svnroot/httplib2/trunk/httplib2
feedvalidator https://svn.sourceforge.net/svnroot/feedvalidator/trunk/feedvalidator/src/feedvalidator

This tells Subversion that after checking out the APP Test Suite where it should go to fetch the httplib2 and feedvalidator subprojects. Note that feedvalidator is off in another directory of the same repository and httplib2 is in a completely different repository. Let's see this in action when we check out the APP Test Suite.


$ svn co https://svn.sourceforge.net/svnroot/feedvalidator/trunk/apptestsuite/client .
A    appclienttest.py
A    helloworld.png
 U   .

Fetching external item into 'httplib2'
A    httplib2/__init__.py
Checked out external at revision 181.


Fetching external item into 'feedvalidator'
A    feedvalidator/link.py
A    feedvalidator/__init__.py
A    feedvalidator/entry.py
A    feedvalidator/author.py
A    feedvalidator/feed.py
A    feedvalidator/textInput.py
A    feedvalidator/mediaTypes.py
A    feedvalidator/rss.py
A    feedvalidator/opml.py
A    feedvalidator/itunes.py
A    feedvalidator/content.py
A    feedvalidator/rdf.py
A    feedvalidator/media.py
A    feedvalidator/logging.py
A    feedvalidator/.cvsignore
A    feedvalidator/skipHours.py
A    feedvalidator/cf.py
A    feedvalidator/i18n
A    feedvalidator/i18n/__init__.py
A    feedvalidator/i18n/en.py
A    feedvalidator/i18n/.cvsignore
A    feedvalidator/item.py
A    feedvalidator/uri.py
A    feedvalidator/timeoutsocket.py
A    feedvalidator/xmlEncoding.py
A    feedvalidator/channel.py
A    feedvalidator/validators.py
A    feedvalidator/compatibility.py
A    feedvalidator/iso639codes.py
A    feedvalidator/base.py
A    feedvalidator/extension.py
A    feedvalidator/formatter
A    feedvalidator/formatter/text_html.py
A    feedvalidator/formatter/base.py
A    feedvalidator/formatter/__init__.py
A    feedvalidator/formatter/application_test.py
A    feedvalidator/formatter/text_xml.py
A    feedvalidator/formatter/.cvsignore
A    feedvalidator/formatter/text_plain.py
A    feedvalidator/category.py
A    feedvalidator/image.py
A    feedvalidator/root.py
A    feedvalidator/generator.py
A    feedvalidator/skipDays.py
 U   feedvalidator
Checked out external at revision 605.

Checked out revision 605.

Note that you don't need commit access to the subprojects you include via svn:externals, just read access. Also note that you don't always have to check out the head of a project as svn:externals allows you to specify a specific revision if you wish. You can get all the gory details from the Subversion book.

2006-04-18