SVN is one of my absolute favorite tools. It’s hands-down easier to use than TFS or (gasp) SourceSafe, which have been the other common version control systems in my industry. If you aren’t using it, you’re missing out (quiet down all you GIT-heads in the back… keep using it for a few more years and we’ll accept that it isn’t just a fad).
In any project of significant complexity you’re going to use libraries of some kind. These libraries frequently end up being copied into the project tree under a lib subdirectory and compiled or included in a project deployment from there. Most of my projects rely on open source libraries, and as we make changes to a library those changes have to be propagated from project to project using patch files or simple copy/paste. This time-consuming process opens up the possibility of human error and versioning confusion, but there is a better way.
SVN Properties
First, some basics: using Subversion, you can specify metadata properties on any directory or file. These can be used for your own custom purposes, or more often to control how the SVN client treats certain files. One commonly used property is svn:ignore, which (unsurprisingly) tells SVN to ignore particular files when looking for changes in a working copy. My new favorite property is svn:external, which when set on a directory, allows you to define subdirectories and point them at any other SVN path, even to a particular revision. You can set an SVN property using the official command-line client, but I’ll leave the syntax for that to the official documentation and show how to do it in my favorite SVN client, TortoiseSVN.
- Check out a working copy of your project.
- Right-click the parent folder of where you want your library subdirectories placed. On the TortoiseSVN context menu, chose Properties.
- In the properties dialog, click New, then select a property name from the drop-down menu.
svn:externals
In the new properties dialog, select svn:externals, and then we’ll enter a value in the multi-line edit box provided. First, if you’re using an SVN client before version 1.5, upgrade and have everyone on your team upgrade. If you’re stuck using pre-1.5 clients the syntax is different so see the official documentation for the details.
In modern clients the syntax looks like this:
External_Path@RevisionNum SubDir_Name
- External Path: This can be a fully qualified SVN url like “svn://svn.example.com/skin-maker” or you can use symbols to specify a relative URL.
- ../ Relative to the URL of the directory on which the svn:externals property is set
- ^/ Relative to the root of the repository in which the svn:externals property is versioned
- // Relative to the scheme of the URL of the directory on which the svn:externals property is set
- / Relative to the root URL of the server on which the svn:externals property is versioned
I only use one SVN server for my project and libraries repositories, so I generally have external paths in the form of /libraries/libraryName without the protocol and server.
- Revision Number: Regular integer revision number of the libraries repository. Here’s a great note from the SVN Book:
You should seriously consider using explicit revision numbers in all of your externals definitions. Doing so means that you get to decide when to pull down a different snapshot of external information, and exactly which snapshot to pull. Besides avoiding the surprise of getting changes to third-party repositories that you might not have any control over, using explicit revision numbers also means that as you backdate your working copy to a previous revision, your externals definitions will also revert to the way they looked in that previous revision, which in turn means that the external working copies will be updated to match the way they looked back when your repository was at that previous revision. For software projects, this could be the difference between a successful and a failed build of an older snapshot of your complex codebase.
- Subdirectory Name: usually “lib” - the name of the directory underneath the directory with the svn:externals property set, which will be mapped to an external repository URL.
My projects follow a traditional trunk-branches-tags folder structure, with a /source directory under trunk. I set the svn:externals property on that source directory and end up with repository_root/trunk/source/lib pointing at an external library directory.
After setting the property, update and commit, and you should see the external library source downloaded during the update process. Commit will make sure all your team members get the property set in their working copies and their next update will likewise download the external library.
That’s all I have for now. Fire away in the comments if you see a mistake or something isn’t clear.
