Tidbit – svn:externals

Not too long ago, I had a need to tie a number of svn repositories together. What I wanted was to create a 1 repository with a number of sharable assets (images, language files, 3rd party libraries, shared code) and have other repositories somehow link to it.

The way I had handled this in the past was simple: checkout each svn repository and cross reference them. As an example, my directory structure would look something like:


I would then add a reference to the xunit.dll from Project1.Tests, which would use the following relative path: ../../AssetRepository/references/xunt.dll.

This solution works great, except it imposes a structure that each team-member must adhere to. In this case, all repositories must be at the same level within the same folder.

Luckily, Subversion has a better solution, the svn:externals property. svn:externals essentially creates a shortcut/link from a folder in one repository to some other repository (or to another place within the same repository). Once 1 person sets it up, it just works for everyone else – they’ll never know that AssetRepository even exists.

How do you do it? If you are using TurtoiseSVN, right click on the Project1Repository and pick “Properties” from the TurtoiseSVN context-menu. Add a new entry with the name of “svn:externals” and a value to the local path + SPACE + external repository. In our case, value would look like:

References svn://AssetRepository/references

That’s all there is to it. You checkout the Project1Repository, you’ll end up with an extra folder:


You might think that you need to create an empty ‘References’ folder at the root of your Project1Repository – don’t. The local path specified in your svn:externals definition should not physically exists within that repository.

That’s all there is to it. Other developers can now checkout/commit without ever knowing how things are set. If they change a file within the References/ folder, it’ll commit to the proper repository, namely AssetRepository.

You can learn more from the red-book

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.

4 Responses to Tidbit – svn:externals

  1. @karl: Agreed. The problem with svn:externals that don’t explicitly specify the revision number is this: what are you going to do when you tag _your_ build?

    You don’t want that tag following the HEAD of the external, and SVN doesn’t provide a way to “pin” externals in tags. The current recommendation (as I understand it) is to be explicit about which revision you want (even in your trunk) and then to “move up” the revision from time to time. If you do that, then tags are a point-in-time snapshot.

    You might argue that branching and tagging should clone the external, just in case it goes away. You _do_ still want to build that branch, don’t you?

    SVN 1.5 also adds all sorts of other cool stuff, like relative externals, which makes dealing with (e.g.) internal/external addresses easier.

  2. karl says:

    @Roger: updated, thx

    @Romain: Absolutely. Left the tags/trunk/braches out for simplicity. Should have mentioned that you can do it though, and should, unless you’re living in the trunk…cuz you know..real developers do it in the trunk.

  3. Yep, SVN 1.5 supports several ways to define external references ; but you shouldn’t reference externals without specifying explicitly the revision number you depend on.

  4. Couple of nitpicks: It’s svn:externals (colon, not hyphen), and you should probably link to the latest version of the book (not 1.0): http://svnbook.red-bean.com/nightly/en/svn.advanced.externals.html — the externals syntax was improved in SVN 1.5.