Rev 3799: (mbp) improved stacked/lightweight documentation in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

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

------------------------------------------------------------
revno: 3799
revision-id: pqm at pqm.ubuntu.com-20081027100754-ilnqmlvshjrw6itv
parent: pqm at pqm.ubuntu.com-20081027093156-02gq7k14aeg9k0c7
parent: mernst at csail.mit.edu-20081016105716-v8x8n5t2pf7f6uds
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2008-10-27 10:07:54 +0000
message:
  (mbp) improved stacked/lightweight documentation
modified:
  doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
  doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
  doc/en/user-guide/using_checkouts.txt using_checkouts.txt-20071123055134-k5x4ekduci2lbn36-4
    ------------------------------------------------------------
    revno: 3779.2.1
    revision-id: mernst at csail.mit.edu-20081016105716-v8x8n5t2pf7f6uds
    parent: pqm at pqm.ubuntu.com-20081016043554-38i4ho6svnlyba65
    committer: mernst at csail.mit.edu
    branch nick: doc-stacked-lightweight
    timestamp: Thu 2008-10-16 12:57:16 +0200
    message:
      Improved documentation of stacked and lightweight branches
      
      These patches improve the User Guide's documentation of stacked and
      lightweight branches.
      
      Section "1.2.6 Putting the concepts together" should mention stacked
      branches and the difference between them and lightweight branches.  It
      should also contain links to further details of the common scenarios.
      
      Section "5.3.4 Getting a lightweight checkout" should mention stacked
      branches as an option, and should link to all the options, not just some of
      them.  It should also clarify that lightweight only applies to checkouts,
      not to arbitrary branches.
    modified:
      doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
      doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
      doc/en/user-guide/using_checkouts.txt using_checkouts.txt-20071123055134-k5x4ekduci2lbn36-4
=== modified file 'doc/en/user-guide/branching_a_project.txt'
--- a/doc/en/user-guide/branching_a_project.txt	2008-05-29 18:42:07 +0000
+++ b/doc/en/user-guide/branching_a_project.txt	2008-10-16 10:57:16 +0000
@@ -37,7 +37,9 @@
 where to put it on your filesystem. For maximum storage
 efficiency down the track, it is recommended that branches
 be created somewhere under a directory that has been set up
-as a shared repository. For example::
+as a shared repository. (See `Choosing a shared repository
+layout`_ in the appendices for guidelines and examples.)
+For example::
 
   bzr init-repo my-repo
   cd my-repo
@@ -89,7 +91,8 @@
 the latest version.
 
 As explained in later chapters, Bazaar also has support for
-lightweight checkouts of a branch, i.e. working trees with
+`lightweight checkouts <#getting-a-lightweight-checkout>`_ 
+of a branch, i.e. working trees with
 no local storage of history. Of course, disconnected usage
 is not available then but that's a tradeoff you can decide
 to make if local disk space is really tight for you. Support for

=== modified file 'doc/en/user-guide/core_concepts.txt'
--- a/doc/en/user-guide/core_concepts.txt	2008-05-09 14:59:31 +0000
+++ b/doc/en/user-guide/core_concepts.txt	2008-10-16 10:57:16 +0000
@@ -108,11 +108,15 @@
 to use a *standalone tree*, which has a working tree, branch, and repository
 all in a single location. Other common scenarios include:
 
-* *Shared repositories* - working tree and branch are colocated, but the
-  repository is in a higher level directory.
-
-* *Lightweight checkouts* - branch is stored is a different location
-  to the working tree.
+* `Shared repositories <#a-reminder-about-shared-repositories>`_ - working
+  tree and branch are colocated, but the repository is in a higher level
+  directory.
+
+* `Stacked branches <#using-stacked-branches>`_ - branch stores just its
+  unique revisions, using its parent's repository for common revisions.
+
+* `Lightweight checkouts <#getting-a-lightweight-checkout>`_ - branch is 
+  stored in a different location to the working tree.
 
 The best way to use Bazaar, however, depends on your needs. Let's take a
 look at some common workflows next.

=== modified file 'doc/en/user-guide/using_checkouts.txt'
--- a/doc/en/user-guide/using_checkouts.txt	2007-11-23 05:52:03 +0000
+++ b/doc/en/user-guide/using_checkouts.txt	2008-10-16 10:57:16 +0000
@@ -61,10 +61,13 @@
 Of course, many of the benefits of a normal checkout are lost by doing
 this but that's a tradeoff you can make if and when it makes sense.
 
+The ``--lightweight`` option only applies to checkouts, not to all branches.
+
 Note: If your code base is really large and disk space on your computer
 is limited, lightweight checkouts may be the right choice for you.
-Be sure to consider all your options though including shared repositories
-and `Reusing a checkout`_ as explained later.
+Be sure to consider all your options though including
+`shared repositories <#a-reminder-about-shared-repositories>`_,
+`stacked branches <#using-stacked-branches>`_, and `reusing a checkout`_.
 
 Updating to the latest content
 ------------------------------