Rev 5649: (spiv) Update "Using stacked branches" document. (Andrew Bennetts) in file:///home/pqm/archives/thelove/bzr/2.3/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/2.3/

------------------------------------------------------------
revno: 5649 [merge]
revision-id: pqm at pqm.ubuntu.com-20110518114537-l5pyj32i4ktye2y4
parent: pqm at pqm.ubuntu.com-20110517204412-wdh321at6v0w307l
parent: andrew.bennetts at canonical.com-20110518090437-yjf51230seyqgz5y
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: 2.3
timestamp: Wed 2011-05-18 11:45:37 +0000
message:
  (spiv) Update "Using stacked branches" document. (Andrew Bennetts)
modified:
  doc/en/release-notes/bzr-2.3.txt NEWS-20050323055033-4e00b5db738777ff
  doc/en/user-guide/stacked.txt  stacked.txt-20080711023247-4uh9oovoka0sze8b-1
=== modified file 'doc/en/release-notes/bzr-2.3.txt'
--- a/doc/en/release-notes/bzr-2.3.txt	2011-05-17 15:14:38 +0000
+++ b/doc/en/release-notes/bzr-2.3.txt	2011-05-18 09:04:37 +0000
@@ -38,6 +38,10 @@
 
 .. Improved or updated documentation.
 
+* Updated the "Using stacked branches" section of the user guide to
+  describe committing to stacked branches and expanded its discussion of
+  pushing a stcked branch.  (Andrew Bennetts)
+
 API Changes
 ***********
 

=== modified file 'doc/en/user-guide/stacked.txt'
--- a/doc/en/user-guide/stacked.txt	2010-03-25 07:34:15 +0000
+++ b/doc/en/user-guide/stacked.txt	2011-05-18 09:04:37 +0000
@@ -74,46 +74,55 @@
 This creates a new branch at ``my-url`` that is stacked on ``reference-url``
 and only contains the revisions in the current branch that are not already
 in the branch at ``reference-url``. In particular, ``my-url`` and
-``reference-url`` can be on the same host, and the ``--stacked`` option
+``reference-url`` can be on the same host, and the ``--stacked-on`` option
 can be used additionally to inform ``push`` to reference the
 revisions in ``reference-url``. For example::
 
-  bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
+  bzr push --stacked-on sftp://host/project sftp://host/user/stacked-branch
 
 This usage fits the scenario described in the Motivation section.
 
-
-.. The following text is hidden because bug 375013 breaks the example.
-   When bug 375013 is fixed, we should unhide this text.
-      - Andrew Bennetts, 10 March 2010
-
-.. If the local branch was created as a stacked branch, then you can
-.. use the ``--stacked`` option to ``push`` and the *stacked-on* location
-.. will be implicit. For example::
-.. 
-..   bzr branch --stacked source-url my-dir
-..   cd my-dir
-..   (hack, hack, hack)
-..   bzr commit -m "fix bug"
-..   bzr push --stacked
+You can also use the ``--stacked`` option without specifying ``--stacked-on``.
+This will automatically set the *stacked-on* location to the parent branch of
+the branch you are pushing (or its ``public_location`` if configured).  For
+example::
+
+  bzr branch source-url my-dir
+  cd my-dir
+  (hack, hack, hack)
+  bzr commit -m "fix bug"
+  bzr push --stacked
+
+You can combine ``bzr branch --stacked`` and ``bzr push --stacked`` to work on a
+branch without downloading or uploading the whole history::
+
+  bzr branch --stacked source-url my-dir
+  cd my-dir
+  (hack, hack, hack)
+  bzr commit -m "fix bug"
+  bzr push --stacked
 
 
 Limitations of stacked branches
 -------------------------------
 
-Currently, you cannot commit to a stacked branch, due to `bug 375013`_.
-
-.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
-
-The important thing to remember about a stacked branch is that the
-stacked-on branch needs to be available for almost all operations. This is
-not an issue when both branches are local or both branches are on the
-same server.
+The important thing to remember about a stacked branch is that the stacked-on
+branch needs to be accessible for almost all operations.  This is not an issue
+when both branches are local, or when both branches are on the same server and
+the stacked-on location is a relative path.  But clearly a branch hosted on a
+server with a stacked-on location of ``file:///...`` is not going to work for
+anyone except the user that originally pushed it.  It's a good idea to configure
+``public_location`` to help prevent that.
 
 Similarly, because most of the history is stored in the stacked-on repository,
 operations like ``bzr log`` can be slower when the stacked-on repository is
 accessed via a network.
 
+If a stacked branch is in a format older than 2a, you cannot commit to it due to
+`bug 375013`_.
+
+.. _bug 375013: https://bugs.launchpad.net/bzr/+bug/375013
+
 
 Changing branch stacking
 ------------------------