Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments


This spec recommends several tweaks to existing commands to make the shared-tree-across-branches workspace model easier to setup and use.


There are numerous scenarios where having a single tree and switching it across branches is a more efficient way of developing than using separate working trees. These include:

  • C/C++ development where it's undesirable to have multiple copies of the built artifacts around
  • Web development where a web server is configured to point into a single location (and changing that configuration is an admin drag)
  • Version control of fixed directory locations (like /etc).

While Bazaar already supports a git-like workspace setup with one working tree shared across multiple branches, it takes a fair amount of setting up and understanding of advanced features. We need to simplify this and better document the new recipes so that it's more accessible to new users.

Many long-time users of Bazaar are unaware that Bazaar can even do this. The new recipes and documentation should help make it more popular.

Current UI

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

To set up:

  bzr init-repo --no-trees project
  cd project
  bzr branch URL trunk
  bzr checkout --lightweight trunk work

To start a feature branch:

  bzr branch ../trunk ../featureX
  bzr switch ../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]

Problem with the current UI design include:

  • 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.

  • Users need to understand lightweight vs heavyweight checkouts and accidentally using the (current) default type (heavyweight) will do the wrong thing
  • Users needs to think about and specify potentially long paths to the branch and switch commands.

Proposed UI enhancements

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

To set up with branches in a specified location:

  bzr branch --no-tree URL url-to-trunk
  bzr checkout url-to-trunk work
  cd work

To start a feature branch (from inside the checkout):

  bzr branch -f :trunk featureX
  bzr switch featureX

In addition to the changes flagged as part of the feature branching and simple checkouts specs, the required changes are:

  • The "basename" of the original branch location for a checkout should be remembered and :foo should refer to the foo directory below there. So the basename recorded for bzr checkout d:\projectX\trunk would be d:\projectX while that recorded for bzr checkout lp:~bzr/bzr/ would be lp:~bzr/bzr.

  • If just a name is given to the switch command, that name should assumed to be relative to the remembered basename. (Apparently Bazaar does something similar to this already, so perhaps just the documentation needs updating to explain that.)

The above can be optimised to support colocated branches:

  bzr branch --shared-tree URL work
  cd work

Or if starting from scratch instead of an existing branch:

  bzr init --shared-tree work
  cd work

Colocated branches could be stored under .bzr/branches say, probably in a shared repository. That detail would be hidden from the user though by the :xxx magic mentioned above.


It might be worth extending branch with a --switch option that switches the current checkout to the newly created branch.

If there is an unacceptable risk of :xxx clashing with the current namespace (:parent, etc.), then the syntax can easily be tweaked to ::xxx, ^xxx or whatever. Alternatively, the current namespace can be disambiguated via config:parent (say) when required.

Unlike cbranch (part of BzrTools), I've deliberately avoided requiring the user to add settings to locations.conf. We could always store information in there if required but the UI needs to be complete and smooth enough that editing a configuration file isn't required.

trunk and work can now easily be in completely different locations - the checkout doesn't need to be a sister directory to the branches within a shared repository.

Implementation notes

Technically, we could implement this in 2.0. But it depends on the feature branching and simple checkouts specs being agreed to and implemented beforehand.