Using stacked branches

What is a stacked branch?

A stacked branch is a branch that knows how to find revisions in another branch. Stacked branches store just the unique revisions, making them faster to create and more storage efficient. In these respects, stacked branches are similar to shared repositories. However, stacked branches have additional benefits:

• The new branch can be in a completely different location to the branch being stacked on.
• Deleting the stacked branch really deletes the revisions (rather than leaving them in a shared repository).
• Security is improved over shared repositories, because the stacked-on repository can be physically readonly to developers committing to stacked branches.

These benefits make stacked branches ideal for various scenarios including experimental branches and code hosting sites.

Creating a stacked branch

To create a stacked branch, use the stacked option of the branch command. For example:

bzr branch --stacked source-url my-dir

This will create my-dir as a stacked branch with no local revisions. If it is defined, the public branch associated with source-url will be used as the stacked-on location. Otherwise, source-url will be the stacked-on location.

Creating a stacked checkout

Direct creation of a stacked checkout is expected to be supported soon. In the meantime, a two step process is required:

1. Create a stacked branch as shown above.
2. Convert the branch into a checkout using either the reconfigure or bind command.

Pushing a stacked branch

Most changes on most projects build on an existing branch such as the development trunk or current stable branch. Creating a new branch stacked on one of these is easy to do using the push command like this:

bzr push --stacked-on reference-url my-url

This creates a new branch at my-url that is stacked on reference-url and only contains the revisions in the current branch that are not already in the branch at reference-url.

If the local branch was created as a stacked branch, then you can use the --stacked option to push and the stacked-on location will be implicit. For example:

bzr branch --stacked source-url my-dir
cd my-dir
(hack, hack, hack)
bzr commit -m "fix bug"
bzr push --stacked

Limitations of stacked branches

The important thing to remember about a stacked branch is that the stacked-on branch needs to be available for almost all operations. This is not an issue when both branches are local or both branches are on the same server.

Changing branch stacking

Stacking of existing branches can be changed using the bzr reconfigure command to either stack on an existing branch, or to turn off stacking. Be aware that when bzr reconfigure --unstacked is used, bzr will copy all the referenced data from the stacked-on repository into the previously stacked repository. For large repositories this may take considerable time and may substantially increase the size of the repository.