How to Use SVN Copy: A Step-by-Step Tutorial

How to Use SVN Copy: A Step-by-Step Tutorial

svn copy is a fundamental command in Subversion (SVN) that serves more than just duplicating files and directories. It’s crucial for creating branches, tags, and maintaining a history of changes. Understanding svn copy is essential for effective version control. This tutorial provides a step-by-step guide to using svn copy, covering its various use cases and best practices.

1. Understanding svn copy‘s Core Functionality

Unlike a simple file system copy (like cp in Linux/Unix or copy in Windows), svn copy creates a link between the source and the destination within the SVN repository. This link preserves the history of the copied item. The destination becomes a “cheap copy,” sharing the same history as the source up to the point of the copy. Subsequent changes to either the source or the destination are tracked independently.

2. Basic Syntax

The general syntax of svn copy is:

bash
svn copy SOURCE DESTINATION -m "Commit message"

• SOURCE: The item you want to copy. This can be:
  • A local working copy path.
  • A URL pointing to a file or directory in the repository.
• DESTINATION: The location where you want to create the copy. This can also be:
  • A local working copy path.
  • A URL pointing to a location in the repository.
• -m "Commit message": A mandatory message describing the reason for the copy. A good commit message is crucial for understanding the history of changes. If you forget the -m option, SVN will prompt you to enter a message using a text editor.

3. Use Cases and Examples

Let’s explore the common use cases of svn copy with practical examples. We’ll assume you have a repository at svn://example.com/repo and a working copy checked out.

3.1. Copying within the Working Copy (Local Copy)

This creates a copy within your local working copy without immediately committing it to the repository. This is useful for preparing a new file or directory based on an existing one before committing the changes.

• Scenario: You want to create a new feature file based on an existing one.

• Steps:

  1. Navigate to the directory in your working copy that contains the file you want to copy (e.g., cd myproject/src).

  2. Execute the copy:

     bash
svn copy feature1.c feature2.c

  3. You’ll see output like:

     A feature2.c
     This indicates that feature2.c has been added to your working copy, scheduled for addition to the repository.

  4. Commit the change:

     bash
svn commit -m "Copied feature1.c to create feature2.c"

3.2. Copying within the Repository (Remote Copy)

This creates a copy directly within the repository. This is the standard method for creating branches and tags. The copy is made immediately on the server, without requiring an explicit commit.

• Scenario: You want to create a branch named release-1.0 from your trunk.

• Steps:

  1. (Optional, but recommended) Update your working copy to ensure you’re branching from the latest revision:

     bash
svn update

  2. Execute the copy:

     bash
svn copy svn://example.com/repo/trunk svn://example.com/repo/branches/release-1.0 -m "Creating release-1.0 branch"

  3. You’ll see output like:

     Committed revision 123.

  4. You now have a new branch at svn://example.com/repo/branches/release-1.0. You can switch your working copy to this branch using svn switch:

     bash
svn switch svn://example.com/repo/branches/release-1.0

• Scenario: You want to create a tag named v1.0 from your trunk.

• Steps:

  1. (Optional, but recommended) Update your working copy.

  2. Execute the copy:

     bash
svn copy svn://example.com/repo/trunk svn://example.com/repo/tags/v1.0 -m "Tagging version 1.0"
     3. Output similar to the branch creation will confirm the tag.

  Important: Tags are conventionally considered read-only. While you can commit changes to a tag, it’s generally bad practice. Tags are meant to represent a specific point in the project’s history.

3.3. Copying from a Specific Revision

You can copy a file or directory as it existed at a specific revision in the repository’s history.

• Scenario: You need to recreate a file as it was in revision 50.

• Steps:

  1. Use the -r option followed by the revision number:

     bash
svn copy -r 50 svn://example.com/repo/trunk/myfile.txt svn://example.com/repo/trunk/myfile_old.txt -m "Recreating myfile.txt from revision 50"

  2. This creates myfile_old.txt in your trunk containing the content of myfile.txt as it existed at revision 50.

3.4. Copying Between Different Repositories

svn copy can also copy between different repositories. This is less common, but can be useful for moving projects or merging repositories.

• Scenario: You want to copy a directory from svn://repo1.com/projectA to svn://repo2.com/projectB.

• Steps:

  bash
svn copy svn://repo1.com/projectA/somedir svn://repo2.com/projectB/somedir -m "Copying somedir from projectA to projectB"
  Important: You’ll likely need appropriate authentication credentials for both repositories.

4. svn move: A Special Case of svn copy and svn delete

The svn move command is essentially a combination of svn copy and svn delete. It copies the source to the destination and then deletes the source. This preserves the history of the moved item.

bash
svn move SOURCE DESTINATION -m "Moved file/directory"

For example:

bash
svn move svn://example.com/repo/trunk/oldfile.txt svn://example.com/repo/trunk/newfile.txt -m "Renamed oldfile.txt to newfile.txt"

5. Best Practices

• Always use meaningful commit messages: Explain why you’re making the copy.
• Use a consistent branching and tagging strategy: Establish conventions for naming branches and tags (e.g., branches/feature-name, tags/vX.Y.Z).
• Update your working copy before branching or tagging: This minimizes the risk of branching from an outdated revision.
• Understand the difference between local and remote copies: Local copies need to be committed; remote copies are immediate.
• Don’t commit changes to tags: Tags should represent a fixed point in history.

6. Troubleshooting

• svn: E155007: ... is not a working copy: This usually means you’re trying to perform an SVN operation outside of a checked-out working copy. Make sure you’re in the correct directory.
• svn: E160013: ... path not found: This indicates that the source URL you provided doesn’t exist in the repository. Double-check the URL.
• svn: E170001: Authorization failed: You don’t have the necessary permissions to access the repository or perform the copy operation. Check your credentials and repository permissions.
• svn: E200009: Could not copy ... (with a more specific error message): Read the detailed error message carefully. It will often provide clues about the problem (e.g., disk space issues, network problems).
• svn: E155010: The node '/path/to/your/file' was already added. This means you likely tried to svn add the file and also svn copy it and are now trying to commit the change. You don’t need to svn add a file you have svn copy‘ed, the latter already performs the add operation.

By following these steps and understanding the nuances of svn copy, you can effectively manage your project’s history, create branches and tags, and collaborate with others using Subversion. This command, while simple in syntax, is a powerful tool for version control.