Mercurial > hg > evolve
changeset 229:681e25e5d83a
[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 +++ b/docs/index.rst @@ -90,7 +90,7 @@ .. toctree:: :maxdepth: 2 - tutorial + tutorials/tutorial evolve-faq from-mq evolve-collaboration
--- a/docs/tutorials/tutorial.t +++ b/docs/tutorials/tutorial.t @@ -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.