Subversion Branching Guide

A Quick Guide On Subversion Branching

This article summarises how to create and manage branching in a Subversion repository. For thorough coverage of the subject see the Red Bean Subversion book for your release of Subversion.

Creating a New Branch

A new branch is created in a repository using the svn copy command:

$ svn copy http://svn.example.com/path/to/trunk \
    http://svn.example.com/path/to/branches/branch-name

Working on a Branch

If you have a working copy checked out from trunk (usually the main line of development) and have local changes that should be committed to the newly created branch, then update your local working copy so that you have the same updates from trunk as are currently on the branch.

You may now use the svn switch command to change your local working copy to work with your new branch.

$ cd my/local/working/copy/
$ svn update
updated to revision 123.
$ svn switch http://svn.example.com/path/to/branches/branch-name

Alternatively, you can perform a check-out directly from a branch:

$ svn checkout http://svn.example.com/path/to/branches/branch-name .
 $ cd branch-name

You can now commit any changes that are in your local working copy and they will be applied to the branch and not the trunk.

$ svn commit -m "Some changes for my new branch."

Merging Trunk Changes into the Branch

You should keep your branch up-to-date with changes that are committed onto the trunk. This minimises the potential for conflicts when the time comes to merge your branch back into the trunk. You use the svn merge command to pull trunk changes into your local working copy of the branch. If any conflicts are found, then you should resolve them before committing the effect of the merge and any conflict resolution changes:

$ svn update
 updated to revision 124
 $ svn merge http://svn.example.com/path/to/trunk
 ...
 $ svn commit -m "Bringing branch up-to-date with changes to trunk."

Reintegrating Branch Changes into Trunk

Before merging your branch back into the trunk, ensure it is up-to-date with any changes that have been applied on the trunk – see the section above for details. You can then apply the changes on your branch to the trunk using the svn merge command and the reintegrate flag. First get a clean working copy of the latest version of the trunk:

$ svn checkout http://svn.example.com/path/to/trunk trunk ...
$ cd trunk
$ svn merge --reintegrate \
http://svn.example.com/path/to/branches/branch-name
--- Merging differences between repository URLs into '.':
...

As with merging trunk changes into a branch, you should now resolve any conflicts that may have arisen merging the branch into your local working copy of the trunk. Once you’ve done that you can commit the effect of the merge into the trunk:

$ svn commit -m "Merge my branch into trunk."

You’re done!

After merging a branch into the trunk using the –reintegrate flag the branch can no longer be used (at least using Subversion version 1.5). You could tidy things up on your repository’s branches folder by deleting the old branch, safe in the knowledge that it is still retained by Subversion in it’s database at a specific revision number. All that is required is to find that revision number (say, using the svn log command) and use the svn copy command to copy the revision to a repository branch location.