docs: add a bit more hierarchy to the sharing guide stable
authorGreg Ward <greg@gerg.ca>
Mon, 09 Jun 2014 08:18:43 -0400
branchstable
changeset 1260 e8016d1011b5
parent 1259 0daf56a2032d
child 1261 56cc2eb5995a
docs: add a bit more hierarchy to the sharing guide
docs/sharing.rst
--- a/docs/sharing.rst	Tue Apr 14 12:43:37 2015 -0400
+++ b/docs/sharing.rst	Mon Jun 09 08:18:43 2014 -0400
@@ -4,6 +4,8 @@
 Evolve: Shared Mutable History
 ------------------------------
 
+.. contents::
+
 Once you have mastered the art of mutable history in a single
 repository (see the `user guide`_), you might want to move up to the
 next level: *shared* mutable history. ``evolve`` lets you push and
@@ -47,8 +49,11 @@
 typically for code review. We'll cover this scenario later. But first,
 single-user sharing.
 
+Sharing with a single developer
+-------------------------------
+
 Publishing and non-publishing repositories
-------------------------------------------
+==========================================
 
 The key to shared mutable history is to keep your changesets in
 *draft* phase as you pass them around. Recall that by default, ``hg
@@ -58,8 +63,8 @@
 (Short version: set ``phases.publish`` to ``false``. Long version
 follows.)
 
-Setting things up
------------------
+Setting up
+==========
 
 We'll work an example with three local repositories, although in the
 real world they'd most likely be on three different computers. First,
@@ -131,7 +136,7 @@
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
 Example 1: Amend a shared changeset
------------------------------------
+===================================
 
 Everything you learned in the `user guide`_ applies to work done in
 ``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
@@ -205,7 +210,7 @@
 *must* use changeset IDs.
 
 Example 2: Amend again, locally
--------------------------------
+===============================
 
 This process can repeat. Perhaps you figure out a more elegant fix to
 the bug, and want to mutate history so nobody ever knows you had a
@@ -262,8 +267,8 @@
   $ cd ../dev-repo
   $ hg pull -u
 
-Getting into trouble
---------------------
+Sharing with multiple developers
+--------------------------------
 
 Mercurial with ``evolve`` is a powerful tool, and using powerful tools
 can have consequences. (You can cut yourself badly with a sharp knife,
@@ -278,6 +283,9 @@
 changesets. Both are more likely with shared mutable history,
 especially mutable history shared by multiple developers.
 
+Setting up
+==========
+
 To demonstrate, let's start with the ``public`` repository as we left
 it in the last example, with two immutable changesets (figure 5
 above). Two developers, Alice and Bob, start working from this point::
@@ -301,7 +309,7 @@
   $ cp alice/.hg/hgrc bob/.hg/hgrc
 
 Bumped changesets: only one gets on the plane
----------------------------------------------
+=============================================
 
 If two people show up at the airport with tickets for the same seat on
 the same plane, only one of them gets on the plane. The would-be
@@ -385,7 +393,7 @@
   [figure SG08: 5:227d is new, formerly bumped changeset 4:fe88 now hidden]
 
 Divergent changesets
---------------------
+====================
 
 In addition to *unstable* and *bumped*, there is a third kind of
 troubled changeset: *divergent*. When an obsolete changeset has two