/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

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

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-02-11 04:02:41 UTC
  • mfrom: (5017.2.2 tariff)
  • Revision ID: pqm@pqm.ubuntu.com-20100211040241-w6n021dz0uus341n
(mbp) add import-tariff tests

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/stacked.txt
1
1
Using stacked branches
2
2
======================
3
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
4
What is a stacked branch?
18
5
-------------------------
19
6
 
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:
 
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
 
12
additional benefits:
26
13
 
27
14
* The new branch can be in a completely different location to the
28
15
  branch being stacked on.
34
21
  repository can be physically readonly to developers committing to stacked
35
22
  branches.
36
23
 
 
24
These benefits make stacked branches ideal for various scenarios
 
25
including experimental branches and code hosting sites.
 
26
 
37
27
 
38
28
Creating a stacked branch
39
29
-------------------------
41
31
To create a stacked branch, use the ``stacked`` option of the branch command.
42
32
For example::
43
33
 
44
 
  brz branch --stacked source-url my-dir
 
34
  bzr branch --stacked source-url my-dir
45
35
 
46
36
This will create ``my-dir`` as a stacked branch with no local revisions.
47
37
If it is defined, the public branch associated with ``source-url`` will be
69
59
branch stacked on one of these is easy to do using the ``push``
70
60
command like this::
71
61
 
72
 
  brz push --stacked-on reference-url my-url
 
62
  bzr push --stacked-on reference-url my-url
73
63
 
74
64
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
75
65
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
 
  brz 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
 
  brz branch source-url my-dir
91
 
  cd my-dir
92
 
  (hack, hack, hack)
93
 
  brz commit -m "fix bug"
94
 
  brz push --stacked
95
 
 
96
 
You can combine ``brz branch --stacked`` and ``brz push --stacked`` to work on a
97
 
branch without downloading or uploading the whole history::
98
 
 
99
 
  brz branch --stacked source-url my-dir
100
 
  cd my-dir
101
 
  (hack, hack, hack)
102
 
  brz commit -m "fix bug"
103
 
  brz push --stacked
 
66
in the branch at ``reference-url``.
 
67
 
 
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::
 
71
 
 
72
  bzr branch --stacked source-url my-dir
 
73
  cd my-dir
 
74
  (hack, hack, hack)
 
75
  bzr commit -m "fix bug"
 
76
  bzr push --stacked
104
77
 
105
78
 
106
79
Limitations of stacked branches
107
80
-------------------------------
108
81
 
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 ``brz 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
 
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
 
85
same server.
125
86
 
126
87
 
127
88
Changing branch stacking
128
89
------------------------
129
90
 
130
 
Stacking of existing branches can be changed using the ``brz reconfigure``
 
91
Stacking of existing branches can be changed using the ``bzr reconfigure``
131
92
command to either stack on an existing branch, or to turn off stacking.
132
 
Be aware that when ``brz reconfigure --unstacked`` is used, brz will
 
93
Be aware that when ``bzr reconfigure --unstacked`` is used, bzr will
133
94
copy all the referenced data from the stacked-on repository into the
134
95
previously stacked repository.  For large repositories this may take
135
96
considerable time and may substantially increase the size of the