← 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: Patch Queue Manager
  • Date: 2016-04-21 05:06:57 UTC
  • mfrom: (6603.4.1 bzr)
  • Revision ID: pqm@pqm.ubuntu.com-20160421050657-ygnzfybewvudf1j9
(richard-wilbur) Use initial_comment as commit_message for lp_propose.(Shawn
 Wang) (Shawn Wang)

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`` option
 
77
``reference-url`` can be on the same host, and the ``--stacked-on`` 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 sftp://host/project --stacked sftp://host/user/stacked-branch
 
81
  bzr push --stacked-on bzr+ssh://host/project bzr+ssh://host/user/stacked-branch
82
82
 
83
83
This usage fits the scenario described in the Motivation section.
84
84
 
85
 
If the local branch was created as a stacked branch, then you can
86
 
use the ``--stacked`` option to ``push`` and the *stacked-on* location
87
 
will be implicit. For example::
 
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::
88
98
 
89
99
  bzr branch --stacked source-url my-dir
90
100
  cd my-dir
96
106
Limitations of stacked branches
97
107
-------------------------------
98
108
 
99
 
The important thing to remember about a stacked branch is that the
100
 
stacked-on branch needs to be available for almost all operations. This is
101
 
not an issue when both branches are local or both branches are on the
102
 
same server.
 
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 ``bzr 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
103
125
 
104
126
 
105
127
Changing branch stacking