Using svn:externals to Link External Repositories in Subversion

When to use svn:externals

If your project depends on a library or tool that lives in its own Subversion repository, you can keep that dependency up‑to‑date without copying its files into your main repo. The svn:externals property tells Subversion to fetch another repository into a subdirectory of your working copy each time you run svn update.

Worked example: linking a third‑party library

1. Check out the main project (if you haven’t already):

   svn checkout https://svn.example.com/repos/myproject/trunk myproject
   cd myproject

   You need write permission to the main repository to set properties.
2. Define the external. Suppose the library lives at https://svn.example.com/repos/libfoo/trunk and you want it in a folder named third_party/libfoo:

   svn propset svn:externals "libfoo https://svn.example.com/repos/libfoo/trunk third_party/libfoo" .
   svn commit -m "Add svn:externals for libfoo"

   The property is set on the current directory (the project root). The value consists of local folder, a space, and the repository URL. The trailing third_party/libfoo is the subdirectory where the external will appear.
3. Fetch the external:

   svn update

   After the update you should see a new directory third_party/libfoo containing the library’s trunk.

Pinning a specific revision

To lock the external to a known state, add a revision number:

svn propset svn:externals "libfoo -r1234 https://svn.example.com/repos/libfoo/trunk third_party/libfoo" .
svn commit -m "Pin libfoo to r1234"

Now svn update will always retrieve revision 1234 of libfoo, even if the external repository advances.

Verifying the configuration

• Check the property: svn propget svn:externals . should return the string you set.
• Confirm the external’s location: svn info third_party/libfoo shows the repository URL and, if pinned, the revision.
• Run svn update again; the external directory should appear (or stay at the pinned revision) without errors.

Limits and common mistakes

• Changes inside the external: You must commit them to the external repository itself. Trying to commit from the main working copy will fail unless you have write access to the external repo.
• Forgetting to commit the property: The external is only fetched after you run svn update following a commit that changed svn:externals. If you skip the commit, other developers won’t see the definition.
• Incorrect URLs or typos: A malformed URL leads to svn update errors like “URL non‑existent”. Double‑check the URL and ensure you can access it with svn info from a clean checkout.
• Relative URLs: Using a relative path (e.g., ../libfoo) can resolve differently depending on where the working copy is rooted. Prefer absolute URLs to avoid mismatches across developer machines.
• No recursive fetch: svn:externals does not automatically follow externals defined inside the external repository. If the external itself relies on another external, you must define that separately.
• Updating a pinned revision: To move to a newer version you must edit the property, commit, and run svn update again. The external will not advance automatically.

Practical way to check the result

After committing the property and running svn update:

1. Run svn propget svn:externals . and verify the output matches the intended definition.
2. Run svn info third_party/libfoo. The Repository Root should point to https://svn.example.com/repos/libfoo and, if pinned, the Revision should be the number you set.
3. Attempt to create a file inside third_party/libfoo and run svn commit. You should be prompted to commit to the external repository’s URL, confirming the separation of histories.

If any of these steps fail, revisit the property definition, check network access to the external repository, and ensure you have the necessary permissions.