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``.
69
.. The following text is hidden because bug 375013 breaks the example.
70
When bug 375013 is fixed, we should unhide this text.
71
- Andrew Bennetts, 10 March 2010
73
.. If the local branch was created as a stacked branch, then you can
74
.. use the ``--stacked`` option to ``push`` and the *stacked-on* location
75
.. will be implicit. For example::
77
.. bzr branch --stacked source-url my-dir
80
.. bzr commit -m "fix bug"
84
Limitations of stacked branches
85
-------------------------------
87
Currently, you cannot commit to a stacked branch, due to `bug 375013`_.
89
.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
91
The important thing to remember about a stacked branch is that the
92
stacked-on branch needs to be available for almost all operations. This is
93
not an issue when both branches are local or both branches are on the
96
Similarly, because most of the history is stored in the stacked-on repository,
97
operations like ``bzr log`` can be slower when the stacked-on repository is
98
accessed via a network.
101
Changing branch stacking
102
------------------------
104
Stacking of existing branches can be changed using the ``bzr reconfigure``
105
command to either stack on an existing branch, or to turn off stacking.
106
Be aware that when ``bzr reconfigure --unstacked`` is used, bzr will
107
copy all the referenced data from the stacked-on repository into the
108
previously stacked repository. For large repositories this may take
109
considerable time and may substantially increase the size of the