Sometimes it is useful to construct a working copy that is made out
of a number of different checkouts. For example, you may want different
files or subdirectories to come from different locations in a repository,
or perhaps from different repositories altogether.
If you want every user to have the same layout, you can define the
svn:externals properties to pull in the specified
resource at the locations where they are needed.
Let's say you check out a working copy of
/project1 to
D:\dev\project1.
Select the folder D:\dev\project1,
right click and choose
→
from the context menu.
The Properties Dialog comes up. Then go to the Subversion tab.
There, you can set properties. Click .
Select the svn:externals property from the
combobox and write in the edit box the repository URL in the format
url folder
or if you want to specify a particular revision,
-rREV url folder
You can add multiple external projects, 1 per line.
Suppose that you have set these properties on
D:\dev\project1:
http://sounds.red-bean.com/repos sounds http://graphics.red-bean.com/repos/fast%20graphics "quick graphs" -r21 http://svn.red-bean.com/repos/skin-maker skins/toolkit
Now click and commit your changes.
When you (or any other user) update your working copy, Subversion
will create a sub-folder
D:\dev\project1\sounds and checkout the sounds
project, another sub-folder D:\dev\project1\quick_graphs
containing the graphics project, and finally a nested sub-folder
D:\dev\project1\skins\toolkit containing
revision 21 of the skin-maker project.
URLs must be properly escaped or they will not work, e.g. you must
replace each space with %20 as shown in the
second example above.
If you want the local path to include spaces or other special characters,
you can enclose it in double quotes, or you can use the \
(backslash) character as a Unix shell style escape character preceding any
special character. Of course this also means that you must use
/ (forward slash) as a path delimiter.
Note that this behaviour is new in Subversion 1.6 and will not work with
older clients.
You should strongly consider using explicit revision numbers in all of your externals definitions, as described above. 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 code base.
The format shown here was introduced in Subversion 1.5. You may also see the older format which has the same information in a different order. The new format is preferred as it supports several useful features described below, but it will not work on older clients. The differences are shown in the Subversion Book .
If the external project is in the same repository, any changes you make there there will be included in the commit list when you commit your main project.
If the external project is in a different repository, any changes you make to the external project will be notified when you commit the main project, but you have to commit those external changes separately.
If you use absolute URLs in svn:externals
definitions and you have to relocate your working copy (i.e.,
if the URL of your repository changes), then your externals
won't change and might not work anymore.
To avoid such problems, Subversion clients version 1.5 and
higher support relative external URLs. Four different methods
of specifying a relative URL are supported.
In the following examples, assume we have two repositories: one at
http://example.com/svn/repos-1
and another at
http://example.com/svn/repos-2.
We have a checkout of
http://example.com/svn/repos-1/project/trunk
into C:\Working and the svn:externals
property is set on trunk.
These URLs always begin with the string ../
for example:
../../widgets/foo common/foo-widget
This will extract
http://example.com/svn/repos-1/widgets/foo
into
C:\Working\common\foo-widget.
Note that the URL is relative to the URL of the directory with the
svn:externals property, not to the directory where
the external is written to disk.
These URLs always begin with the string ^/
for example:
^/widgets/foo common/foo-widget
This will extract
http://example.com/svn/repos-1/widgets/foo
into
C:\Working\common\foo-widget.
You can easily refer to other repositories with the same
SVNParentPath (a common directory holding
several repositories). For example:
^/../repos-2/hammers/claw common/claw-hammer
This will extract
http://example.com/svn/repos-2/hammers/claw
into
C:\Working\common\claw-hammer.
URLs beginning with the string // copy
only the scheme part of the URL. This is useful when the same hostname
must the accessed with different schemes depending upon network location;
e.g. clients in the intranet use http://
while external clients use svn+ssh://.
For example:
//example.com/svn/repos-1/widgets/foo common/foo-widget
This will extract
http://example.com/svn/repos-1/widgets/foo
or
svn+ssh://example.com/svn/repos-1/widgets/foo
depending on which method was used to checkout
C:\Working.
URLs beginning with the string / copy
the scheme and the hostname part of the URL, for example:
/svn/repos-1/widgets/foo common/foo-widget
This will extract
http://example.com/svn/repos-1/widgets/foo
into
C:\Working\common\foo-widget.
But if you checkout your working copy from another server at
svn+ssh://another.mirror.net/svn/repos-1/project1/trunk
then the external reference will extract
svn+ssh://another.mirror.net/svn/repos-1/widgets/foo.
You can also specify a peg revision after the URL if required, e.g.
http://sounds.red-bean.com/repos@19.
If you need more information how TortoiseSVN handles Properties read the section called “Project Settings”.
To find out about different methods of accessing common sub-projects read the section called “Include a common sub-project”.
As of Subversion 1.6 you can add single file externals to your working copy using the same syntax as for folders. However, there are some restrictions.
The path to the file external must place the file in an existing
versioned folder. In general it makes most sense to place the file
directly in the folder that has svn:externals
set, but it can be in a versioned sub-folder if necessary.
By contrast, directory externals will automatically create any
intermediate unversioned folders as required.
The URL for a file external must be in the same repository as the URL that the file external will be inserted into; inter-repository file externals are not supported.
A file external behaves just like any other versioned file in many respects,
but they cannot be moved or deleted using the normal commands; the
svn:externals property must be modified instead.
In subversion 1.6 it is not possible to remove a file external
from your working copy once you have added it, even if you delete
the svn:externals property altogether. You
have to checkout a fresh working copy to remove the file.