Subversion: Externals Definitions

Published: Mon 22 December 2008
By mafr

In tools.

tags: rcs

Externals definitions are a little known but very useful feature of subversion. Using an externals definition, you can create links to different parts of the repository (or even other repositories). Subversion clients then automatically check out the linked content into your working copy.

How this works is best explained with an example. Suppose you check out your code from the repository:

svn co https://svn.your.host/project/trunk project

Inside your project, you need code from a different location in the repository or maybe even from some other repository. This could be a software module, test data, a generic part of your company's standard build system or other things shared between projects. Many people do this manually:

cd project
svn co https://svn.your.host/whatever/tags/release-1.3 whatever

That's tedious and error prone. A better approach is to use an externals definition that tells subversion to check out that project automatically for you. It works by adding some magic metadata to the project directory (that's the dot on the svn command line!):

cd project
svn propset svn:externals \
  'whatever https://svn.your.host/whatever/tags/release-1.3' .

The svn:externals property accepts a set of declarations, each consisting of a directory name and a subversion URL. Because of this, the propedit command is more useful if you happen to need multiple declarations.

So, every time you check out (or update) the parent project, the whatever project will be checked out, too. The dependency to the other project is versioned by convention (I've linked to a tag in the example), but you can link to any URL and even include a revision number.

For more information see the Subversion book on svn:externals.

social