Need to build a working copy made of several different checkouts? Externals definitions may be the tool you need to keep your workflow uninterrupted! For example, if you want subdirectories to come from different locations in a repository or even from completely different repositories, you could set up an externals definition to draw them from their respective locations.

What are externals definitions?

Externals definitions map a local directory to the URL of a versioned resource. The svn:externals property can be set on any versioned directory and its value is a multi-line table of subdirectories and absolute repository URLs.

Why should I use externals definitions?

For workflows requiring a working copy that involves several checkouts, svn:externals can be incredibly useful because once it is set on a directory, then every user who checks out a working copy with that directory will also reap the benefits of the externals definition. This means that once the working copy is defined using svn:externals, then no one else needs to exert extra effort to keep their workflow intact.

How do I use externals?

For this example, we’ll use a repository structure like this:

branches
tags
trunk
--library
--folderA
--folderB
MYFOLDERA
--folder1
MYFOLDERB
--folder2

This repository is located at http://subversion.assembla.com/svn/your_assembla_space/

Step 1

Go to your SVN root and create a text file with any name. We’ll use “external.txt” for this example.

Step 2

In your text file, you need to tell SVN which folder and repo the code will be fetched from. The syntax is: folder svn_url. So for our example, you would add this line to your text file, with the directory name and the URL separated by whitespace: MYFOLDERA/library https://subversion.assembla.com/svn/your_assembla_space/trunk where “MYFOLDERA/library” creates a non-versioned folder called “library” under “MYFOLDERA”. It’s important to remember that there shouldn’t be another folder under “MYFOLDERA” called “library” or this step will fail. The SVN path “.../your_assembla_space/trunk” is the source the files will be fetched from.

Step 3

Now, we’ll set the property: svn propset svn:externals . -F external.txt

The output should be property ‘svn:externals’ set on ‘.’

Step 4

Now, we’ll run svn up to see all of the files and folders under “trunk” fetched under MYFOLDERA/library.

Note: you will see that under “trunk”, “MYFOLDERA/library” will be created too along with any other externals you set. That is how svn:externals works.

Step 5

Now, every time you want to fetch your changes, just run svn up

Step 6

The svn:externals property can (as you would expect) also be used to draw a subdirectory from a second repository (for this example, we’ll call it your_assembla_space_2). In this case, we would create a directory within the second repository by adding a second line to our text file: MYFOLDERB/library http://subversion.assembla.com/svn/your_assembla_space_2/trunk

This will create MYFOLDERB/library under http://subversion.assembla.com/svn/your_assembla_space/

Your external.txt file should now have two lines and look like this:

MYFOLDERA/library https://subversion.assembla.com/svn/your_assembla_space/trunk/
MYFOLDERB/library http://subversion.assembla.com/svn/your_assembla_space_2/trunk

To ensure these changes are put in place, run svn propset svn:externals . -F external.txt

To confirm that your changes took place, run svn pg svn:externals . The output should be the contents of the external.txt file.

What else do I need to know about externals definitions?

There are many things to remember when using svn:externals:

An externals definition can’t point to relative paths (like .../../skins/myskin), only to absolute URLs
The working copies created by the externals definition are not connected to the primary working copy - so to commit changes you’ve made in one or more external working copy, you must run svn commit explicitly on those working copies. In other words, committing on the primary working copy will not recurse into any external ones.
Since externals definitions use absolute URLs, moving or copying a directory to which they are attached will not affect what gets checked out as an external working copy. But, the relative local target subdirectory will move with the renamed directory. For example, say that you use externals definitions on a directory in your /trunk which point to other areas of that line. Then, you use svn copy to branch that line to a new location (we’ll use /branches/my-branch). The externals definitions on your new branch will still refer to the resources in /trunk and not those same resources in /branches/my-branch.
If you need to re-parent your working copy (using svn switch --relocate ), then externals definitions will not also be re-parented

If you have any questions, please email support@assembla.com for assistance.