4
What is a stacked branch?
5
-------------------------
7
A stacked branch is a branch that knows how to find revisions
8
in another branch. Stacked branches store just the
9
unique revisions, making them faster to create and more
10
storage efficient. In these respects, stacked branches are
11
similar to shared repositories. However, stacked branches have
14
* The new branch can be in a completely different location to the
15
branch being stacked on.
17
* Deleting the stacked branch really deletes the revisions (rather
18
than leaving them in a shared repository).
20
* Security is improved over shared repositories, because the stacked-on
21
repository can be physically readonly to developers committing to stacked
24
These benefits make stacked branches ideal for various scenarios
25
including experimental branches and code hosting sites.
28
Creating a stacked branch
29
-------------------------
31
To create a stacked branch, use the ``stacked`` option of the branch command.
34
bzr branch --stacked source-url my-dir
36
This will create ``my-dir`` as a stacked branch with no local revisions.
37
If it is defined, the public branch associated with ``source-url`` will be
38
used as the *stacked-on* location. Otherwise, ``source-url`` will be the
39
*stacked-on* location.
42
Creating a stacked checkout
43
---------------------------
45
Direct creation of a stacked checkout is expected to be supported soon.
46
In the meantime, a two step process is required:
48
1. Create a stacked branch as shown above.
50
2. Convert the branch into a checkout using either the ``reconfigure``
54
Pushing a stacked branch
55
------------------------
57
Most changes on most projects build on an existing branch such as the
58
*development trunk* or *current stable* branch. Creating a new
59
branch stacked on one of these is easy to do using the ``push``
62
bzr push --stacked-on reference-url my-url
64
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
65
and only contains the revisions in the current branch that are not already
66
in the branch at ``reference-url``.
68
If the local branch was created as a stacked branch, then you can
69
use the ``--stacked`` option to ``push`` and the *stacked-on* location
70
will be implicit. For example::
72
bzr branch --stacked source-url my-dir
75
bzr commit -m "fix bug"
79
Limitations of stacked branches
80
-------------------------------
82
The important thing to remember about a stacked branch is that the
83
stacked-on branch needs to be available for almost all operations. This is
84
not an issue when both branches are local or both branches are on the
added
removed
doc/en/user-guide/stacked.txt
