Rev 5103: (mbp) improved documentation for stacking in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 5103 [merge]
revision-id: pqm at pqm.ubuntu.com-20100322015121-7um8d7zqa960emyz
parent: pqm at pqm.ubuntu.com-20100319132930-bqdnwhq9ao2rf8ae
parent: herberteuler at hotmail.com-20100318080339-mdg9zk62sq9d8rh5
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2010-03-22 01:51:21 +0000
message:
  (mbp) improved documentation for stacking
modified:
  doc/en/user-guide/stacked.txt  stacked.txt-20080711023247-4uh9oovoka0sze8b-1
=== modified file 'doc/en/user-guide/stacked.txt'
--- a/doc/en/user-guide/stacked.txt	2009-12-02 20:34:07 +0000
+++ b/doc/en/user-guide/stacked.txt	2010-03-18 08:03:39 +0000
@@ -1,15 +1,28 @@
 Using stacked branches
 ======================
 
+Motivation
+----------
+
+If you are working on a project, and you have read access to whose
+public repository but do not have write access to it, using stacked
+branches to backup/publish your work onto the same host of the public
+repository might be an option for you.
+
+Other scenarios for stacked branch usage include experimental branches
+and code hosting sites. For these scenarios, stacked branches are
+ideal because of the benefits it provides.
+
+
 What is a stacked branch?
 -------------------------
 
-A stacked branch is a branch that knows how to find revisions
-in another branch. Stacked branches store just the
-unique revisions, making them faster to create and more
-storage efficient. In these respects, stacked branches are
-similar to shared repositories. However, stacked branches have
-additional benefits:
+A stacked branch is a branch that knows how to find revisions in
+another branch (the stacked-on branch). Stacked branches store just
+the unique revisions that are not in the stacked-on branch, making
+them faster to create and more storage efficient. In these respects,
+stacked branches are similar to shared repositories. However, stacked
+branches have additional benefits:
 
 * The new branch can be in a completely different location to the
   branch being stacked on.
@@ -21,9 +34,6 @@
   repository can be physically readonly to developers committing to stacked
   branches.
 
-These benefits make stacked branches ideal for various scenarios
-including experimental branches and code hosting sites.
-
 
 Creating a stacked branch
 -------------------------
@@ -63,7 +73,14 @@
 
 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 the branch at ``reference-url``. In particular, ``my-url`` and
+``reference-url`` can be on the same host, and the ``--stacked`` 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
+
+This usage fits the scenario described in the Motivation section.
 
 If the local branch was created as a stacked branch, then you can
 use the ``--stacked`` option to ``push`` and the *stacked-on* location