← 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: 2008-07-11 02:33:29 UTC
  • mto: (3549.1.2 stacking)
  • mto: This revision was merged to the branch mainline in revision 3551.
  • Revision ID: ian.clatworthy@canonical.com-20080711023329-0p2migiydrfqsz0t
Add user doc for stacked branches

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
What is a stacked branch?
 
5
-------------------------
 
6
 
 
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:
 
13
 
 
14
* The new branch can be in a completely different location to the
 
15
  branch being stacked on.
 
16
 
 
17
* Deleting the stacked branch really deletes the revisions (rather
 
18
  than leaving them in a shared repository).
 
19
 
 
20
* Security is improved over shared repositories: developers with
 
21
  access to a shared repository can programmatically get to all
 
22
  revisions, while they cannot get to the local revisions in a stacked
 
23
  branch in a secure location.
 
24
 
 
25
These benefits make stacked branches ideal for various scenarios
 
26
including experimental branches and code hosting sites.
 
27
 
 
28
 
 
29
Creating a stacked branch
 
30
-------------------------
 
31
 
 
32
To create a stacked branch, use the ``stacked`` option of the branch command.
 
33
For example::
 
34
 
 
35
  bzr branch --stacked source-url my-dir
 
36
 
 
37
This will create ``my-dir`` as a stacked branch with no local revisions.
 
38
If it is defined, the public branch associated with ``source-url`` will be
 
39
used as the *stacked-on* location. Otherwise, ``source-url`` will be the
 
40
*stacked-on* location.
 
41
 
 
42
 
 
43
Creating a stacked checkout
 
44
---------------------------
 
45
 
 
46
Direct creation of a stacked checkout is expected to be supported soon.
 
47
In the meantime, a two step process is required:
 
48
 
 
49
1. Create a stacked branch as shown above.
 
50
 
 
51
2. Convert the branch into a checkout using either the ``reconfigure``
 
52
   or ``bind`` command.
 
53
 
 
54
 
 
55
Pushing a stacked branch
 
56
------------------------
 
57
 
 
58
Most changes on most projects build on an existing branch such as the
 
59
*development trunk* or *current stable* branch. Creating a new
 
60
branch stacked on one of these is easy to do using the ``push``
 
61
command like this::
 
62
 
 
63
  bzr push --stacked-url reference-url new-url
 
64
 
 
65
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
 
66
and only contains the revisions in the current branch that are not already
 
67
in the branch at ``reference-url``.
 
68
 
 
69
If the local branch was created as a stacked branch, then you can
 
70
use the ``--stacked`` option to ``push`` and the *stacked-on* location
 
71
will be implicit. For example::
 
72
 
 
73
  bzr branch --stacked source-url my-dir
 
74
  cd my-dir
 
75
  (hack, hack, hack)
 
76
  bzr commit -m "fix bug"
 
77
  bzr push --stacked my-url
 
78
 
 
79
 
 
80
Limitations of stacked branches
 
81
-------------------------------
 
82
 
 
83
The important thing to remember about a stacked branch is that the
 
84
stacked-on branch needs to be available for many operations. This is
 
85
not an issue when both branches are local or both branches are on the
 
86
same server.