changeset 93:1b962aaf0c7d

docs: Small tutorial
author Pierre-Yves David <pierre-yves.david@logilab.fr>
date Tue, 20 Sep 2011 18:17:08 +0200
parents 5b23cdf998d0
children 780a222d547d
files doc/simple-tuto.t
diffstat 1 files changed, 400 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/simple-tuto.t	Tue Sep 20 18:17:08 2011 +0200
@@ -0,0 +1,400 @@
+Mutable History and collaboration
+=====================================================================
+
+
+History mutation
+=====================
+
+.. Albert Beugras
+
+.. René de Robert
+
+
+Here is small introduction of 
+
+Single Developer Usage
+======================
+
+This tutorial shows how to use evolution to replace the basics of *mq*.
+
+
+Amending a changeset
+---------------------
+
+
+First there is some setup phase you will understand later.
+
+there is a local repository and a remote one.
+
+Please close your eyes.
+
+  $ hg init local
+  $ cat >> local/.hg/hgrc << EOF
+  > [paths]
+  > remote = ../remote
+  > [ui]
+  > user = Albert Beugras
+  > [diff]
+  > git = 1
+  > [alias]
+  > amend = amend -d '0 0'
+  > tlog = log --template "{node|short}: '{desc}'\n"
+  > ttlog = log --template "{node|short}: '{desc}' ({state})\n"
+  > tglog = log -G --template "{node|short}: '{desc}' {branches}\n"
+  > [extensions]
+  > hgext.graphlog=
+  > hgext.rebase=
+  > EOF
+  $ echo "states=$(echo $(dirname $TESTDIR))/hgext/states.py" >> local/.hg/hgrc
+  $ echo "obsolete=$(echo $(dirname $TESTDIR))/hgext/obsolete.py" >> local/.hg/hgrc
+  $ echo "evolution=$(echo $(dirname $TESTDIR))/hgext/evolution.py" >> local/.hg/hgrc
+  $ hg init remote
+  $ cat >> remote/.hg/hgrc << EOF
+  > [paths]
+  > local = ../local
+  > [ui]
+  > user = René de Robert
+  > [diff]
+  > git = 1
+  > [alias]
+  > amend = amend -d '0 0'
+  > tlog = log --template "{node|short}: '{desc}' {branches}\n"
+  > ttlog = log --template "{node|short}: '{desc}' {state}\n"
+  > tglog = log -G --template "{node|short}: '{desc}' {branches}\n"
+  > [extensions]
+  > hgext.graphlog=
+  > hgext.rebase=
+  > EOF
+  $ echo "states=$(echo $(dirname $TESTDIR))/hgext/states.py" >> remote/.hg/hgrc
+  $ echo "obsolete=$(echo $(dirname $TESTDIR))/hgext/obsolete.py" >> remote/.hg/hgrc
+  $ echo "evolution=$(echo $(dirname $TESTDIR))/hgext/evolution.py" >> remote/.hg/hgrc
+  $ cd local
+
+You can reopen you eyes.
+
+Now we make a first version of our shopping list.
+
+  $ cat  >> shopping << EOF
+  > Spam
+  > Whizzo butter
+  > Albatross
+  > Rat (rather a lot)
+  > Jugged fish
+  > Blancmange
+  > Salmon mousse
+  > EOF
+  $ hg commit -A -m "Monthy Python Shopping list"
+  adding shopping
+
+We share this first version with the outside.
+
+  $ hg push remote
+  pushing to $TESTTMP/remote
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files
+
+Later I add additional item to my list
+
+  $ cat >> shopping << EOF
+  > Egg
+  > Suggar
+  > Vinegar
+  > Oil
+  > EOF
+  $ hg commit -m "adding condiment"
+  $ cat >> shopping << EOF
+  > Bananos
+  > Pear
+  > Apple
+  > EOF
+  $ hg commit -m "adding fruit"
+
+I now have the following history:
+
+  $ hg tlog
+  d85de4546133: 'adding fruit'
+  4d5dc8187023: 'adding condiment'
+  7e82d3f3c2cb: 'Monthy Python Shopping list'
+
+But, I just notice, I made a typo in Banana.
+
+  $ hg export tip
+  # HG changeset patch
+  # User test
+  # Date 0 0
+  # Node ID d85de4546133030c82d257bbcdd9b1b416d0c31c
+  # Parent  4d5dc81870237d492284826e21840b2ca00e26d1
+  adding fruit
+  
+  diff --git a/shopping b/shopping
+  --- a/shopping
+  +++ b/shopping
+  @@ -9,3 +9,6 @@
+   Suggar
+   Vinegar
+   Oil
+  +Bananos
+  +Pear
+  +Apple
+
+hopefully. I can use hg amend to rewrite my faulty changeset!
+
+  $ sed -i'' s/Bananos/Banana/ shopping
+  $ hg diff
+  diff --git a/shopping b/shopping
+  --- a/shopping
+  +++ b/shopping
+  @@ -9,6 +9,6 @@
+   Suggar
+   Vinegar
+   Oil
+  -Bananos
+  +Banana
+   Pear
+   Apple
+  $ hg amend
+  abort: can not rewrite immutable changeset d85de4546133
+  [255]
+
+By default all changeset are considered "published" and can't be rewrittent.
+
+ $ hg ttlog
+
+You need to enable a mutable state in your repo the "ready" one
+
+  $ hg states ready # XXX --clever
+  $ hg ttlog
+  d85de4546133: 'adding fruit' (ready)
+  4d5dc8187023: 'adding condiment' (ready)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+
+Notice that changeset you already shared with the outside have been keep
+published.
+
+The changeset we want to rewrite is now in a mutable state.
+
+  $ hg amend
+
+A new changeset with the right diff replace the wrong one.
+
+  $ hg tlog
+  0cacb48f4482: 'adding fruit'
+  4d5dc8187023: 'adding condiment'
+  7e82d3f3c2cb: 'Monthy Python Shopping list'
+  $ hg export tip
+  # HG changeset patch
+  # User test
+  # Date 0 0
+  # Node ID 0cacb48f44828d2fd31c4e45e18fde32a5b2f07b
+  # Parent  4d5dc81870237d492284826e21840b2ca00e26d1
+  adding fruit
+  
+  diff --git a/shopping b/shopping
+  --- a/shopping
+  +++ b/shopping
+  @@ -9,3 +9,6 @@
+   Suggar
+   Vinegar
+   Oil
+  +Banana
+  +Pear
+  +Apple
+
+Getting Ride of branchy history
+----------------------------------
+
+While I was working on my list. someone help made a change remotly.
+
+close your eyes
+
+  $ cd ../remote
+  $ hg up -q
+  $ sed -i'' 's/Spam/Spam Spam Spam/' shopping
+  $ hg ci -m 'SPAM'
+  $ cd ../local
+
+open your eyes
+
+  $ hg pull remote
+  pulling from $TESTTMP/remote
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  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
+
+  $ hg ttlog
+  9ca060c80d74: 'SPAM' (published)
+  0cacb48f4482: 'adding fruit' (ready)
+  4d5dc8187023: 'adding condiment' (ready)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+  $ hg tglog -r "::(9ca060c80d74 + 0cacb48f4482)"
+  o  9ca060c80d74: 'SPAM'
+  |
+  | @  0cacb48f4482: 'adding fruit'
+  | |
+  | o  4d5dc8187023: 'adding condiment'
+  |/
+  o  7e82d3f3c2cb: 'Monthy Python Shopping list'
+  
+
+instead of merging my head with the new one. I'm going to rebase my work
+
+  $ hg diff
+  $ hg rebase -d 9ca060c80d74 -s 4d5dc8187023
+  merging shopping
+  merging shopping
+  merging shopping
+  merging shopping
+
+
+My local work is now rebase on the remote one.
+
+  $ hg kill e7a71e229632 ad97bbd3e37d # XXX fix me instead
+  $ hg ttlog
+  387187ad9bd9: 'adding fruit' (ready)
+  dfd3a2d7691e: 'adding condiment' (ready)
+  9ca060c80d74: 'SPAM' (published)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+  $ hg tglog -r '::.'
+  @  387187ad9bd9: 'adding fruit'
+  |
+  o  dfd3a2d7691e: 'adding condiment'
+  |
+  o  9ca060c80d74: 'SPAM'
+  |
+  o  7e82d3f3c2cb: 'Monthy Python Shopping list'
+  
+
+Removing changeset
+========================
+
+I add new item to my list
+
+  $ cat >> shopping << EOF
+  > car
+  > bus
+  > plane
+  > boat
+  > EOF
+  $ hg ci -m 'transport'
+  $ hg ttlog
+  d58c77aa15d7: 'transport' (ready)
+  387187ad9bd9: 'adding fruit' (ready)
+  dfd3a2d7691e: 'adding condiment' (ready)
+  9ca060c80d74: 'SPAM' (published)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+
+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.
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  working directory now at 387187ad9bd9
+
+The silly changeset is gone.
+
+  $ hg ttlog
+  387187ad9bd9: 'adding fruit' (ready)
+  dfd3a2d7691e: 'adding condiment' (ready)
+  9ca060c80d74: 'SPAM' (published)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+
+Reordering changeset
+========================
+
+
+We create two changeset.
+
+
+  $ cat >> shopping << EOF
+  > Toothbrush
+  > Towel
+  > ... More bathroom stuff to come
+  > EOF
+  $ hg ci -m 'bathroom stuff' -q # XXX remove the -q
+
+  $ sed -i'' 's/Spam/Spam Spam Spam/g' shopping
+  $ hg ci -m 'SPAM SPAM'
+  $ hg ttlog
+  d19fa1996cc7: 'SPAM SPAM' (ready)
+  e64eb196cfd1: 'bathroom stuff' (ready)
+  387187ad9bd9: 'adding fruit' (ready)
+  dfd3a2d7691e: 'adding condiment' (ready)
+  9ca060c80d74: 'SPAM' (published)
+  7e82d3f3c2cb: 'Monthy Python Shopping list' (published)
+
+.. 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"
+
+You can use rebase or relocate for that:
+
+  $ hg relocate 'p1(e64eb196cfd1)' --traceback
+  merging shopping
+  $ hg tglog -r '::(. + e64eb196cfd1)'
+  @  e96fa9b78e3d: 'SPAM SPAM'
+  |
+  | o  e64eb196cfd1: 'bathroom stuff'
+  |/
+  o  387187ad9bd9: 'adding fruit'
+  |
+  o  dfd3a2d7691e: 'adding condiment'
+  |
+  o  9ca060c80d74: 'SPAM'
+  |
+  o  7e82d3f3c2cb: 'Monthy Python Shopping list'
+  
+
+We have a new SPAM SPAM version without the bathroom stuff
+
+  $ grep Spam shopping  # enouth spamm
+  Spam Spam Spam Spam Spam Spam Spam Spam Spam
+  $ grep Toothbrush shopping # no Toothbrush
+  [1]
+  $ hg export .
+  # HG changeset patch
+  # User test
+  # Date 0 0
+  # Node ID e96fa9b78e3d2e21b604d4e05582bb1906a9bc59
+  # Parent  387187ad9bd9d8f9a00a9fa804a26231db547429
+  SPAM SPAM
+  
+  diff --git a/shopping b/shopping
+  --- a/shopping
+  +++ b/shopping
+  @@ -1,4 +1,4 @@
+  -Spam Spam Spam
+  +Spam Spam Spam Spam Spam Spam Spam Spam Spam
+   Whizzo butter
+   Albatross
+   Rat (rather a lot)
+
+we can now push our change:
+
+  $ hg push -r . remote
+  pushing to $TESTTMP/remote
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 3 changesets with 3 changes to 1 files
+
+collaboration
+====================
+
+
+
+We create a central repo (because most workflow include this central repo
+
+  $ cd ..
+  $ hg init central