← 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

(mbp) improved documentation for stacking

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
 
4
17
What is a stacked branch?
5
18
-------------------------
6
19
 
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:
 
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:
13
26
 
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
22
35
  branches.
23
36
 
24
 
These benefits make stacked branches ideal for various scenarios
25
 
including experimental branches and code hosting sites.
26
 
 
27
37
 
28
38
Creating a stacked branch
29
39
-------------------------
63
73
 
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``.
 
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.
67
84
 
68
85
If the local branch was created as a stacked branch, then you can
69
86
use the ``--stacked`` option to ``push`` and the *stacked-on* location