Subversion svn:externals: Share Code Across Repositories

Share code across Subversion repositories without copy-paste using svn:externals: how the property works, a pinned-revision example, verification steps, and the trade-offs to plan for.

The problem: shared code without copy-paste

Several projects need the same library or asset directory. Copying the files into each repository works until the first bug fix, after which every copy drifts out of sync. Subversion's supported answer is the svn:externals property: a versioned pointer that tells a working copy to pull a directory from another repository location automatically during svn update.

How svn:externals works

You set svn:externals on a directory in your repository. Its value is a multi-line string; each line defines one external:

local_name [-r REV] URL[@PEG]

On update, Subversion checks out URL into local_name inside your working copy. Only the property (the pointer) is versioned in the parent repository; the external content lives in, and is versioned by, the external repository. Pinning an explicit revision (-r 1234) makes builds reproducible; omitting it tracks HEAD, which suits active development but can surprise you on update.

Worked example

Assume a main project at $REPO_URL and a shared library at $LIB_URL/lib. Run these as a user with write access to the main repo and read access to the library repo:

Check out the main project:
```
svn checkout $REPO_URL wc_main
```
Set the property on the target directory, pinning a known-good revision:
```
cd wc_main/src
svn propset svn:externals "lib -r 1234 $LIB_URL/lib" .
```

Commit the property change:

svn commit -m "Add lib external pinned at r1234"

Update and confirm the external appears:
```
svn update
ls wc_main/src/lib
```

Verify the pinned revision with svn info wc_main/src/lib and check the Revision field. Note that commits inside the external directory go to the external repository, not the parent — a common surprise.

Trade-offs and limitations

Network dependency: every update contacts the external server; if it is unreachable or the URL changes, the update fails until you fix the property.
Revision drift: unpinned externals silently move to HEAD. Pin revisions for release builds.
Permissions: anyone updating needs read access to the external repository too.

Checking failure behavior

To see what a broken external looks like, point the property at a nonexistent path and run svn update; Subversion reports an access error for the external while the rest of the working copy updates normally. Restore the correct URL, update again, and confirm recovery.

Closing

If you need a shared dependency that evolves independently, svn:externals gives you a versioned, reproducible pointer with no file duplication. Pin revisions for stability, keep the external server available, and remember the external's history stays in its own repository.

Using Subversion svn:externals to Share Code Across Repositories