annotate docs/index.rst @ 227:abe52cf492ee

doc: several update and review.

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

   unstability

The effort is 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:

* 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 are **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.

  Evolve create and exchange real changeset only, not patches.
  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.

            XXX make sure to read the XXX section before using it.

            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
recommended). ::

    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/hgview/
    $ cd hgview
    $ python setup.py install --user

works with mercurial 2.1 and 2.2 (recommended)

 ---

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






Known limitation and bug
=================================

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



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

    You must fallback to graft or rebase when that happen.

* rewritinf conflict are not detected yet``hg stabilize`` does not handle them.

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

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

* hg merge considered extinct head as valid target. requiring you to manually
  specify target all the time.

* obsolete relation exchange crash (as in traceback) on static http repo.

* Extinct changeset are turned secret by various commands.

* Extinct changesets are hidden using the *hidden* feature of mercurial only
  supported by a few commands.

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

* hg heads show extinct changeset

Fixed in 2.2
---------------------------------

* hg graphlog show extinct changeset

* Mercurial 2.1 think you are pushing additional heads even when the new head
  obsolete another one. You have to use hg push -f more than necessary.





Annexe
=================================

.. toctree::
   :maxdepth: 1

   glossary