← 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

  • Committer: Ian Clatworthy
  • Date: 2007-08-13 14:33:10 UTC
  • mto: (2733.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2734.
  • Revision ID: ian.clatworthy@internode.on.net-20070813143310-twhj4la0qnupvze8
Added Quick Start Summary

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`` 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 sftp://host/project --stacked sftp://host/user/stacked-branch
82
 
 
83
 
This usage fits the scenario described in the Motivation section.
84
 
 
85
 
 
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
89
 
 
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::
93
 
.. 
94
 
..   bzr branch --stacked source-url my-dir
95
 
..   cd my-dir
96
 
..   (hack, hack, hack)
97
 
..   bzr commit -m "fix bug"
98
 
..   bzr push --stacked
99
 
 
100
 
 
101
 
Limitations of stacked branches
102
 
-------------------------------
103
 
 
104
 
Currently, you cannot commit to a stacked branch, due to `bug 375013`_.
105
 
 
106
 
.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
107
 
 
108
 
The important thing to remember about a stacked branch is that the
109
 
stacked-on branch needs to be available for almost all operations. This is
110
 
not an issue when both branches are local or both branches are on the
111
 
same server.
112
 
 
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.
116
 
 
117
 
 
118
 
Changing branch stacking
119
 
------------------------
120
 
 
121
 
Stacking of existing branches can be changed using the ``bzr reconfigure``
122
 
command to either stack on an existing branch, or to turn off stacking.
123
 
Be aware that when ``bzr reconfigure --unstacked`` is used, bzr will
124
 
copy all the referenced data from the stacked-on repository into the
125
 
previously stacked repository.  For large repositories this may take
126
 
considerable time and may substantially increase the size of the
127
 
repository.