1
1
Using stacked branches
2
2
======================
7
If you are working on a project, and you have read access to whose
8
public repository but do not have write access to it, using stacked
9
branches to backup/publish your work onto the same host of the public
10
repository might be an option for you.
12
Other scenarios for stacked branch usage include experimental branches
13
and code hosting sites. For these scenarios, stacked branches are
14
ideal because of the benefits it provides.
4
17
What is a stacked branch?
5
18
-------------------------
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
20
A stacked branch is a branch that knows how to find revisions in
21
another branch (the stacked-on branch). Stacked branches store just
22
the unique revisions that are not in the stacked-on branch, making
23
them faster to create and more storage efficient. In these respects,
24
stacked branches are similar to shared repositories. However, stacked
25
branches have additional benefits:
14
27
* The new branch can be in a completely different location to the
15
28
branch being stacked on.
21
34
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
38
Creating a stacked branch
29
39
-------------------------
64
74
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
65
75
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"
76
in the branch at ``reference-url``. In particular, ``my-url`` and
77
``reference-url`` can be on the same host, and the ``--stacked`` option
78
can be used additionally to inform ``push`` to reference the
79
revisions in ``reference-url``. For example::
81
bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
83
This usage fits the scenario described in the Motivation section.
86
.. The following text is hidden because bug 375013 breaks the example.
87
When bug 375013 is fixed, we should unhide this text.
88
- Andrew Bennetts, 10 March 2010
90
.. If the local branch was created as a stacked branch, then you can
91
.. use the ``--stacked`` option to ``push`` and the *stacked-on* location
92
.. will be implicit. For example::
94
.. bzr branch --stacked source-url my-dir
97
.. bzr commit -m "fix bug"
79
101
Limitations of stacked branches
80
102
-------------------------------
104
Currently, you cannot commit to a stacked branch, due to `bug 375013`_.
106
.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
82
108
The important thing to remember about a stacked branch is that the
83
109
stacked-on branch needs to be available for almost all operations. This is
84
110
not an issue when both branches are local or both branches are on the
113
Similarly, because most of the history is stored in the stacked-on repository,
114
operations like ``bzr log`` can be slower when the stacked-on repository is
115
accessed via a network.
88
118
Changing branch stacking
89
119
------------------------
added
removed
doc/en/user-guide/stacked.txt
