← 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: 2009-01-19 02:24:15 UTC
  • mto: This revision was merged to the branch mainline in revision 3944.
  • Revision ID: ian.clatworthy@canonical.com-20090119022415-mo0mcfeiexfktgwt
apply jam's log --short fix (Ian Clatworthy)

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, because the stacked-on
 
21
  repository can be physically readonly to developers committing to stacked 
 
22
  branches.
 
23
 
 
24
These benefits make stacked branches ideal for various scenarios
 
25
including experimental branches and code hosting sites.
 
26
 
 
27
 
 
28
Creating a stacked branch
 
29
-------------------------
 
30
 
 
31
To create a stacked branch, use the ``stacked`` option of the branch command.
 
32
For example::
 
33
 
 
34
  bzr branch --stacked source-url my-dir
 
35
 
 
36
This will create ``my-dir`` as a stacked branch with no local revisions.
 
37
If it is defined, the public branch associated with ``source-url`` will be
 
38
used as the *stacked-on* location. Otherwise, ``source-url`` will be the
 
39
*stacked-on* location.
 
40
 
 
41
 
 
42
Creating a stacked checkout
 
43
---------------------------
 
44
 
 
45
Direct creation of a stacked checkout is expected to be supported soon.
 
46
In the meantime, a two step process is required:
 
47
 
 
48
1. Create a stacked branch as shown above.
 
49
 
 
50
2. Convert the branch into a checkout using either the ``reconfigure``
 
51
   or ``bind`` command.
 
52
 
 
53
 
 
54
Pushing a stacked branch
 
55
------------------------
 
56
 
 
57
Most changes on most projects build on an existing branch such as the
 
58
*development trunk* or *current stable* branch. Creating a new
 
59
branch stacked on one of these is easy to do using the ``push``
 
60
command like this::
 
61
 
 
62
  bzr push --stacked-on reference-url my-url
 
63
 
 
64
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
 
65
and only contains the revisions in the current branch that are not already
 
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
 
77
 
 
78
 
 
79
Limitations of stacked branches
 
80
-------------------------------
 
81
 
 
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.