4.18. External Items


4.18. External Items

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.

4.18.1. External Folders

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 Windows MenuProperties from the context menu. The Properties Dialog comes up. Then go to the Subversion tab. There, you can set properties. Click Properties.... In the properties dialog, either double click on the svn:externals if it already exists, or click on the New... button and select externals from the menu. To add a new external, click the New... and then fill in the required information in the shown dialog.

[Caution] Caution

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.

[Tip] Use explicit revision numbers

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 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.

Relative to parent directory

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.

Relative to repository root

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.

Relative to scheme

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.

Relative to the server's hostname

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.

[Important] Important

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 Section 4.17, “Project Settings”.

To find out about different methods of accessing common sub-projects read Section B.6, “Include a common sub-project”.

4.18.2. External Files

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.

4.18.3. Creating externals via drag and drop

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: SVN Add as externals here 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.