Mercurial > evolve

changeset 1259:0daf56a2032d stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: update sharing guide based (mostly) on marmoute's review - don't claim certain scenarios are more/less common, just simple/advanced - mention code review as a multiple-developer scenario (not described in detail yet!) - suggest "hg config --edit --local" instead of "cat >> .hg/hgrc" - use -q less often (and show resulting output) - edit some section headers to be consistent with user guide (example numbers; "amend" instead of "amending") (These are just the small changes; big changes are yet to come.)
author Greg Ward <greg@gerg.ca>
date Tue, 14 Apr 2015 12:43:37 -0400
parents 8873aedbd83d
children e8016d1011b5
files docs/sharing.rst tests/test-sharing.t
diffstat 2 files changed, 128 insertions(+), 48 deletions(-) [+]
line wrap: on
line diff
--- 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)'
 
--- a/tests/test-sharing.t	Mon Apr 20 13:52:43 2015 +0200
+++ b/tests/test-sharing.t	Tue Apr 14 12:43:37 2015 -0400
@@ -11,8 +11,12 @@
   > EOF
   $ echo "evolve=$(echo $(dirname $TESTDIR))/hgext/evolve.py" >> $HGRCPATH
   $ hg init public
-  $ 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
   $ cat >> test-repo/.hg/hgrc <<EOF
   > [phases]
   > publish = false
@@ -24,12 +28,26 @@
   $ echo 'my new project' > file1
   $ hg add file1
   $ hg commit -m'create new project'
-  $ hg push -q
+  $ hg push
+  pushing to $TESTTMP/public
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
 
 and pull that into the development repository::
 
   $ cd ../dev-repo
-  $ hg pull -q -u
+  $ hg pull -u
+  pulling from $TESTTMP/test-repo
+  requesting all changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
+  pull obsolescence markers
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
 Let's commit a preliminary change and push it to ``test-repo`` for
 testing. ::
@@ -92,7 +110,8 @@
   
 Figure SG04 (test-repo)
   $ cd ../test-repo
-  $ hg update -q
+  $ hg update
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
   $ hg shortlog --hidden -G
   @  4:de6151c48e1c  draft  fix bug 37
   |
@@ -132,8 +151,12 @@
 First, setup repos for them.
 
   $ cd ..
-  $ 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
   $ cat >> alice/.hg/hgrc <<EOF
   > [phases]
   > publish = false
@@ -143,13 +166,23 @@
 Alice commits a bug fix.
   $ cd alice
   $ echo 'fix' > file2
-  $ hg commit -q -A -u alice -m 'fix bug 15'
+  $ hg commit -A -u alice -m 'fix bug 15'
+  adding file2
 
 Bob pulls and amends Alice's fix.
   $ cd ../bob
-  $ hg pull -q -u ../alice
+  $ hg pull -u ../alice
+  pulling from ../alice
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
+  pull obsolescence markers
+  0 obsolescence markers added
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
   $ echo 'Fix.' > file2
-  $ hg amend -q -A -u bob -m 'fix bug 15 (amended)'
+  $ hg amend -A -u bob -m 'fix bug 15 (amended)'
 
 Figure SG06: Bob's repository after amending Alice's fix.
 (Nothing new here; we could have seen this in the user guide.
@@ -167,7 +200,15 @@
 
 But in the meantime, Alice decides the fix is just fine and publishes it.
   $ cd ../alice
-  $ hg push -q
+  $ hg push
+  pushing to $TESTTMP/public
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
+  pushing 4 obsolescence markers (369 bytes)
+  0 obsolescence markers added
 
 Which means that Bob now has an formerly obsolete changeset that is
 also public (2:6e83). As soon as he pulls its phase change, he's got
@@ -234,7 +275,16 @@
 
 Alice pulls Bob's fix and improves it.
   $ cd ../alice
-  $ hg pull -q -u ../bob
+  $ hg pull -u ../bob
+  pulling from ../bob
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
+  pull obsolescence markers
+  0 obsolescence markers added
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
   $ echo 'better (alice)' >> file1
   $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'