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.
Si le projet externe est dans le même référentiel, les changements que vous faites là seront inclus dans la liste de livraisons quand vous livrerez votre projet principal.
Si le projet externe est dans un référentiel différent, les changements que vous faites au projet externe seront signalés quand vous livrerez le projet principal, mais vous devez livrer ces changements externes séparément.
Si vous utilisez des URL absolues dans la valeur de l'option svn:externals and que vous déplacez votre copie de travail (i.e., si l'URL de votre référentiel change), alors vos références externes ne seront pas mises à jour et ne fonctionneront plus.
Pour éviter de tels problèmes, à partir de la version 1.5 du client Subversion permet d'utiliser les chemins relatifs dans les références externes. Quatres méthodes différentes de spécifications d'URL sont supportées. Dans les exemples suivants, considérez qu'il y a deux référentiels: un premier ici http://exemple.com/svn/repos-1 et un second ici http://exemple.com/svn/repos-2. Nous avons une extraction de http://exemple.com/svn/repos-1/project/trunk dans C:\Working et la propriété svn:externals est activée sur le répertoire trunk.
Ces URLs commencent toujours par la chaine de caractère ../ par exemple:
../../widgets/foo common/foo-widget
Extraira http://exemple.com/svn/repos-1/widgets/foo dans C:\Working\common\foo-widget.
Notez que l'URL est relative à l'URL du répertoire ayant la propriété svn:externals, pas à l'emplacement physique où le répertoire ayant la référence externe est stocké.
Ces URLs commencent toujours par la chaine de caractère ^/ par exemple:
^/widgets/foo common/foo-widget
Extraira http://exemple.com/svn/repos-1/widgets/foo dans C:\Working\common\foo-widget.
Vous pouvez facilement faire référence à d'autres référentiels ayant le même SVNParentPath (un répertoire commun hébergeant plusieurs référentiels ). Par exemple:
^/../repos-2/hammers/claw common/claw-hammer
Extraira http://exemple.com/svn/repos-2/hammers/claw dans C:\Working\common\claw-hammer.
Les URL qui commencent par // ne comportent que la partie "scheme" de l'URL. C'est utile quand l'hôte est accédé de différentes manières selon l'emplacement du client ; i.e. on utilise http:// depuis l'intranet alors que le protocole svn+ssh:// est nécessaire depuis l'extérieur. Par exemple :
//exemple.com/svn/repos-1/widgets/foo common/foo-widget
Extraira http://exemple.com/svn/repos-1/widgets/foo ou svn+ssh://exemple.com/svn/repos-1/widgets/foo selon la méthode utilisée pour faire la livraison de C:\Travail.
Les URL commençant par la chaine / ne contiennent que la partie "scheme" et le nom d'hôte de l'URI, par exemple :
/svn/repos-1/widgets/foo common/foo-widget
Extraira http://exemple.com/svn/repos-1/widgets/foo dans C:\Travail\common\foo-widget. Mais si vous extrayez votre copie de travail depuis un autre serveur svn+ssh://autre.mirroir.net/svn/repos-1/projet1/trunk alors la référence externe extraira svn+ssh://autre.mirroir.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.
Si vous avez besoin de plus d'informations sur la façon dont TortoiseSVN manipule les propriétés, lisez la section intitulée « Configuration des projets ».
Pour découvrir des méthodes différentes d'accéder aux sous-projets communs, lisez la section intitulée « Inclure un sous-projet commun ».
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.