.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>

..                Logilab SA        <contact@logilab.fr>

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

Safe Mutable History

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

Here are various materials on planned improvement to Mercurial regarding

rewriting history.

First read about what challenge arise while rewriting history and how we plan to

solve them once and for all.

.. toctree::

   :maxdepth: 2

   instability

The effort is split in two parts:

 * The **obsolescence marker** concept aims to provide an alternative to ``strip``

   to get rid of changesets. This concept have been partially implemented in

   Mercurial 2.3.

 * The **evolve** mercurial extension rewrites history using obsolete

   *marker* under the hood.

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

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

this manual starts with changeset evolution.

Evolve: A robust alternative to MQ

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

Evolve is an experimental history rewriting extension that uses obsolete

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

them:

* Focus on your current work.

    You can focus your work on a single changeset and take care of adapting

    descendent changeset later.

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

* Rely internally on **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**.

  always use 'hg update' and forget about (un)applying patches to access the

  mutable part of your history.

* Use only **plain changeset** and forget about patches. Evole will create and

  exchange real changesets. Mutable history can be used in all usual operations:

  pull, push, log, diff, etc.

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

  (thanks to obsolete marker).

* Cover all mq usage but guard.

.. warning:: The evolve extension and obsolete markers are at an experimental

             stage. While using obsolete you willl likely be exposed to complex

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

             non-power users to test this at this stage.

             While numbered 1.0.0, the command line API of this version should

             **not** be regarded as *stable*, command behavior, name and

             options may change in future release or once integrated in

             mercurial. It is still an immature extension, a lot of

             features are still missing but there is no high risk of

             repository corruption.

             Production ready version should hide such details to normal user.

The evolve extension require mercurial 2.3

To enable the evolve extension use::

    $ hg clone https://bitbucket.org/marmoute/mutable-history -u stable

    $ echo '[extensions]\nevolve=$PWD/mutable-history/hgext/evolve.py' >> ~/.hgrc

You will probably want to use hgview_ to visualize obsolescence. Version 1.6.2

or later is required.

.. _hgview: http://www.logilab.org/project/hgview/

(The old version 0.7 of evolve works with mercurial 2.2 but have far less feature)

 ---

For more information see documents below:

.. toctree::

   :maxdepth: 1

   tutorials/tutorial

   evolve-good-practice

   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 rewriting process,

- clean final history,

- share and collaborate on mutable parts of the history,

- gracefully handle history rewriting conflicts,

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

 ---

For more information see documents below

.. toctree::

   :maxdepth: 1

   obs-concept

   obs-terms

   obs-implementation

Known limitation and bug

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

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

* you need to provide to `graft --continue -O` if you started you

  graft using `-O`.

  you to manually specify target all the time.

* trying to exchange obsolete marker with a static http repo will crash.

* Extinct changesets are hidden using the *hidden* feature of mercurial only

  supported by a few commands.

  Only ``hg log``, ``hgview`` and `hg glog` support it. ``hg head`` or other visual viewer don't.

* hg heads show extinct changeset