(photo by Subversion)

Version control is a must for projects such as ours with a geographically diverse team of developers each working on any number of these projects at the same time.

Subversion, because of its similarities to CVS, has made it easy for us to reap the benefits of version control with minimal effort. However, there is a lot more to subversion than update and commit. There is also branching and merging, but unlike CVS the concept is easier in subversion, at least, in my experience.

So when does branching become necessary or useful? Branching allows you to create a copy of the portion of your project to another location in the repository. This allows one developer to work on features that may not be part of the main line of development without disrupting the work of other developers.

As an example, I have Ajax File Storage 0.8 running on one of our client projects and they have recently requested for new features. Now I can just as simply work on the trunk or main line of development without branching but I'll probably have a hard time if I need to fix bugs and do minor tweaks. If I don't branch, I would have to cherry pick the changes I commit to the repository to ensure that unfinished code doesn't get committed and pushed to production.

So the safest and most appropriate solution is to create a branch of Ajax File Storage and work on the new features on this branch. Bug fixes and minor tweaks are then committed to the trunk or the main line of development.

Later on, when I am finished with the new features on the separate branch, I can use svn merge to merge changes from the branch back to the trunk.

Here's a step-by-step guide on how I went about branching and merging. But before trying this out, it would help if:

• you know basic subversion
• you have a repository viewer like viewsvn or viewvc

1. Although not necessary, we decided to follow the recommended layout of a version control project in subversion where you start out with 3 directories, namely, trunk, tags, and branches (eg. http://code.solutiongrove.com/svn/viewvc.cgi/monitorex/). Trunk is the main line of development. Tags and branches, as you might guess, will contain directories that have branched out from the trunk.
2. So I am concerned now with working on ajax-filestorage-ui which is in the trunk http://code.solutiongrove.com/svn/viewvc.cgi/monitorex/trunk/packages/ajax-filestorage-ui/
3. First thing is to create a branch of that code where I will add new features. In a terminal, inside the packages/ directory where ajax-filestorage-ui is located, I execute

		svn cp ajax-filestorage-ui svn+ssh://code@code.solutiongrove.com/home/svnrepo/solutiongrove/monitorex/branches/ajax-filestorage-ui -m   "create a branch to work on new ajaxfs features"	
	

4. This will create a branch in the branches directory http://code.solutiongrove.com/svn/viewvc.cgi/monitorex/branches/ajax-filestorage-ui/
5. The next thing that needs to be done is to switch the code on your working copy to use the code in the branches directory of the repository. This can be accomplished by executing the following command inside the packages/ directory of your working copy,

		svn switch svn+ssh://code@code.solutiongrove.com/home/code/svnrepo/solutiongrove/monitorex/trunk/packages/ajax-filestorage-ui/ ajax-filestorage-ui/	
	

At this pioint,

• you have successfully created a branch of a package in your project
• you have successfully switched over the code in your working copy to use this new branch

I can now start working on the new features. 

After I'm done with programming, the next task will be merging changes back to the main line of development.

Before merging, I should look at the repository viewer and check what revisions in the branch I want to merge back to the trunk.  Looking at http://code.solutiongrove.com/svn/viewvc.cgi/monitorex/branches/ajax-filestorage-ui/, I found out that there are 2 revisions, namely, 2557 and 2558 that I want to merge back to the trunk.

Here's how I went about merging:

1. Made sure all changes have been committed, then switched the code in the working copy from the branch back to the trunk by executing the following in the packages directory of my working copy.

		svn switch svn+ssh://code@code.solutiongrove.com/home/code/svnrepo/solutiongrove/monitorex/trunk/packages/ajax-filestorage-ui/ .
	

2. Then, I executed the svn merge command to merge revision 2557 in the branches directory of the repository in the trunk. Notice in the command below I had to specify a revision 2554. Revision 2554 is the revision when the branch was created. The merge command is essentailly saying, get all the changes between 2554 and 2557 from branches/ajax-filestorage-ui and merge it to the current working copy which is set to trunk.

		svn merge -r 2554:2557 svn+ssh://code@code.solutiongrove.com/home/code/svnrepo/solutiongrove/monitorex/branches/ajax-filestorage-ui	
	

3. I did the same for revision 2558

		svn merge -r 2554:2558 svn+ssh://code@code.solutiongrove.com/home/code/svnrepo/solutiongrove/monitorex/branches/ajax-filestorage-ui	
	

If all goes well, then you would have an updated working copy with the changes from your branch. You should probably test the code and check to be sure that the merging worked.

You can then finally commit the changes to the repository using svn commit and svn update your production system.

svn commit -m "commit revisions 2558 and 2557, merge new features from branch to trunk"