Bazaar

Merge lp:~mbp/bzr/doc-stacking into lp:bzr

  1. doc-stacking
  2. Merge into bzr.dev
Proposed by Martin Pool
Status: Merged
Approved by: Martin Pool
Approved revision: no longer in the source branch.
Merged at revision: not available
Proposed branch: lp:~mbp/bzr/doc-stacking
Merge into: lp:bzr
Diff against target: 64 lines (+27/-10)
1 file modified
doc/en/user-guide/stacked.txt (+27/-10)
To merge this branch: bzr merge lp:~mbp/bzr/doc-stacking
Reviewer Review Type Date Requested Status
Andrew Bennetts Approve
Martin Pool Approve
Review via email: mp+21694@code.launchpad.net

Commit message

(mbp) improved documentation for stacking

Description of the change

Proposed doc improvements for bug 537888.

To post a comment you must log in.
Revision history for this message
Martin Pool (mbp) wrote :

This looks pretty good to me. I wonder if we should have a recommendation against stacking across servers though, which may make things fragile/slow.

Revision history for this message
Martin Pool (mbp) :
review: Approve
Revision history for this message
Andrew Bennetts (spiv) wrote :

I like this too.

Martin, do we need a contributor agreement from ~herberteuler ?

review: Approve
Revision history for this message
Martin Pool (mbp) wrote :

Fed to pqm

star-merge http://bazaar.launchpad.net/~mbp/bzr/doc-stacking http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/en/user-guide/stacked.txt'
2--- doc/en/user-guide/stacked.txt 2009-12-02 20:34:07 +0000
3+++ doc/en/user-guide/stacked.txt 2010-03-18 23:18:20 +0000
4@@ -1,15 +1,28 @@
5 Using stacked branches
6 ======================
7
8+Motivation
9+----------
10+
11+If you are working on a project, and you have read access to whose
12+public repository but do not have write access to it, using stacked
13+branches to backup/publish your work onto the same host of the public
14+repository might be an option for you.
15+
16+Other scenarios for stacked branch usage include experimental branches
17+and code hosting sites. For these scenarios, stacked branches are
18+ideal because of the benefits it provides.
19+
20+
21 What is a stacked branch?
22 -------------------------
23
24-A stacked branch is a branch that knows how to find revisions
25-in another branch. Stacked branches store just the
26-unique revisions, making them faster to create and more
27-storage efficient. In these respects, stacked branches are
28-similar to shared repositories. However, stacked branches have
29-additional benefits:
30+A stacked branch is a branch that knows how to find revisions in
31+another branch (the stacked-on branch). Stacked branches store just
32+the unique revisions that are not in the stacked-on branch, making
33+them faster to create and more storage efficient. In these respects,
34+stacked branches are similar to shared repositories. However, stacked
35+branches have additional benefits:
36
37 * The new branch can be in a completely different location to the
38 branch being stacked on.
39@@ -21,9 +34,6 @@
40 repository can be physically readonly to developers committing to stacked
41 branches.
42
43-These benefits make stacked branches ideal for various scenarios
44-including experimental branches and code hosting sites.
45-
46
47 Creating a stacked branch
48 -------------------------
49@@ -63,7 +73,14 @@
50
51 This creates a new branch at ``my-url`` that is stacked on ``reference-url``
52 and only contains the revisions in the current branch that are not already
53-in the branch at ``reference-url``.
54+in the branch at ``reference-url``. In particular, ``my-url`` and
55+``reference-url`` can be on the same host, and the ``--stacked`` option
56+can be used additionally to inform ``push`` to reference the
57+revisions in ``reference-url``. For example::
58+
59+ bzr push --stacked-on sftp://host/project --stacked sftp://host/user/stacked-branch
60+
61+This usage fits the scenario described in the Motivation section.
62
63 If the local branch was created as a stacked branch, then you can
64 use the ``--stacked`` option to ``push`` and the *stacked-on* location