# HG changeset patch # User Greg Ward # Date 1429029817 14400 # Node ID 0daf56a2032d9c6275762605f74351d1bd2c58c7 # Parent 8873aedbd83d461237b95931c8068fa507ac7f93 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.) diff -r 8873aedbd83d -r 0daf56a2032d docs/sharing.rst --- 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 <> test-repo/.hg/hgrc <> dev-repo/.hg/hgrc < 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)' diff -r 8873aedbd83d -r 0daf56a2032d tests/test-sharing.t --- 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 < [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 < [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)'