--- a/docs/sharing.rst Mon Apr 20 13:52:43 2015 +0200
+++ b/docs/sharing.rst Tue Apr 14 12:43:37 2015 -0400
@@ -5,12 +5,15 @@
------------------------------
Once you have mastered the art of mutable history in a single
-repository, you might want to move up to the next level: *shared*
-mutable history. ``evolve`` lets you push and pull draft changesets
-between repositories along with their obsolescence markers. This opens
-up a number of interesting possibilities.
+repository (see the `user guide`_), you might want to move up to the
+next level: *shared* mutable history. ``evolve`` lets you push and
+pull draft changesets between repositories along with their
+obsolescence markers. This opens up a number of interesting
+possibilities.
-The most common scenario is a single developer working across two
+.. _`user guide`: user-guide.html
+
+The simplest scenario is a single developer working across two
computers. Say you're working on code that must be tested on a remote
test server, probably in a rack somewhere, only accessible by SSH, and
running an “enterprise-grade” (out-of-date) OS. But you probably
@@ -40,9 +43,9 @@
those half-baked changesets between repositories to try things out on
your test server before anything is carved in stone.
-A less common scenario is multiple developers sharing mutable history.
-(This is in fact how Mercurial itself is developed.) We'll cover this
-scenario later. But first, single-user sharing.
+A less common scenario is multiple developers sharing mutable history,
+typically for code review. We'll cover this scenario later. But first,
+single-user sharing.
Publishing and non-publishing repositories
------------------------------------------
@@ -60,15 +63,20 @@
We'll work an example with three local repositories, although in the
real world they'd most likely be on three different computers. First,
-the public repository is where tested, polished changesets live, and
-it is where you push/pull changesets to/from the rest of your team. ::
+the ``public`` repository is where tested, polished changesets live,
+and it is where you synchronize changesets with the rest of your team.
+::
$ hg init public
We'll need two clones where work gets done::
- $ hg clone -q public test-repo
- $ hg clone -q test-repo dev-repo
+ $ hg clone public test-repo
+ updating to branch default
+ 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ hg clone test-repo dev-repo
+ updating to branch default
+ 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
``dev-repo`` is your local machine, with GUI merge tools and IDEs and
everything configured just the way you like it. ``test-repo`` is the
@@ -76,25 +84,29 @@
we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
there, and push to ``public``.
-The key to making this whole thing work is to make ``test-repo``
-non-publishing::
+The key to shared mutable history is to make the target repository,
+``test-repo`` in this case, non-publishing. And, of course, we have to enable ``evolve`` in both ``test-repo`` and ``dev-repo``.
+
+First, edit the configuration for ``test-repo``::
- $ cat >> test-repo/.hg/hgrc <<EOF
+ $ hg -R test-repo config --edit --local
+
+and add ::
+
[phases]
publish = false
- EOF
-We also have to configure ``evolve`` in both ``test-repo`` and
-``dev-repo``, so that we can amend and evolve in both of them. ::
-
- $ cat >> test-repo/.hg/hgrc <<EOF
[extensions]
evolve = /path/to/mutable-history/hgext/evolve.py
- EOF
- $ cat >> dev-repo/.hg/hgrc <<EOF
+
+Then edit the configuration for ``dev-repo``::
+
+ $ hg -R dev-repo config --edit --local
+
+and add ::
+
[extensions]
evolve = /path/to/mutable-history/hgext/evolve.py
- EOF
Keep in mind that in real life, these repositories would probably be
on separate computers, so you'd have to login to each one to configure
@@ -106,15 +118,20 @@
$ echo 'my new project' > file1
$ hg add file1
$ hg commit -m 'create new project'
- $ hg push -q
+ $ hg push
+ [...]
+ added 1 changesets with 1 changes to 1 files
and pull that into the development repository::
$ cd ../dev-repo
$ hg pull -u
+ [...]
+ added 1 changesets with 1 changes to 1 files
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
-Amending a shared changeset
----------------------------
+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
@@ -187,8 +204,8 @@
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
*must* use changeset IDs.
-Amend again, locally
---------------------
+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
@@ -209,7 +226,8 @@
Let's hop over to ``test-repo`` to test the more elegant fix::
$ cd ../test-repo
- $ hg update -q
+ $ hg update
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
This time, all the tests pass, so no further amendment is required.
This bug fix is finished, so we push it to the public repository::
@@ -264,8 +282,12 @@
it in the last example, with two immutable changesets (figure 5
above). Two developers, Alice and Bob, start working from this point::
- $ hg clone -q public alice
- $ hg clone -q public bob
+ $ hg clone public alice
+ updating to branch default
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ hg clone public bob
+ updating to branch default
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
We need to configure Alice's and Bob's working repositories similar to
``test-repo``, i.e. make them non-publishing and enable ``evolve``::
@@ -298,15 +320,19 @@
$ cd alice
$ echo 'fix' > file2
- $ hg commit -q -A -m 'fix bug 15'
+ $ hg commit -A -m 'fix bug 15'
+ adding file2
Now Bob has a bad idea: he decides to pull whatever Alice is working
on and tweak her bug fix to his taste::
$ cd ../bob
- $ hg pull -q -u ../alice
+ $ hg pull -u ../alice
+ [...]
+ added 1 changesets with 1 changes to 1 files
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ echo 'Fix.' > file2
- $ hg amend -q -A -m 'fix bug 15 (amended)'
+ $ hg amend -A -m 'fix bug 15 (amended)'
(Note the lack of communication between Alice and Bob. Failing to
communicate with your colleagues is a good way to get into trouble.
@@ -319,7 +345,9 @@
publish. ::
$ cd ../alice
- $ hg push -q
+ $ hg push
+ [...]
+ added 1 changesets with 1 changes to 1 files
This introduces a contradiction: in Bob's repository, changeset 2:e011
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
@@ -382,7 +410,9 @@
idea)::
$ cd ../alice
- $ hg pull -q -u ../bob
+ $ hg pull -u ../bob
+ [...]
+ added 1 changesets with 1 changes to 1 files
$ echo 'better (alice)' >> file1
$ hg amend -u alice -m 'fix bug 24 (v2 by alice)'