Simple introduction to SVN externals

Not so long ago, we’ve had to include a third-party library into a new project (using SVN). Our first idea (the one which did not imply thinking) was to SVN-export library files from the remote repository, paste them into the project, SVN-add them, then SVN-commit files.

Having to keep these library files up-to-date with official patches and improvements sounded like a full-time job.
This solution sucked.
A lot.

We are programmers, and we really hate repetitive tasks because we are lazy. We spend most of our time building applications which automate human tasks, why not take care of this one?

Good news, a quick googling revealed our issue was a common one, and there was already a ready-to-use solution: SVN externals.

What are SVN externals?

SVN externals allow to include (nest) a remote SVN repository into another SVN repository. They are set through SVN properties.

How to use them?

If you’re a command-line geek, type:

svn propset svn:externals "library http://svn.3rdapp.com/super-library/" .

This will create a SVN property at the current location (don’t miss the final dot “.” at the end) named “svn:externals”, and its value will be “http://svn.3rdapp.com/super-library/ library”. Which means: insert a directory named “library”, which will retrieve its content from a distant SVN repository located at “http://svn.3rdapp.com/super-library/”. The next time you run a SVN-update, the third-party files will be added to your SVN project.

You can do the same with TortoiseSVN Windows Shell Extension for Subversion: right-click when browsing your SVN project with the Windows file explorer, highlight “TortoiseSVN”, then click “Properties”:

SVN externals: TortoiseSVN, step 1

Now, click “New…”, type or pick “svn:externals” in the “Property name:” drop-down, then type “http://svn.3rdapp.com/super-library/ library” in the “Property value:” textarea. Click “OK” twice:

SVN externals: TortoiseSVN, step 2

Now, every time a new version of the third-party application will be released, it will be reflected when you SVN-update your local copy of your project.

12 comments

  1. Ah, I think I see what happened with your example. Your svn documentation links point to Subversion 1.5, which used the “backward” syntax. In 1.6 or 1.7, the order on the svn:externals property was changed to ‘{directory-name} {url}’

  2. Thanks! It’s really easy to understand. Earlier, I was scared to learn SVN Externals. Your explaination given a lot of relief. Now I can go through Advanced SVN Externals.

  3. Yes a good summary stating what this is really intended for!
    I have inherited a (multi-application) project where externals are used to link to directories under the SAME repository, thus creating a multiply connected graph rather than a tree. Specifically two applications which link the same (internal) library will have ‘externals’ linking to the source tree of that library.
    The only upside of this is that if you check out the code to develop one application, you automatically have the code of the library, appearing as if it is under your application’s hierarchy. I suspect the downside is much bigger though? Interested in other opinions!

    1. I have worked in some big projects with internal externals, too. IMHO it works great as a way to preconfigure sparse checkouts, to integrate different libraries etc. residing in the same or other repositories. In fact, in the end we had a bunch of empty “checkout folders” for each role and project, that had an external configurations setting up a suitable working copy using the correct libraries, modules, branches for the specific role (e.g. artists, QA, frontend developer, backend developer, library maintainer, ….). The externals even make it easy to migrate parts between repositories, folders, branches from a central point. We had no problems with this setup …

Leave a Reply

Your email address will not be published. Required fields are marked *