Basic Branching & Merging in SVN

NOTE: This document assumes you have subversion 1.5 or higher. Branching and merging was different in v1.4 and below.

Subversion allows you to 'branch' source code; e.g. create a separate copy, away from the main development trunk, where you can make changes. Branching is often used if you have to do some larger scale development (a new release, for example) and don't want to mess up your core code. You branch your 'trunk', do your new development in the branch, and then merge your branch back into the trunk when you're done.

This document outlines the basics of a simple branch and merge operation. For details, see the SVN docs on branch and merge.

You branch source code using the svn copy command. By convention, you'll branch from the trunk into the branches directory, although you could theoretically copy from anywhere to anywhere.

From the root of your repository:

cd [repository root]
svn copy trunk/ branches/dev_040610/
svn ci branches/dev_040610/ -m '6 April 2010 Development Branch' 

Now you can make changes to either your development branch, or your trunk. As I mentioned above, I like to do serious development (e.g. a new version) in the branch, and use the trunk for minor maintenance fixes. Many people, however, do it the other way around… the trunk is where serious development goes on, and a branch contains the 'released' code which only gets minor bug fixes.

Regardless, do your development as you normally would, checking code into the development branch.

When you're done, you'll need to merge the changes in your branch back into the trunk. svn merge is your friend here. The interesting thing about merging is that you merge from the copy in the repository, into your trunk.

cd  [repository root]/trunk/
svn merge https://svn.mydomain.com/branches/dev_040610/ .

Now you'll need to manually resolve any conflicts that have come up, and test the results of your merge. You can use svn status to see the status of conflicts, and svn resolved to resolve them.

Once your code works, checkin the trunk:

svn ci -m 'merge from dev_040610 branch'

That's it! You're done.

Both the svn copy and svn merge commands have considerably more options and advanced usage; this document is just a primer to get you started with the basics. Here are a few slightly more advanced things to consider:

All of the svn copy and svn merge commands referenced here used local URLs; meaning you're working on the local copy of your repository. As you may know, subversion allows you to work directly on the repository itself as well using remote URLs. For example, you could do the same branch above as:

svn copy https://svn.mydomain.com/trunk/ https://svn.mydomain.com/branches/dev_040610/ -m '6 April 2010 Development Branch'

I don't recommend doing that, because there's no chance to fix a screwup if you make one. In some cases it my be useful, though.

Once you've finished your development in a given branch, you may want to 'lock' it or 'freeze' it so that users can't check changes in anymore. For more on that, see Locking a Branch in Subversion.