I discovered this obscure Subversion feature called externals which is just fascinating. Here’s the documentation for it. I’ll save a more detailed description of Subversion for when I discuss version-control systems in greater detail.
To summarize, the externals feature allows you to effectively make symbolic links to other repositories within your own repository. So, imagine that I have two repositories (which I actually do) – one for the upcoming release of Audio Islam & one for the main Hidayah Online site. Both these projects use a set of database access tools I’ve collectively called “HDB” (For the curious, the “H” stands for “Hidayah”. I won’t tell you what the “DB” stands for…). However, if I update the HDB code in one repository, I will have to manually copy those changes to the other repository – which is kind of counter to what version control is all about – one consistent history for any particular piece of code (or whatever else you happen to be tracking).
The externals feature is the solution to this dilemma. I would create a separate, third repository for my HDB code, and then make an externals link (by editing the svn property :externals) to this repository in both my other repositories. It will appear as a directory in both of them, and that directory will automatically track any developments in the externally-linked repository.
Note that this link is essentially read-only – you cannot update externally-linked code directly. In order to do that, you’ll have to do so through the originating repository, like you would normally (e.g., through my HDB working copy).
The beauty of this feature is that many other projects can safely & automatically track your own project via this method. The SVN documentation does make one important point in the 1.2 “nightly build”:
You should strongly 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 the common sense aspect of not being surprised by 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 they 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.
To summarize what they are saying here, you should make your link to an external project be tied to a specific revision of an external repository, so that future updates don’t break your code. Also, it would keep things consistent with your older versions. This makes sense if you don’t need to track the “latest & greatest” improvements, but you’ll miss out on automatic updates, as well. If you choose to go this route (I probably won’t, since I’m controlling all the code), then you can always update to newer revisions by updating the :externals property again.
I can’t wait to start using this!