new file mode 100644
--- /dev/null
+++ b/doc/evolve-tutorial.rst
@@ -0,0 +1,189 @@
+========================================
+Introduction to the evolution extension
+========================================
+
+An history rewriting extension
+
+* Using the obsolete marker concept
+
+* Inspired from mq
+
+it is simple to enable::
+
+    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/
+    $ mutable-history/enable.sh > ~/.hgrc
+
+
+
+Quick Guide
+=====================================================================
+
+
+
+Add a changeset: ``commit``
+------------------------------------------------------------
+
+Just use commit as usual.
+
+Rewrite a changeset: ``amend``
+------------------------------------------------------------
+
+A new command ``hg amend`` is added by the extension. it write a new changeset
+combining working-directory parent changes and working directory parent changes.
+
+To understand what the result of amend will be I do use the two following
+aliases  [#]_::
+
+    # diff what amend will look likes
+    pdiff=diff --rev .^
+
+    # status what amend will look likes
+    pstatus=status --rev .^
+
+It take various options to choose the user, the date and the branch of the
+result. see ``hg help amend for detail``
+
+This command can be invoqued on any mutable changeset even changeset with
+children !
+
+
+.. note:: the amend command is very similar to mq's ``qrefresh``, a ``refresh``
+          alias for amend is also available. But note that contrary to
+          ``qrefresh``, ``amend`` does not exclude changes on file not specified
+          on the command line.
+
+          XXX add idank example
+
+
+.. [#] (added by enable.sh)
+
+
+
+Move a changeset: ``graft``
+------------------------------------------------------------
+
+the graft command introduced in 2.0 allows to "copy changes from other branches
+onto the current branch"
+
+The graft command have been altered to be able to create an obsolete marker from
+the copy result to the copy source, acting like changeset movement operation.
+This is achieved using a new flag `-O` (or `old-obsolete`) [#]_.
+
+
+XXX example
+
+.. warning:: when using graft --continue after conflict resolution you **MUST**
+             pass `-O` or `-o` flag again because they are not saved for now
+
+
+.. [#] add this `-O` to graft instead of a dedicated command is probably
+       abusive. But this was very convenient for experimental purpose.
+       This will likely change in non experimental release.
+
+Delete a changeset: ``kill``
+------------------------------------------------------------
+
+A new ``kill`` command allow to remove a changeset.
+
+Just use ``hg kill <some-rev>``.
+
+Moving within the history: ``up`` ``gdown`` and ``gup``
+------------------------------------------------------------
+
+While working on mutable part of the history you often need to move between
+mutable commit.
+
+You just need to use standard update to work with evolve. For convenience, you
+can use ``hg gup`` to move to children commit or ``hg gdown`` to move to working
+directory parent commit.
+
+.. note:: those command only exist for the convenience of getting qpush and qpop
+          feeling back.
+
+          They are 
+
+collapse changesets: ``amend``
+------------------------------------------------------------
+
+you can use amend -c to collapse multiple changeset in a single one.
+
+Move multiple changesets: ``rebase``
+------------------------------------------------------------
+
+You can still use rebase to move whole part of the changeset graph at once.
+
+.. warning:: Beware that rebasing obsolete changeset will result in new
+             conflicting version.
+
+Stabilize history: ``stabilize``
+------------------------------------------------------------
+
+When you rewrite changeset with children without rewriting those children you
+create *unstable* changeset and *suspended obsolete* changeset
+
+.. warning:: ``hg stabilize`` have no --continue to use after conflict
+             resolution
+
+.. warning:: stabilization does not handle deletion yet.
+
+.. warning:: obsolete currently rely on secret changeset to not exchange
+             obsolete and unstable changeset.
+
+             XXX details issue here
+
+
+Fix my history afterward: ``kill -n``
+------------------------------------------------------------
+
+sometime you need to create obsolete marker by hand. This may happen when
+upstream applied some of you patches for example.
+
+you can use ``hg kill --new <new-changeset> <old-changeset>`` to add obsolete
+marker.
+
+export to mq: ``synchronize``
+------------------------------------------------------------
+
+Another extension allows to export 
+
+view change to your file
+------------------------------------------------------------
+
+Another extension allows to export 
+
+view diff from the last amend
+------------------------------------------------------------
+
+an odiff alias have been added by enable.sh
+
+:: 
+    [alias]
+    odiff = diff --rev 'limit(obsparents(.),1)' --rev .
+
+view obsolete marker
+------------------------------------------------------------
+
+hgview is the only viewer that support this feature. you need an experimental
+version available here:
+
+    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/
+
+Important Note
+=====================================================================
+
+view change to your file
+------------------------------------------------------------
+
+extinct changeset are hidden using the *hidden* feature of mercurial.
+
+only hg log and hgview support it. hg glog or other visual viewer don't.
+
+
+
+
+
+
+
+
+
+