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

Safe Mutable History

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

Here are various Materials on planned improvement to mercurial regarding

rewriting history.

The effort  splits in two parts:

 * The **obsolete marker** concept aims to provide and alternative to ``strip``

   to get ride of changesets.

 * The **evolve** mercurial extension to rewrite history using *obsolete marker*

   under the hood.

The first and most important step is by far the **obsolete marker**. However

most user will never be directly exposed to the concept. For this reason

document about changeset evolution are put first.

Evolve: A robust alternative to MQ

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

Evolve is an experimental history rewriting extensions that use obsolete

markers. It is inspired from MQ and pbranch but have multiple advantage over

them:

* sticks to "Work where you are" philosophy (I'll need better wording

  for that)

* Handle **non-linear history with branches and merges**

* Use **robust merge** mechanism of mercurial.

  simple conflict are handled by real merge tools using appropriate ancestor.

  Conflict are much rarer and much more user friendly.

*  Mutable history **fully available all the time**.

  You are do not need to unapply and apply patche to access various part of you

  history.

* Use **plain changeset** only. Evole create and exchange real changeset only. 

  Mutable history can be used in all usual operation 'pull, push, log, diff …)

* Allow **sharing and collaboration** mutable history without fear of duplicate.

  (thanks to obsolete marker).

* Cover all mq usage but guard.

.. warning:: The evolve extention and the obsolete marker are at an experimental

            stage. While using obsolet you'll likely be exposed to complexe

            implication of the **obsolete marker** concept. I do not recommend

            non power user to test this at this stage.

            Production ready version should hide such details to normal user.

To enable the evolve extension use::

    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/

    $ mutable-history/enable.sh >> ~/.hgrc

You will probably want to use the associated version of hgview (QT viewer

only). ::

    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/

    $ cd hgview

    $ python setup.py install --user

 ---

For more information see documents below

.. toctree::

   :maxdepth: 2

   tutorial

   evolve-faq

   from-mq

   evolve-collaboration

   qsync

Smart changeset deletion: Obsolete Marker

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

Obsolete marker is a powerful concept that allow mercurial to safely handle

history rewriting operations. It is a new type of relation between Mercurial

changesets that track the result of history rewriting operations.

This concept is simple to define and provides a very solid base to:

- Very fast history rewriting operations,

- auditable and reversible history rewritting process,

- clean final history,

- share and collaborate on mutable part of the history,

- gracefully handle history rewriting conflict,

- allows various history rewriting UI to collaborate with a underlying common API.

 ---

For more information see documents below

.. toctree::

   :maxdepth: 2

   obs-concept

   obs-implementation

Know canveas

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

Here is a list of know issue that will be fixed later:

* Unstable changeset turns secret.

* ``hg stabilize`` does not handle conflict.

* Mercurial think you are pushing additional heads even when the new head

  obsolete another one. You have to use hg push -f more than necessary.

* ``hg update`` can move an obsolete parent

* you need to provideto graft --continue -O if you started you graft using -O.

* hg graphlog show extinct changeset

* hg heads show extinct changeset

* hg merge considered extinct head as valid target. requiring you to manually

  specify target all the time.

Annexe

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

.. toctree::

   :maxdepth: 1

   glossary