Once you get the hang of working in version control systems like Subversion, you'll want to make use of great concepts such as branching. Branching lets you manage different versions of your code base in parallel for things like maintaining older versions, the development of new features and so on. But no sooner do you start branching, then you'll need to start merging.
Merging is not all that difficult, but if you are doing it for the first time or you only do it infrequently, you can get a bit knotted trying to work out what you're supposed to be doing. What follows is a little crib sheet for merging. Just happens to be using Subclipse for Eclipse but the same steps apply for any Subversion client.
Merging From A Maintenance Branch to "trunk"
If you have a production release of a code base and you have started work on the next version, you may want to keep a maintenance branch of the currently live code base. This allows you to get gung-ho into the new development (say on "trunk") while any minor changes you need to implement on the live site can be done on your maintenance branch (for example "./branches/p400"). From time to time, you will want to make sure any bug fixes you have done on the production site are merged into the new developments the team are working on.
In this example, we're merging the changes on the v4.0 maintenance branch for the FarCry Core framework, back into the trunk where development on v5.0 is racing ahead at a blistering pace. We want to make sure we're not fixing bugs for existing installations only to have them reappear in the new release -- so we make it a rule to merge as regularly as practical.
Regardless of what you are doing the process is nearly always the same. And hopefully folks can apply this cheat-sheet to their own development environments.
- First of all make sure you are up to date. Update your working copy of the target branch, ie. where you are merging into. In this example we're working on the trunk of "core" and we want to grab the changes that have happened in the maintenance branch and merge them.
- Resolve any conflicts. There should be no conflicts at this stage between the working copy and the repository.
- Select the SVN merge option on the working copy. In Eclipse this is going to be found under the "Team" menu and called "Merge Branch".
- Change the From URL to the specific branch you want to be merged into your working copy. In this example we're looking for the p400 maintenance branch (./core/branches/p400).
- Change the From Revision to the last revision that was merged into the target branch. Essentially you don't want to keep merging the whole branch history, you just want to include those changes since the last time you merged. There is no easy way to determine the last merge point at this time in Subversion. You have to review your message log and look for the last commit that talks about merging. If you are disciplined about the commit messages you use for merging this should be easy (see below). Make a note of what that revision is -- you'll need this later when you commit your changes.
- Change the To Revision to the latest (i.e. head). Make a note of what that revision is -- you'll need this later when you commit your changes.
- Click Merge and wait. Depending on how big the differences are this may be quick or Eclipse my just fall over. If you have such an enormous change that you can't get it done in Eclipse you may need to make the range of revisions you are merging smaller. Or you may even have to skip certain revisions and do them manually if they are massive. We've had this problem from time to time when updating large third-party libraries. The vast majority of the time you will be fine.
- Review changes and resolve conflicts. Once the merge is complete, look through the changes made to your working copy and make sure you address any conflicts you find.
- Once all the changes have been resolved in the target working copy, check them in with a single commit. The reason you're not doing lots of commits is that these are changes that should have been documented in the branch from which you merged. The commit message needs to be in a specific format that details the merge and is easy to find in the future. We use the following format, but you can use anything that works for you -- as long as you stick to it.
Merging [source] to [target]; [repository]. Merge rev [start]:[end]
In our example, that would translate to:
Merging p400 to trunk; core. Merge rev 2356:2551.
PS. Thanks to Daemonite Blair for helping out on this post.
Related Blog Posts