svn:externals

svn externals are essentially symbolic links to other repositories that get updated along with your current working copy. They can be essential for sharing frameworks across different projects. For example, at BKWLD we keep a repo of our Actionscript codebase (com.bkwld) that we all make revisions to. Adding the package as an external in each Flash/Flex project allows us to make modifications to the codebase without having to worry about copying the changes over to other projects.

Externals can be a pain to set up. There’s no support for them in GUI’s such as Zigversion and Versions (but Cornerstone, Tortoise, SmartSVN and RapidSVN do as far as I know) but they are pretty easy to set up from the command-line. Frankly, I had an easier time setting them up from Terminal than from RapidSVN when I was using GUIs to begin with.

Anyway, externals! Yes!

$ cd Flash/Classes/com
# I'm inside my com folder where I want the bkwld codebase folder to live
# In this example /Flash is a directory at the root of my local repository
$ svn propedit svn:externals .
# edit the 'svn:externals' property for the 'com' folder

At this point, TextMate opens a blank file called svn-prop.tmp where I’m going to define my link to my external (If you get a message about SVN_EDITOR or EDITOR not being set, check out this link.). In this file I add one line:

bkwld http://svn.bkwlddev.com/codebase_as/com/bkwld

The first part bkwld is the path/name/symlink to create in my main repository. So, in this case, I’m going to have a “folder” called “bkwld” in the “com” folder (/Flash/Classes/com/bkwld). You can see that the second part is a full url of the folder I want “bkwld” to “represent” (it’s kind of like an ‘alias’ in MacOS).

Once you close the file, you should see something like

# Set new value for property 'svn:externals' on 'Flash/Classes/com'
$ svn status
#  X	Flash/Classes/com/bkwld

Now, you can see it’s an external link with the ‘X’ status. Now just run svn up to populate the ‘bkwld’ folder! You should see a separate fetch performed with the update. Something like

# Fetching external item into 'Flash/Classes/com/bkwld'
# External at revision 377

Your last step is to

$ svn commit -m "hey I added an external"

commit the revision to the properties of the ‘com’ folder so others can get the external as well. Any updates to our Actionscript codebase can now be reflected in any number of other projects utilizing it (without copying and pasting changes). Brilliant.

svn export

Before export, if we needed files from another project we would often copy files from the working copy clear the .svn files — though that was a pretty sweet trick if I say so myself ;) — and then add them to the repository. I know a lot of people do this. Whether it’s using an automated script or just running it in Terminal, it’s a dangerous trick (I personally have accidently ran it on my ‘Websites’ folder — and it’s recursive — ouch).

A better way to grab versioned files into a new working copy is to use svn export. This “exports a clean directory tree from the repository” (svn help export) meaning that the resulting directory structure will have no .svn folders to begin with. You can navigate to your working copy and run export and then svn add those new files to your working copy.

For example, perhaps I want my bkwld codebase classes in this new project, but I want a clean version that I might hack a bit (and not want to be merged into the main codebase repository). I often for some projects like to have a snapshot of how the classes looked at the time of development so if we go back to the site a year later, there will be very minimal effort applied to recompile the swf with changes.

$ cd Flash/Classes/com
# I'm inside my com folder where I want to add the bkwld codebase folder
$ svn export http://svn.bkwlddev.com/codebase_as/com/bkwld
# exporting a clean version of the 'bkwld' package into 'com' directory
$ svn status
# ?	bkwld
$ svn add bkwld
# add the newly exported tree to my working copy ...
# no 'already under version control' errors ;)
$ svn st
# A	bkwld

You can see this is MUCH better than copying the folders from my working copy of the bkwld repository and then clearning out all the .svn files and THEN adding it. Plus, there’s no possibility of accidently ‘corrupting’ your local copy by deleting a required hidden file.