Using svn:externals to Share Code Across Subversion Projects

The problem: duplicated code in multiple Subversion checkouts

When several projects rely on the same utility library, teams often copy the source into each repository. This creates drift: a bug fix in one copy must be manually propagated to the others, and the history of the shared code becomes fragmented.

How svn:externals helps

The svn:externals property lets you declare that a directory inside a working copy should actually be a checkout of another repository location. When you run svn update on the parent directory, Subversion automatically fetches (or updates) the external resource, keeping it in sync without manual copying.

Worked example: adding a shared library

1. Create a repository for the shared code (run on the server with appropriate admin rights):

   svnadmin create /srv/svn/sharedlib
   svn mkdir file:///srv/svn/sharedlib/trunk -m "Initial layout"
   # Add some source files
   svn import ./mylib file:///srv/svn/sharedlib/trunk -m "Import library"
   

2. Create a repository for the main project:

   svnadmin create /srv/svn/myproject
   svn mkdir file:///srv/svn/myproject/trunk -m "Initial layout"
   svn mkdir file:///srv/svn/myproject/trunk/src -m "Add src dir"
   

3. Check out the project working copy (client side, read/write access to the repo):

   svn checkout file:///srv/svn/myproject/trunk ~/work/myproject
   cd ~/work/myproject
   

4. Set the externals property on the directory where you want the library to appear (e.g., src/lib):

   mkdir -p src/lib
   svn propset svn:externals "lib file:///srv/svn/sharedlib/trunk" src/
   svn commit -m "Add svn:externals for shared library"
   

   Here lib is the relative path inside src/ where the external will be checked out.

5. Update to pull in the external:

   svn update
   

   After the update you should see a new directory src/lib containing the library files, and svn status will show it as a normal versioned directory (not marked with ?).

6. Verify the property:

   svn propget svn:externals src/
   # Expected output: lib file:///srv/svn/sharedlib/trunk
   

Trade‑off: floating vs. pinned externals

If you leave the external without a revision specifier (as in the example), svn update will always fetch the latest revision from sharedlib/trunk. This keeps projects automatically up‑to‑date but can introduce breaking changes if the library evolves unexpectedly.

To avoid surprise upgrades, pin the external to a known revision:

svn propset svn:externals "lib -r1234 file:///srv/svn/sharedlib/trunk" src/
svn commit -m "Pin shared library to r1234"

Now svn update will only change the external when you explicitly update the property to a newer revision.

Limitation and verification

The most common failure mode is an unavailable external repository. If the server hosting sharedlib is down or its URL changes, svn update on the parent project will abort with an error like:

svn: E170013: Unable to connect to a repository at URL 'file:///srv/svn/sharedlib/trunk'
svn: E210002: Unable to open an ra_local session to URL
svn: E230001: Repository moved permanently to 'new_location'; please relocate

To check that the external is working, run:

svn update
# Should succeed and show the external at its current revision
svn info src/lib
# Displays the URL and revision of the external

If you suspect the external is broken, temporarily rename the external’s URL in the property, commit, and run svn update again; you should see the failure message above. Reverting the property restores normal operation.

Actionable closing

Use svn:externals to keep shared code in one place and avoid manual copies. Agree on a team policy: either track the latest trunk (floating) for rapidly evolving utilities, or pin to a specific revision for stable dependencies. Document the chosen policy in your project’s README, and periodically run svn update on a clean checkout to verify that all externals resolve correctly.