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 .
In the properties dialog, either double click on the
svn:externals if it already exists, or click
on the button and select
externals from the menu.
To add a new external, click the
and then fill in the required information in the shown dialog.
URLs must be properly escaped or they will not work, e.g. you must
replace each space with %20.
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 the 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 edit dialog for svn:externals
properties allows you to select the externals and automatically
set them explicitly to the HEAD revision.
If the external project is in the same repository, any changes you make 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 shown or indicated 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 and operative revision for the URL if required. To learn more about peg and operative revisions, please read the corresponding chapter in the Subversion book.
If you specify the target folder for the external as a subfolder
like in the examples above, make sure that all
folders in between are versioned as well. So for the examples above,
the folder common should be versioned!
While the external will work in most situations properly if folders in between are not versioned, there are some operations that won't work as you expect. And the status overlay icons in explorer will also not show the correct status.
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 be a direct child of the folder
where you set the svn:externals property.
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.
If you already have a working copy of the files or folders you want to include as externals in another working copy, you can simply add those via drag and drop from the windows explorer.
Simply right drag the file or folder from one
working copy to where you want those to be included as externals.
A context menu appears when you release the mouse button:
if you click on that context menu entry, the svn:externals
property is automatically added. All you have to do after that
is commit the property changes and update to get those externals
properly included in your working copy.