← 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: Andrew Bennetts
  • Date: 2010-10-13 00:26:41 UTC
  • mto: This revision was merged to the branch mainline in revision 5498.
  • Revision ID: andrew.bennetts@canonical.com-20101013002641-9tlh9k89mlj1666m
Keep docs-plain working.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/stacked.txt
74
74
This creates a new branch at ``my-url`` that is stacked on ``reference-url``
75
75
and only contains the revisions in the current branch that are not already
76
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
 
77
``reference-url`` can be on the same host, and the ``--stacked`` option
78
78
can be used additionally to inform ``push`` to reference the
79
79
revisions in ``reference-url``. For example::
80
80
 
81
 
  bzr push --stacked-on bzr+ssh://host/project bzr+ssh://host/user/stacked-branch
 
81
  bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
82
82
 
83
83
This usage fits the scenario described in the Motivation section.
84
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
 
  bzr branch source-url my-dir
91
 
  cd my-dir
92
 
  (hack, hack, hack)
93
 
  bzr commit -m "fix bug"
94
 
  bzr push --stacked
95
 
 
96
 
You can combine ``bzr branch --stacked`` and ``bzr push --stacked`` to work on a
97
 
branch without downloading or uploading the whole history::
98
 
 
99
 
  bzr branch --stacked source-url my-dir
100
 
  cd my-dir
101
 
  (hack, hack, hack)
102
 
  bzr commit -m "fix bug"
103
 
  bzr push --stacked
 
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
104
99
 
105
100
 
106
101
Limitations of stacked branches
107
102
-------------------------------
108
103
 
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.
 
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.
116
112
 
117
113
Similarly, because most of the history is stored in the stacked-on repository,
118
114
operations like ``bzr log`` can be slower when the stacked-on repository is
119
115
accessed via a network.
120
116
 
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
125
 
 
126
117
 
127
118
Changing branch stacking
128
119
------------------------