svn relocate — Relocate the working copy to point to a different repository root URL.
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
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
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 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.
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.
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 …
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
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 http://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
option to disable this behavior.