The use of local branches

Contents

Introduction

Heavy new stuff may take quite a long time to be stable and mature enough to be shared even with other developpers. Mercurial, as a distributed SCM, allows to keep a fine-grain history through local commits without letting the genie out of the bottle. It is only through merging and pushing the new changesets to some common repository that new things gets available to others. Yet it is quite frequent that one would like to work on heavy stuff while maintaining the ability to perform fixes and smaller task on the trunk, without releasing into the open experimental and unfinished changesets. With mercurial, there are two natural answers to this problem : cloning and branching.

Making a new clone and working the heavy stuff in it is probably the simplest way: things get naturally separated since they happen in distinct folders. However, maintaining and building multiple clones may prove to be quite demanding, in terms of physical spaces and working folder organization. In this short article, we will investigate the other option: branching. We will demonstrate how to :

Start a new local branch,

Work in it,

Switch to the trunk and back,

Close the branch if it appears to be a dead-end,

Merge the branch with the trunk when it is ready.

Creating a new branch and working in it

The first step toward local branching is to create a new branch, which can be done by using:

Do not try to force pushing (using the -f option or --new-branch)! In OTB it is forbidden to push new remote branches (actually this may even be forbidden on the server side). To push your changesets made to the trunk, you need to specify the head you want to push. The topmost head of the trunk is the one with no branch properties:

You therefore need to specify the correct changeset short (or long) id to push:

$ hg push -r 16325

Last, you can switch back to your local branch running:

$ hg update new_heavy_feature

Work done: merging with trunk

Once the work on the local branch is completed and you want to share it with others, you can rebase your branched changesets on trunk. If you need to, you ensure you are on the trunk and rebase incoming changeset: