Mercurial > evolve

changeset 229:681e25e5d83a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[doc] update tutorial text.
author Pierre-Yves David <pierre-yves.david@logilab.fr>
date Wed, 09 May 2012 16:39:35 +0200
parents 5a17c0d41a00
children bcf095c8239c
files docs/index.rst docs/tutorials/tutorial.t
diffstat 2 files changed, 272 insertions(+), 170 deletions(-) [+]
line wrap: on
line diff
--- a/docs/index.rst	Wed May 09 14:24:56 2012 +0200
+++ b/docs/index.rst	Wed May 09 16:39:35 2012 +0200
@@ -90,7 +90,7 @@
 .. toctree::
    :maxdepth: 2
 
-   tutorial
+   tutorials/tutorial
    evolve-faq
    from-mq
    evolve-collaboration
--- 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.