Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments


This spec recommends adding a new option to the branch command called --feature for creating a local feature branch. When this new option is specified, Bazaar will:

  • require a target name to be given
  • assume the target is in the same place as the base branch
  • make the new branch without a tree if the source has no tree
  • intelligently stack the new branch on the base branch.

Given how frequently feature branches are created, having a short form of --feature (-f say) is recommended.


The UI for common Use Cases needs to be as smooth as can be, reflecting what the user is trying to achieve and hiding implementation details where it can. The primary intention when branching locally (start me a new line of development) is different to the primary intention when branching from a remote location (grab me my copy of that project). It is therefore worthwhile to capture this intent via a new option, intelligently applying appropriate policies. Using an option that reflects the logical action allows us to hide technical ideas (like repositories and stacking) from new users.

Putting the target in the same location as the source and reusing the tree-vs-no-tree setting simplifies the UI when the shared-tree-across-branches setup is being used.

Stacking the new branch on the base branch has several benefits:

  • Garbage collection of the new commits is implicit - simply delete the feature branch when you're done
  • Disk resource consumption is greatly reduced without requiring a shared repository to be established in advance
  • Performance is greatly improved outside a shared repository (down from 4 minutes to a few seconds for Emacs).

The default user model

At the core of the UI design there needs to be a way of working that we think is the Right Way for most projects. I believe that user model ought to be feature branching. In this model, one branch is kept as a mirror of "trunk" and each unit-of-work (i.e. bug-fix or enhancement) gets its own "feature branch".

Here are the current set of recipes for using this model in Bazaar ...

To set up:

  bzr init-repo project
  cd project
  bzr branch URL trunk

To start a feature branch:

  bzr branch trunk featureX
  cd featureX

To work:

  (make changes)
  bzr commit
  (make changes)
  bzr commit

To publish changes to a mailing list for review & approval:

  bzr send

To publish changes to a public branch (that can then be registered as a Launchpad merge request, say):

  bzr push [URL]

So the core problem with the current UI design is that users need to understand shared repositories and set one up in advance. If they fail to do this, the performance and disk consumption is lousy. There's also the problem that commits made on experimental feature branches go into the shared repository and never get cleaned out. They really ought to disappear when the experimental feature branch is removed instead.

Proposed UI enhancements

Here's are the proposed changes to the feature branching recipes given above.

To set up:

  bzr branch URL trunk

To start a feature branch:

  bzr branch -f trunk featureX
  cd featureX


Instead of adding a new option, a new command could be added (called fbranch, local, feature or twig say). While that command could effectively hide some of the options on branch, it would be less discoverable than using the proposed new option. Users can always add an alias to bazaar.conf that makes feature branching feel like a separate command if they wish to.

It might be worthwhile for the source branch to record what feature branches are based on it. bzr info -v on source could list the dependent feature branches. (If we added a command for safely deleting a branch, it could check that list was empty before deleting source.)

Stacking has it's risks but I think it works sweetly here given a core assumption of the feature branching model: the trunk mirror ought to always exist and is the place to base new lines of development on.

Implementation notes

We could implement this in 1.15, but it really needs our default branch format changed to something later than pack-0.92 to leverage stacking behind the scenes.