--- a/docs/tutorials/tutorial.t Wed May 09 14:24:56 2012 +0200
+++ b/docs/tutorials/tutorial.t Wed May 09 16:39:35 2012 +0200
@@ -1,20 +1,7 @@
-===================================
- Mutable History and collaboration
-===================================
-.. warning:: need heavy update
-
-Single Developer Usage
-======================
-
-This tutorial shows how to use evolution to replace the basics of *mq*.
-
-Amending a changeset
+Initial setup
---------------------
-
-First there is some setup phase you will understand later.
-
-There is a local repository and a remote one.
+.. Various setup
$ cat >> $HGRCPATH << EOF
> [ui]
@@ -25,14 +12,13 @@
> amend = amend -d '0 0'
> [extensions]
> hgext.graphlog=
- > hgext.rebase=
> EOF
- $ $(dirname $TESTDIR)/enable.sh >> $HGRCPATH 2> /dev/null
$ hg init local
$ cat >> local/.hg/hgrc << EOF
> [paths]
> remote = ../remote
+ > other = ../other
> [ui]
> user = Babar the King
> EOF
@@ -45,12 +31,48 @@
> user = Celestine the Queen
> EOF
- $ cd local
+ $ hg init other
+ $ cat >> other/.hg/hgrc << EOF
+ > [ui]
+ > user = Princess Flore
+ > EOF
+
+
+This tutorial use the following configuration for Mercurial:
+
+A compact log template with phase data:
+
+ $ hg showconfig ui
+ ui.slash=True
+ ui.logtemplate="{node|short} ({phase}): {desc}\n"
+
+Improved git format diff:
+
+ $ hg showconfig diff
+ diff.git=1
-You can reopen you eyes.
+And the graphlog extension
+ $ hg showconfig extensions
+ extensions.hgext.graphlog=
+
+And of course, we anabled the experimental extensions for mutable history:
+
+ $ $(dirname $TESTDIR)/enable.sh >> $HGRCPATH 2> /dev/null
+
-Now we make a first version of our shopping list.
+-----------------------
+Single Developer Usage
+-----------------------
+
+This tutorial shows how to use evolution to rewrite history locally.
+
+Fixing mistake with `hg amend`
+--------------------------------
+
+We are versionning a shopping list
+
+ $ cd local
$ cat >> shopping << EOF
> Spam
> Whizzo butter
@@ -63,7 +85,7 @@
$ hg commit -A -m "Monthy Python Shopping list"
adding shopping
-We share this first version with the outside.
+Its first version is shared with the outside.
$ hg push remote
pushing to $TESTTMP/remote
@@ -89,14 +111,17 @@
> EOF
$ hg commit -m "adding fruit"
-I now have the following history:
+This history is very linear
- $ hg log
- d85de4546133 (draft): adding fruit
- 4d5dc8187023 (draft): adding condiment
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg glog
+ @ d85de4546133 (draft): adding fruit
+ |
+ o 4d5dc8187023 (draft): adding condiment
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
-But, I just notice, I made a typo in Banana.
+But a typo was made in Babanas!
$ hg export tip
# HG changeset patch
@@ -117,12 +142,17 @@
+Pear
+Apple
-The faulty changeset is in the "draft" phase because he was not exchanged with the outside. The first one have been exchanged and is an immutable public changeset
+The faulty changeset is in the "draft" phase because he was not exchanged with
+the outside. The first one have been exchanged and is an immutable public
+changeset.
- $ hg log
- d85de4546133 (draft): adding fruit
- 4d5dc8187023 (draft): adding condiment
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg glog
+ @ d85de4546133 (draft): adding fruit
+ |
+ o 4d5dc8187023 (draft): adding condiment
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
hopefully. I can use hg amend to rewrite my faulty changeset!
@@ -143,10 +173,13 @@
A new changeset with the right diff replace the wrong one.
- $ hg log
- 0cacb48f4482 (draft): adding fruit
- 4d5dc8187023 (draft): adding condiment
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg glog
+ @ 0cacb48f4482 (draft): adding fruit
+ |
+ o 4d5dc8187023 (draft): adding condiment
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
$ hg export tip
# HG changeset patch
# User test
@@ -171,15 +204,13 @@
While I was working on my list. someone help made a change remotly.
-close your eyes
-
$ cd ../remote
$ hg up -q
$ sed -i'' -e 's/Spam/Spam Spam Spam/' shopping
$ hg ci -m 'SPAM'
$ cd ../local
-open your eyes
+I'll get this remote changeset when pulling
$ hg pull remote
pulling from $TESTTMP/remote
@@ -190,13 +221,8 @@
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads .' to see heads, 'hg merge' to merge)
-I now have a new heads. Note that the remote head is immutable
+I now have a new heads. Note that this remote head is immutable
- $ hg log
- 9ca060c80d74 (public): SPAM
- 0cacb48f4482 (draft): adding fruit
- 4d5dc8187023 (draft): adding condiment
- 7e82d3f3c2cb (public): Monthy Python Shopping list
$ hg log -G
o 9ca060c80d74 (public): SPAM
|
@@ -217,11 +243,6 @@
My local work is now rebased on the remote one.
- $ hg log
- 387187ad9bd9 (draft): adding fruit
- dfd3a2d7691e (draft): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
$ hg log -G
@ 387187ad9bd9 (draft): adding fruit
|
@@ -244,33 +265,42 @@
> boat
> EOF
$ hg ci -m 'transport'
- $ hg log
- d58c77aa15d7 (draft): transport
- 387187ad9bd9 (draft): adding fruit
- dfd3a2d7691e (draft): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ d58c77aa15d7 (draft): transport
+ |
+ o 387187ad9bd9 (draft): adding fruit
+ |
+ o dfd3a2d7691e (draft): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
I have a new commit but I realize that don't want it. (transport shop list does
not fit well in my standard shopping list)
- $ hg kill . # . is for working directory parent.
+ $ hg kill . # . is for working directory parent
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
working directory now at 387187ad9bd9
The silly changeset is gone.
- $ hg log
- 387187ad9bd9 (draft): adding fruit
- dfd3a2d7691e (draft): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ 387187ad9bd9 (draft): adding fruit
+ |
+ o dfd3a2d7691e (draft): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
Reordering changeset
------------------------
-We create two changeset.
+We create two changesets.
$ cat >> shopping << EOF
@@ -284,20 +314,26 @@
$ sed -i'' -e 's/Spam/Spam Spam Spam/g' shopping
$ hg ci -m 'SPAM SPAM'
- $ hg log
- c48f32fb1787 (draft): SPAM SPAM
- 8d39a843582d (draft): bathroom stuff
- 387187ad9bd9 (draft): adding fruit
- dfd3a2d7691e (draft): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ c48f32fb1787 (draft): SPAM SPAM
+ |
+ o 8d39a843582d (draft): bathroom stuff
+ |
+ o 387187ad9bd9 (draft): adding fruit
+ |
+ o dfd3a2d7691e (draft): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
.. note: don't amend changeset 7e82d3f3c2cb or 9ca060c80d74 as they are
immutable.
-I now want to push to remote all my change but the bathroom one that i'm not totally happy with yet.
-
-To be able to push "SPAM SPAM" I need a version of "SPAM SPAM" not children of "bathroom stuff"
+I now want to push to remote all my change but the bathroom one that i'm not
+totally happy with yet. To be able to push "SPAM SPAM" I need a version of "SPAM SPAM" not children of
+"bathroom stuff"
You can use 'rebase -r' or 'graft -O' for that:
@@ -322,7 +358,7 @@
We have a new SPAM SPAM version without the bathroom stuff
- $ grep Spam shopping # enouth spamm
+ $ grep Spam shopping # enouth spam
Spam Spam Spam Spam Spam Spam Spam Spam Spam
$ grep Toothbrush shopping # no Toothbrush
[1]
@@ -364,6 +400,20 @@
$ hg rebase -Dr 8d39a843582d -d a2fccc2e7b08
merging shopping
$ hg phase --draft .
+ $ hg log -G
+ @ 8a79ae8b029e (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
+
Splitting change
@@ -376,8 +426,14 @@
To be done (currently achieve with "revert + debugobsolete" or "rebase --collapse")
-collaboration
-====================
+
+
+
+
+
+-----------------------
+Collaboration
+-----------------------
sharing mutable changeset
@@ -390,7 +446,8 @@
$ cd ../remote
$ hg -R ../local/ showconfig phases
-the localrepo does not have any specific configuration for `phases.publish`. It is ``true`` by default.
+the localrepo does not have any specific configuration for `phases.publish`. It
+is ``true`` by default.
$ hg pull local
pulling from $TESTTMP/local
@@ -400,13 +457,19 @@
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)
- $ hg log
- 8a79ae8b029e (public): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ o 8a79ae8b029e (public): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ @ 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
@@ -414,14 +477,19 @@
$ hg rollback
repository tip rolled back to revision 4 (undo pull)
- $ hg log
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ @ 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
-Let's make thz local repo "non publishing"
+Let's make the local repo "non publishing"
$ echo "[phases]\npublish=false" >> ../local/.hg/hgrc
$ echo "[phases]\npublish=false" >> .hg/hgrc
@@ -441,18 +509,24 @@
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)
- $ hg log
- 8a79ae8b029e (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ o 8a79ae8b029e (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ @ 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
Rebasing unstable change after pull
----------------------------------------------
-Remotely someone add a new changeset on top of our mutable "bathroom" on.
+Remotely someone add a new changeset on top of the mutable "bathroom" on.
$ hg up 8a79ae8b029e -q
$ cat >> shopping << EOF
@@ -461,21 +535,27 @@
> Lion
> Bear
> EOF
- $ hg ci -m 'animals' -q # XXX remove the -q
+ $ hg ci -m 'animals'
-While this time locally, we updated "bathroom changeset"
+But at the same time, locally, this same "bathroom changeset" was updated.
$ cd ../local
$ hg up 8a79ae8b029e -q
$ sed -i'' -e 's/... More bathroom stuff to come/Bath Robe/' shopping
$ hg amend
- $ hg log
- ffa278c50818 (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ ffa278c50818 (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
When we pull from remote again we get an unstable state!
@@ -490,22 +570,12 @@
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads .' to see heads, 'hg merge' to merge)
1 new unstables changesets
- $ hg log -r 'extinct()'
- $ hg log
- 9ac5d0e790a2 (draft): animals
- ffa278c50818 (draft): bathroom stuff
- 8a79ae8b029e (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
The new changeset "animal" is based one an old changeset of "bathroom". You can
-see both version showing up the log.
+see both version showing up in the log.
- $ hg glog
+ $ hg log -G
o 9ac5d0e790a2 (draft): animals
|
| @ ffa278c50818 (draft): bathroom stuff
@@ -523,39 +593,61 @@
o 7e82d3f3c2cb (public): Monthy Python Shopping list
-In hgview there is a nice doted relation highlighting ffa278c50818 is a new
-version of 8a79ae8b029e. this is not yet ported to graphlog.
+The older version 8a79ae8b029e never ceased to exist in the local repo. It was
+jsut hidden and excluded from pull and push.
+
+.. note:: In hgview there is a nice doted relation highlighting ffa278c50818 as a new version of 8a79ae8b029e. this is not yet ported to graphlog.
+
+Their is **unstable** changeset in this history now. Mercurial will refuse to
+share it with the outside:
+
+ $ hg push other
+ pushing to $TESTTMP/other
+ searching for changes
+ abort: Trying to push unstable changeset: 9ac5d0e790a2!
+ (use 'hg stabilize' to get a stable history (or --force to proceed))
+ [255]
+
+
+
To resolve this unstable state, you need to rebase 9ac5d0e790a2 onto
-ffa278c50818 the "hg stabilize" command will make this for you. It has a
---dry-run option to only suggest the next move
+ffa278c50818 the "hg stabilize" command will make this for you.
+
+It has a --dry-run option to only suggest the next move.
$ hg stabilize --dry-run
move:[15] animals
atop:[14] bathroom stuff
hg rebase -Dr 9ac5d0e790a2 -d ffa278c50818
-
Let's do it
$ hg rebase -Dr 9ac5d0e790a2 -d ffa278c50818
merging shopping
-The old version of bathroom is hidden again now.
+The old version of bathroom is hidden again.
- $ hg log
- 437efbcaf700 (draft): animals
- ffa278c50818 (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ 437efbcaf700 (draft): animals
+ |
+ o ffa278c50818 (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
We can push this evolution to remote
- $ hg push -f remote # XXX should not require -f
+ $ hg push remote
pushing to $TESTTMP/remote
searching for changes
adding changesets
@@ -566,8 +658,10 @@
remote get a warning that current working directory is based on an obsolete changeset
$ cd ../remote
- $ hg up . # XXX "loulz"
- 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ hg pull local # we up again to trigger the warning. it was displayed during the push
+ pulling from $TESTTMP/local
+ searching for changes
+ no changes found
Working directory parent is obsolete
$ hg up 437efbcaf700
@@ -581,7 +675,7 @@
$ sed -i'' -e 's/Spam/Spam Spam Spam Spam/g' shopping
$ hg commit -m "SPAM SPAM SPAM"
-Work I can keep getting localy
+I'm pulling its work locally.
$ cd ../local
$ hg pull remote
@@ -592,15 +686,23 @@
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)
- $ hg log
- ae45c0c3092a (draft): SPAM SPAM SPAM
- 437efbcaf700 (draft): animals
- ffa278c50818 (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ o ae45c0c3092a (draft): SPAM SPAM SPAM
+ |
+ @ 437efbcaf700 (draft): animals
+ |
+ o ffa278c50818 (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
In the mean time I noticed you can't buy animals in a super market and I kill the animal changeset:
@@ -613,19 +715,6 @@
The animals changeset is still displayed because the "SPAM SPAM SPAM" changeset
is neither dead or obsolete. My repository is in an unstable state again.
- $ hg log
- ae45c0c3092a (draft): SPAM SPAM SPAM
- 437efbcaf700 (draft): animals
- ffa278c50818 (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
-
- $ hg log -r 'unstable()'
- ae45c0c3092a (draft): SPAM SPAM SPAM
-
$ hg log -G
o ae45c0c3092a (draft): SPAM SPAM SPAM
|
@@ -643,7 +732,11 @@
|
o 7e82d3f3c2cb (public): Monthy Python Shopping list
-# XXX make this work
+
+ $ hg log -r 'unstable()'
+ ae45c0c3092a (draft): SPAM SPAM SPAM
+
+# XXX make kill stabilization works
# $ hg stabilize --any
# merging shopping
@@ -651,14 +744,21 @@
grafting revision 17
merging shopping
- $ hg log
- 20de1fb1cec5 (draft): SPAM SPAM SPAM
- ffa278c50818 (draft): bathroom stuff
- a2fccc2e7b08 (public): SPAM SPAM
- 387187ad9bd9 (public): adding fruit
- dfd3a2d7691e (public): adding condiment
- 9ca060c80d74 (public): SPAM
- 7e82d3f3c2cb (public): Monthy Python Shopping list
+ $ hg log -G
+ @ 20de1fb1cec5 (draft): SPAM SPAM SPAM
+ |
+ o ffa278c50818 (draft): bathroom stuff
+ |
+ o a2fccc2e7b08 (public): SPAM SPAM
+ |
+ o 387187ad9bd9 (public): adding fruit
+ |
+ o dfd3a2d7691e (public): adding condiment
+ |
+ o 9ca060c80d74 (public): SPAM
+ |
+ o 7e82d3f3c2cb (public): Monthy Python Shopping list
+
Handling Conflicting amend
@@ -666,3 +766,5 @@
We can detect that multiple diverging//conflicting amend have been made. There
will be a "evol-merge" command to merge conflicting amend
+
+This command is not ready yet.