annotate doc/evolve-faq.rst @ 158:3cdf8291fd97

this is an FAQ not a tutorial

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