Synopsis

svn relocate FROM-PREFIX TO-PREFIX [PATH...]

svn relocate TO-URL [PATH]

Description

Sometimes an administrator might change the location (or apparent location, from the client's perspective) of a repository. The content of the repository doesn't change, but the repository's root URL does. The hostname may change because the repository is now being served from a different computer. Or, perhaps the URL scheme changes because the repository is now being served via SSL (using https://) instead of over plain HTTP. There are many different reasons for these types of repository relocations. But ideally, a “change of address” for a repository shouldn't suddently cause all the working copies which point to that repository to become forever unusable. And fortunately, that's not the case. Rather than force users to check out a new working copy when a repository is relocated, Subversion provides the svn relocate command, which “rewrites” the working copy's administrative metadata to refer to the new repository location.

The first svn relocate syntax allows you to update one or more working copies by what essentially amounts to a find-and-replace within the repository root URLs recorded in those working copies. Subversion will replace the initial substring FROM-PREFIX with the string TO-PREFIX in those URLs. These initial URL substrings can be as long or as short as is necessary to differentiate between them. Obviously, to use this syntax form, you need to know both the current root URL of the repository to which the working copy is pointing, and the new URL of that repository. (You can use svn info to determine the former.)

The second syntax does not require that you know the current repository root URL with which the working copy is associated at all—only the new repository URL (TO-URL) to which it should be pointing. In this syntax form, only one working copy may be relocated at a time.

	Warning
	Users often get confused about the difference between svn switch and svn relocate. Here's the rule of thumb: If the working copy needs to reflect a new directory within the repository, use svn switch. If the working copy still reflects the same repository directory, but the location of the repository itself has changed, use svn relocate.

Options

--ignore-externals

Examples

Let's start with a working copy that reflects a local repository URL:

$ svn info | grep URL:
URL: file:///var/svn/repos/trunk
$

One day the administrator decides to rename the on-disk repository directory. We missed the memo, so we see an error the next time we try to update our working copy.

$ svn up
Updating '.':
svn: E180001: Unable to connect to a repository at URL 'file:///var/svn/repos/trunk'

After cornering the administrator over by the vending machines, we learn about the repository being moved and are told the new URL. Rather than checkout a new working copy, though, we simply ask Subversion to rewrite the working copy metadata to point to the new repository location.

$ svn relocate file:///var/svn/new-repos/trunk
$

Subversion doesn't tell us much about what it did, but hey—error-free operation is really all we need, right? Our working copy is functional for online operations again.

$ svn up
Updating '.':
A    lib/new.c
M    src/code.h
M    src/headers.h
…

	Note
	Once again, this type of relocation affects working copy metadata only. It will not change your versioned or unversioned file contents, perform any version control operations (such as commits or updates), and so on.

A few months later, we're told that the company is moving development to separate machines and that we'll be using HTTP to access the repository. So we relocate our working copy again.

$ svn relocate http://svn.company.com/repos/trunk
$

Now, each time we perform a relocation of this sort, Subversion contacts the repository—at its new URL, of course—to verify a few things.

First, it wants to compare the UUID of the repository against what is stored in the working copy. If these UUIDs don't match, the working copy relocation is disallowed. Maybe this isn't the same repository (just in a new location) after all?

Secondly, Subversion wants to ensure that the updated working copy metadata jives with respect to the directory location inside the repository. Subversion won't let you accidentally relocate a working copy of a branch in your repository to the URL of a different branch in the same repository. (That's what svn switch, described in svn switch (sw), is for.)

Also, Subversion will not allow you to relocate a subtree of the working copy. If you're going to relocate the working copy at all, you must relocate the whole thing. This is to protect the integrity of the working copy metadata and behavior as a whole. (And really, you'd be hard pressed to come up with a compelling reason to relocate only a piece of your working copy anyway.)

Let's look at one final relocation opportunity. After using HTTP access for some time, the company moves to SSL-only access. Now, the only change to the repository URL is that the scheme goes from being http:// to being https://. There are two different ways that we could make our working copy reflect ths change. The first is to do exactly as we've done before and relocate to the new repository URL.

$ svn relocate https://svn.company.com/repos/trunk
$

But we have another option here, too. We could simply ask Subversion to swap out the changed prefixes of the URL.

$ svn relocate http https
$

Either approach leaves us a working copy whose metadata has been updated to point to the right repository location.

By default, svn relocate will traverse any external working copies nested within your working copy and attempt relocation of those working copies, too. Use the --ignore-externals option to disable this behavior.