← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/stacked.txt

Major code cleanup.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/stacked.txt
 
1
Using stacked branches
 
2
======================
 
3
 
 
4
Motivation
 
5
----------
 
6
 
 
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.
 
11
 
 
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.
 
15
 
 
16
 
 
17
What is a stacked branch?
 
18
-------------------------
 
19
 
 
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:
 
26
 
 
27
* The new branch can be in a completely different location to the
 
28
  branch being stacked on.
 
29
 
 
30
* Deleting the stacked branch really deletes the revisions (rather
 
31
  than leaving them in a shared repository).
 
32
 
 
33
* Security is improved over shared repositories, because the stacked-on
 
34
  repository can be physically readonly to developers committing to stacked
 
35
  branches.
 
36
 
 
37
 
 
38
Creating a stacked branch
 
39
-------------------------
 
40
 
 
41
To create a stacked branch, use the ``stacked`` option of the branch command.
 
42
For example::
 
43
 
 
44
  bzr branch --stacked source-url my-dir
 
45
 
 
46
This will create ``my-dir`` as a stacked branch with no local revisions.
 
47
If it is defined, the public branch associated with ``source-url`` will be
 
48
used as the *stacked-on* location. Otherwise, ``source-url`` will be the
 
49
*stacked-on* location.
 
50
 
 
51
 
 
52
Creating a stacked checkout
 
53
---------------------------
 
54
 
 
55
Direct creation of a stacked checkout is expected to be supported soon.
 
56
In the meantime, a two step process is required:
 
57
 
 
58
1. Create a stacked branch as shown above.
 
59
 
 
60
2. Convert the branch into a checkout using either the ``reconfigure``
 
61
   or ``bind`` command.
 
62
 
 
63
 
 
64
Pushing a stacked branch
 
65
------------------------
 
66
 
 
67
Most changes on most projects build on an existing branch such as the
 
68
*development trunk* or *current stable* branch. Creating a new
 
69
branch stacked on one of these is easy to do using the ``push``
 
70
command like this::
 
71
 
 
72
  bzr push --stacked-on reference-url my-url
 
73
 
 
74
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
 
75
and only contains the revisions in the current branch that are not already
 
76
in the branch at ``reference-url``. In particular, ``my-url`` and
 
77
``reference-url`` can be on the same host, and the ``--stacked-on`` option
 
78
can be used additionally to inform ``push`` to reference the
 
79
revisions in ``reference-url``. For example::
 
80
 
 
81
  bzr push --stacked-on bzr+ssh://host/project bzr+ssh://host/user/stacked-branch
 
82
 
 
83
This usage fits the scenario described in the Motivation section.
 
84
 
 
85
You can also use the ``--stacked`` option without specifying ``--stacked-on``.
 
86
This will automatically set the *stacked-on* location to the parent branch of
 
87
the branch you are pushing (or its ``public_location`` if configured).  For
 
88
example::
 
89
 
 
90
  bzr branch source-url my-dir
 
91
  cd my-dir
 
92
  (hack, hack, hack)
 
93
  bzr commit -m "fix bug"
 
94
  bzr push --stacked
 
95
 
 
96
You can combine ``bzr branch --stacked`` and ``bzr push --stacked`` to work on a
 
97
branch without downloading or uploading the whole history::
 
98
 
 
99
  bzr branch --stacked source-url my-dir
 
100
  cd my-dir
 
101
  (hack, hack, hack)
 
102
  bzr commit -m "fix bug"
 
103
  bzr push --stacked
 
104
 
 
105
 
 
106
Limitations of stacked branches
 
107
-------------------------------
 
108
 
 
109
The important thing to remember about a stacked branch is that the stacked-on
 
110
branch needs to be accessible for almost all operations.  This is not an issue
 
111
when both branches are local, or when both branches are on the same server and
 
112
the stacked-on location is a relative path.  But clearly a branch hosted on a
 
113
server with a stacked-on location of ``file:///...`` is not going to work for
 
114
anyone except the user that originally pushed it.  It's a good idea to configure
 
115
``public_location`` to help prevent that.
 
116
 
 
117
Similarly, because most of the history is stored in the stacked-on repository,
 
118
operations like ``bzr log`` can be slower when the stacked-on repository is
 
119
accessed via a network.
 
120
 
 
121
If a stacked branch is in a format older than 2a, you cannot commit to it due to
 
122
`bug 375013`_.
 
123
 
 
124
.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
 
125
 
 
126
 
 
127
Changing branch stacking
 
128
------------------------
 
129
 
 
130
Stacking of existing branches can be changed using the ``bzr reconfigure``
 
131
command to either stack on an existing branch, or to turn off stacking.
 
132
Be aware that when ``bzr reconfigure --unstacked`` is used, bzr will
 
133
copy all the referenced data from the stacked-on repository into the
 
134
previously stacked repository.  For large repositories this may take
 
135
considerable time and may substantially increase the size of the
 
136
repository.