Traversing Branches

The svn switch command transforms an existing working copy to reflect a different branch. While this command isn't strictly necessary for working with branches, it provides a nice shortcut. In one of our earlier examples, after creating your private branch, you checked out a fresh working copy of the new repository directory. Instead, you can simply ask Subversion to change your working copy of /calc/trunk to mirror the new branch location:

$ cd calc
$ svn info | grep URL
URL: http://svn.example.com/repos/calc/trunk
Relative URL: ^/calc/trunk
$ svn switch ^/calc/branches/my-calc-branch
U    integer.c
U    button.c
U    Makefile
Updated to revision 341.
$ svn info | grep URL
URL: http://svn.example.com/repos/calc/branches/my-calc-branch
Relative URL: ^/calc/branches/my-calc-branch
$

“Switching” a working copy that has no local modifications to a different branch results in the working copy looking just as it would if you'd done a fresh checkout of the directory. It's usually more efficient to use this command, because often branches differ by only a small degree. The server sends only the minimal set of changes necessary to make your working copy reflect the branch directory.

The svn switch command also takes a --revision (-r) option, so you need not always move your working copy to the HEAD of the branch.

Of course, most projects are more complicated than our calc example, and contain multiple subdirectories. Subversion users often follow a specific algorithm when using branches:

  1. Copy the project's entire “trunk” to a new branch directory.

  2. Switch only part of the trunk working copy to mirror the branch.

In other words, if a user knows that the branch work needs to happen on only a specific subdirectory, she uses svn switch to move only that subdirectory to the branch. (Or sometimes users will switch just a single working file to the branch!) That way, the user can continue to receive normal “trunk” updates to most of her working copy, but the switched portions will remain immune (unless someone commits a change to her branch). This feature adds a whole new dimension to the concept of a “mixed working copy”—not only can working copies contain a mixture of working revisions, but they can also contain a mixture of repository locations as well.

Tip

Typically switched subdirectories share common ancestry with the location which is switched “away” from. However svn switch can switch a subdirectory to mirror a repository location which it shares no common ancestry with. To do this you need to use the --ignore-ancestry option.

If your working copy contains a number of switched subtrees from different repository locations, it continues to function as normal. When you update, you'll receive patches to each subtree as appropriate. When you commit, your local changes are still applied as a single, atomic change to the repository.

Note that while it's okay for your working copy to reflect a mixture of repository locations, these locations must all be within the same repository. Subversion repositories aren't yet able to communicate with one another; that feature is planned for the future.[43]

Tip

Administrators who need to change the URL of a repository which is accessed via HTTP are encouraged to add to their httpd.conf configuration file a permanent redirect from the old URL location to the new one (via the RedirectPermanent directive). Subversion clients will generally display the new repository URL in error messages generated when the user attempts to use working copies which still reflect the old URL location. Since Subversion 1.7 clients will go a step further, automatically relocating the working copy to the new URL.

Switches and Updates

Have you noticed that the output of svn switch and svn update looks the same? The switch command is actually a superset of the update command.

When you run svn update, you're asking the repository to compare two trees. The repository does so, and then sends a description of the differences back to the client. The only difference between svn switch and svn update is that the latter command always compares two identical repository paths.

That is, if your working copy is a mirror of /calc/trunk, svn update will automatically compare your working copy of /calc/trunk to /calc/trunk in the HEAD revision. If you're switching your working copy to a branch, svn switch will compare your working copy of /calc/trunk to some other branch directory in the HEAD revision.

In other words, an update moves your working copy through time. A switch moves your working copy through time and space.

Because svn switch is essentially a variant of svn update, it shares the same behaviors; any local modifications in your working copy are preserved when new data arrives from the repository.

Tip

Have you ever found yourself making some complex edits (in your /trunk working copy) and suddenly realized, “Hey, these changes ought to be in their own branch?” There is a great two step technique to do this:

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/newbranch \
           -m "Create branch 'newbranch'."
Committed revision 353.
$ svn switch ^/calc/branches/newbranch
At revision 353.

The svn switch command, like svn update, preserves your local edits. At this point, your working copy is now a reflection of the newly created branch, and your next svn commit invocation will send your changes there.


[43] You can, however, use svn relocate if the URL of your server changes and you don't want to abandon an existing working copy. See svn relocate in svn Reference—Subversion Command-Line Client for more information and an example.