Mastering Subversion’s Peg Revisions: A Reliable Way to Fetch Files Across Renames and Deletions

Why the “path not found” error keeps popping up

When you run svn cat trunk/src/OldName.java after the file has been renamed, Subversion returns “path not found” even though the file still exists in the repository’s history. The culprit is Subversion’s two‑step addressing model: peg revision (the historical anchor) and operative revision (the snapshot you want to examine). If you skip the peg, SVN assumes @HEAD for URLs and @BASE for working‑copy paths, which breaks when the path no longer exists at that point in time.

What are peg and operative revisions?

• Peg revision tells SVN which historical object you’re talking about. It’s written after the path: path@PEG.
• Operative revision (the -r flag) specifies the revision of that object you want to fetch.
• If you omit the peg, SVN defaults to HEAD for URLs and BASE for working‑copy paths.

Practical pattern for scripts and audits

When writing automation, always resolve the object’s identity first, then anchor your commands with an explicit peg. The following steps are safe across renames, deletions, and branch merges:

1. Use svn info or svn log -v to find the original revision where the file was created or last moved.

   svn log -v --stop-on-copy trunk/src/OldName.java
   # Look for the copyfrom-path and copyfrom-rev entries – they show the rename boundary.

2. Anchor your command with that peg:

   svn cat trunk/src/OldName.java@123 -r 150 > /tmp/OldName_150.java
   # 123 is the peg (original creation or last rename), 150 is the revision you want.
   

3. Verify the result by comparing svn diff -c 150 or by inspecting the file’s checksum.

Concrete example: retrieving a file after a rename

Assume a repository https://svn.example.com/repo with a file created at r100, renamed at r120, and you want its contents at r110 (before the rename). Running svn cat trunk/src/OldName.java -r 110 fails because OldName.java no longer exists at r110. The correct command is:

svn cat trunk/src/OldName.java@100 -r 110 > /tmp/OldName_110.java

Here @100 anchors the lookup to the original creation, and -r 110 pulls the file as it existed in that revision. The command succeeds, and the file is now in /tmp for further analysis.

Trade‑offs and limitations

• Complexity vs. reproducibility: Subversion’s model requires explicit pegs, which can be more verbose than Git’s content‑addressed commits. Scripts must remember the peg or risk future breakage.
• Client version differences: Older SVN clients may treat --stop-on-copy differently. Always test your commands against the exact client version used in production.
• Files containing ‘@’: If a filename literally contains an at‑sign, escape it by appending a trailing @ (e.g., file@name@).

Actionable take‑away

• In every script that accesses historical files, hard‑code the peg revision: path@PEG.
• Use svn log -v --stop-on-copy to discover the correct peg automatically.
• Test your commands in a sandbox repository that mimics your branching and renaming patterns.
• Document the peg strategy in your project’s onboarding guide so new contributors understand why the extra syntax is required.

By adopting this pattern, you avoid “path not found” errors, make your automation reproducible, and keep your audit trails reliable across the entire life cycle of a file.