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.
Understanding externals definitions
Externals definitions map a local directory to the URL of a versioned resource. You can set the svn:externals
property on any versioned directory and its value is a multi-line table of subdirectories and absolute repository URLs.
For workflows requiring a working copy that involves several checkouts, svn:externals
helps because once it is set on a directory, then every user who checks out a working copy with that directory also reaps 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.
Using externals
This example uses the following repository structure:
branches
tags
trunk
--library
--folderA
--folderB
MYFOLDERA
--folder1
MYFOLDERB
--folder2
To use external definitions
Go to your SVN root, and then create a text file with any name. We’ll use “external.txt” for this example.
In your text file, tell SVN the folder and repository from with you want to fetch the code. The syntax is:
folder svn_url
. For this example, add the following 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 fails. The SVN path “.../your_assembla_space/trunk” is the source from which the files are fetched.Set the property:
svn propset svn:externals . -F external.txt
The output should be
property ‘svn:externals’ set on ‘.’
Run
svn up
to see all of the files and folders under “trunk” fetched under MYFOLDERA/library.
Note: Notice that under “trunk”, “MYFOLDERA/library” is also created along with any other externals you set.Each time you want to fetch your changes, simply run
svn up
You can also use the
svn:externals
property to draw a subdirectory from a second repository. For this example, we’ll call it your_assembla_space_2. In this case, you can create a directory within the second repository by adding a second line to your text file:MYFOLDERB/library http://subversion.assembla.com/svn/your_assembla_space_2/trunk
Your external.txt file should now have two lines and look similar to the following example:
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.
Notes
Additional items to remember when using svn:externals
:
An externals definition can’t point to relative paths, such as .../../skins/myskin. It can point 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 does not recurse into any external ones.Because externals definitions use absolute URLs, moving or copying a directory to which they are attached does not affect what gets checked out as an external working copy. But, the relative local target subdirectory does 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. Use
svn copy
to branch that line to a new location. For this example, we’ll use /branches/my-branch. The externals definitions on your new branch 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 are not also re-parented.
If you have any questions, please email support@assembla.com for assistance.