Pin svn:externals at Specific Revisions for Reproducible Builds

Desired Outcome

A Subversion working copy that automatically checks out external repositories at pinned revisions, so every developer and CI build sees identical dependency sources.

Prerequisites

• Subversion 1.5 or newer client and server for peg-revision support.
• Write access to the parent repository to modify the svn:externals property.
• Network reachability from checkout machines and CI agents to the external repository URL.
• Authentication credentials cached or supplied non-interactively for the external repository.

Procedure: Define a Pinned External

1. Choose a vendor directory

Create a consistent location under the parent project, for example trunk/vendor/. Keep paths short to avoid Windows path-length limits.

2. Edit the externals property

Run from the parent directory that will contain the external, for example trunk/:

svn propedit svn:externals .

This opens the editor configured by $EDITOR. Each line defines one external.

3. Add a pinned definition

Use the form [URL] [local-path] [@PEG_REV | -rOPERATIVE_REV]. For reproducible builds, always pin a revision.

Relative URL with peg revision (same server):

^../libfoo vendor/libfoo@1234

Absolute URL with operative revision (different server):

https://svn.example.com/libfoo vendor/libfoo -r1234

The peg revision @1234 freezes the identity of the external node. The operative revision -r1234 freezes the content at that revision. Omitting either means svn update pulls the latest HEAD, which breaks reproducibility.

4. Commit the property change

Commit from the parent directory. You need write access to the parent repository.

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

5. Materialize the external

svn update

Subversion checks out the external into vendor/libfoo/ at the pinned revision.

Expected Checks

Confirm the property value

svn propget svn:externals .

Output should match the definitions entered in the editor.

Verify the pinned revision

svn info vendor/libfoo | grep '^Revision:'

Expected: Revision: 1234.

Dry-run an update

svn update --dry-run

Confirm the listed externals show the pinned revisions and no newer revisions appear.

Check working-copy status

svn status vendor/

After the first update, externals appear as normal directories without an X flag for unmaterialized externals.

CI validation

Run a clean build in CI. Confirm no svn: warning: failed to open errors for externals and that build artifacts are identical across runs.

Recovery Options

Change or move an external

1. Run svn propedit svn:externals ..
2. Edit the line: new URL, local path, or peg revision.
3. Commit the property change.
4. Run svn update to materialize the change.

Roll back a committed property change

If the commit revision was R:

svn merge -c -R .
svn commit -m "Revert external change from rR"

Before committing, discard the edit with svn revert ..

External URL disappears

1. Copy the last known revision into your own repository:

svn copy -r1234 ^/libfoo ^/vendor/libfoo-vendored -m "Vendor libfoo@1234"

2. Switch the external definition to the local path:

^/vendor/libfoo-vendored vendor/libfoo

3. Commit and run svn update.

Limitations and Cautions

• Externals are not first-class versioned objects. svn log on the parent does not show external commit history; run svn log vendor/libfoo separately.
• svn export does not expand externals by default. Use --force or script a checkout followed by export for standalone tarballs.
• Authentication is per-user. CI agents must have credentials cached or passed non-interactively.
• Large external trees increase checkout and update time. Use svn checkout --depth=empty with targeted svn update --set-depth=infinity for optional heavy dependencies.
• Windows path-length limits above 260 characters can break deeply nested externals. Enable long-path support on Windows 10+ or keep vendor paths short.
• File externals require Subversion 1.8 or newer. Older clients ignore them silently.

Version Assumptions

• Subversion 1.5+ for peg revisions
• Subversion 1.8+ for file externals
• Server and client should match feature support