========================================

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. is conflict occurs use::

               $ hg up -C . # cancel the failed merge

               $ hg stabilize -n # go get a command to execute

.. 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/

Prevent my unfinished changeset to get published

------------------------------------------------------------

The easiest way is to set them in the private phase

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.