Branching and Merging with Subversion

From WikiJava

Subversion offers a powerful tool for controlling the branching and merging of your projects. This tutorial will show and explain you how to create a branch in your project and then how to properly merge your branch in the trunk.

Contents 1 the article 2 introduction 3 How to create a branch 4 How to merge a branch in the trunk 5 Comments from the users

the article

introduction

Lets say, for example, you are working on your trunk which is at the URL: http:\\svn.svnexample.org\project\trunk\ and you want to introduce a new developer ("developer1") who will be working on a new feature ("feature1") for your software. You want your new developer to be versioning, but you don't want him to influence your work on the main trunk.

What you want is you both to be working on the same code, using the same repository, but without influencing each other.

This is a typical situation in which you want to create a new branch for developer1, so he can work and commit to his branch without affecting the other developers.

What will you do is to create a copy (branch) of the code for developer1 so he will be working on his branch and not directly editing the main block of code (the trunk). The life cycle of the branch starts when the branch is created and at that moment is an exact copy of the trunk. After the branch is created the trunk and the branch can be developed independently, as they were completely separated. When developer1 is done, and the feature1 is ready the new code must be mixed (merged) with the main source code in order for feature1 to be included in the official project.

The situation is now interesting:

• The branch was modified by developer1 and is now different from the moment in which it was created and in which it was identical to the trunk.
• the trunk has been modified by the other developers and is now different from the original code the branch was made from.

It is obvious given these two points that merging is not an easy task, both the trunk and the branch have evolved independently, and only the developers know what has been made and for what reason. The process of merging cannot be made automatic, since there may be conflicts between the modifications made in both versions. So it always requires at least one of the developers.

Fortunately Subversion implements the merge command, that is able to save a lot of time in this process.

svn merge can automatically mix all the modifications of the trunk and of the branch leaving to the developer only to solve the eventual conflicts found in the code.

I'll show you how to use this powerful feature in the following paragraphs.

How to create a branch

To create a branch is very easy in subversion.

The command:

svn copy http:\\svn.svnexample.org\project\trunk\ \
      http:\\svn.svnexample.org\project\branches\feature1
svn commit -m "creating branch for feature1"

In subversion to create a branch corresponds to the operation of copying your code via the copy command.

The copy command copies the files in your repository maintaining the history of the original file. After the commit the repository will then contain the base files for the trunk, the changelog information for all the commits performed on the trunk before the copy and the last commit in which svn copy created the new branch.

This contains just the structure for saving the changes and not the whole file information. The new branch then doesn't occupy on the disk any space, (except from few control bytes) and when developer1 will start working on it, each commit will only contain the space from the changelog.

If we do a svn log on the branch we will see that the history of the files is the same as when we do svn log on the trunk.

See the help for copy for more details.

svn help copy

How to merge a branch in the trunk

After you've worked on the branch and you verified that your feature is ready to be included in the main trunc of your code you can proceed to the next step, which is the merge.

To merge you normally need to pass to subversion information from three different resources in your code:

• The head version of the main trunk
• The head version of your branch
• The common ancestor version which represents the last moment in which the trunk and the branch were identical to each other.

Note that these are the most common sources that you will use, though in some cases this may not be the case.

While the head of the main trunk and of your branch are obviously needed, since they contain the data that is to be merged into the trunk, the last piece of information, the common ancestor may require some explanation.

The common ancestor gives information on what whas changed on the trunk and on the branch since the creation of the branch itself. Without the common ancestor Subversion would just see two different versions of the code and will not be able to understand what was changed where. In this situation the merge would not be possible.

Fortunately Subversion keeps track of when the copy operation has been made on a file so to find the common ancestor you just type

svn log --stop-on-copy

This shows the log of the current path going back in time until it finds a commit with the copy operation. The last result in the given list shows the revision number of the commit of the copy. This revision is our common ancestor.

Once you have found the common ancestor you can proceed to the actual merge. To do so change to the directory containing the trunk (the directory that you want to receive the updates from the branch) and use the command:

svn merge -r 7:head http:\\svn.svnexample.org\project\branches\feature1

let see it in detail:

svn log --stop-on-copy
svn merge -r 7:head http:\\svn.svnexample.org\project\branches\feature1
svn status
svn commit -m "merging feature1 branch"

Comments from the users

To be notified via mail on the updates of this discussion you can login and click on watch at the top of the page

Comments on wikijava are disabled now, cause excessive spam.