If you are working as part of a team, branching is essential to keeping your changes organized and creates a smooth workflow to avoid conflicts. Branches let you easily maintain your “in-progress” work separately from your completed, tested, and stable code. Not only is this an effective way to collaborate with others, but it will also allow you to automate the deployment of updates and fixes to your servers. Our guide on Developing and deploying with branches covers the high level workflow and benefits of branching. This guide covers specific branching techniques with Subversion.
We’ll be using command line examples in this guide but you should be able to do the same operations in any compatible Subversion client.
Creating a branch
In command line enter the trunk directory. First let’s make sure that it’s up-to-date by running
svn update. Note the revision number that will be returned when the command is finished.
Updating '.': At revision 132.
We are ready to create our branch now. The process is very simple: we create a remote branch then run
svn update to pull it to our local machine. This approach can be slow, however, because it requires Subversion to transfer files over the network. We can do a little trick instead that will help avoid transferring files over the network and should save us some time. We will create a branch remotely, then create another one locally and then make Subversion think that it’s the same branch.
First let’s create the remote branch. Run the following command, changing
@132 to your revision number and setting your own relevant branch name and commit message. Note: the following implies our own folder structure and yours could be different.
svn copy ^/trunk@132 ^/branches/ticket-15 -m "Branch for ticket #15"
Note, the caret
^ symbol is just a shorthand notation for your repository URL. Now when the new branch is created we need to reproduce it on our local machine too. For now it only exists in Beanstalk. Run the following comand to create a local branch:
ditto ./ ../branches/ticket-15
Now here’s the trick. We need to make Subversion think that both the remote branch that we created, and the local one is the same branch. For this we need to use the
svn switch command to change the branch’s URL:
svn switch ^/branches/ticket-15 ../branches/ticket-15 --ignore-externals
That’s it, your new branch is now ready. To quickly recap, we created a remote branch, duplicated our local branch and then switched it to point to the new remote branch. We’ve performed this with little network overhead and no need to download a full copy of our trunk.
Merging other people’s work
As you work on your new branch other team members may have made or merged changes to the trunk that you would like to have in your branch. You can use the following steps to merge in changes from other branches.
In command line enter the directory of the branch you’re working on. Now, to merge in the changes from trunk, run the following:
svn merge ^/trunk
This performs a synchronize merge with your branch, catching up to the tip of the branch you’re merging in. After the merge you can commit the changes that have been applied.
svn commit -m "Synchronize with trunk"
Reintegrating your work
Once you’re finished working on your branch, you’ll want to reintegrate the changes back in to trunk. First you should synchronize merge the trunk in to your branch using the steps above. This gives you the opportunity to resolve any conflicts and help make your reintegration more concise. Before you reintegrate, ensure the two branches you will be using are in a clean state (have no uncommitted changes.)
In command line enter the directory of the branch that you want to reintegrate your work in to (usually trunk) and run
svn update. Now you can reintegrate your working branch by running:
svn merge --reintegrate ^/branches/ticket-15@139
Don’t forget to change 139 with an actual revision number of the head of your branch. The reintegrate merge will merge all of the changes that are unique to your working branch and skip changes that are already in the trunk. You can now review the changes locally, resolve any conflicts, build and test.
When you are happy with the merge you can commit with:
svn commit -m "Reintegrate the ticket #15 branch in to trunk"
And finally delete the branch that you reintegrated:
svn delete ^/branches/ticket-15 -m "Delete the ticket #15 branch"
There is one caveat to keep in mind with reintegrating and deleting the branch, essentially there is a race condition between the two. If another developer were to make additional commits after you have reintegrated the branch, then these will be missing. It’s worth checking the commit log after deleting the branch to ensure that this hasn’t happened or, better still, use locking.