comparison docs/index.rst @ 166:8f8a52cd0b9f

big doc update

165:ef6113f3d38e

Safe Mutable History
========================================


Here are various Materials on planned improvement to mercurial regarding
rewriting mutable history.

The effort  split in two part:

 * The **obsolete marker** concept aiming to provide and alternative to strip to
   get ride of changesets.

 * A mercurial extension: **evolve** that rewrite using *obsolete marker*
   under the hood.


regarding mercurial internals, the first and most important step is 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 the obsolete
marker. 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 any kind history. Even history with branch and merge.

* Use robust mercurial's merge mechanism 

  simple conflict are handled by real merge tools using appropriate ancestor.
  Conflict are much rarer and much more user friendly.

* All mutable history available at the same 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 collaborating 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

To enable the evolve extension use::

    $ hg clone http://hg-dev.octopoid.net/hgwebdir.cgi/mutable-history/
    $ mutable-history/enable.sh > ~/.hgrc


.. toctree::
   :maxdepth: 1

   tutorial
   evolve-faq
   from-mq

Smart changeset deletion: Obselete Marker
==========================================

for dev and advanced user


.. toctree::
   :maxdepth: 1

   obs-concept
   glossary
   obs-implementation






Know canveas
=================================

Big flashy warning on current remaining issue

166:8f8a52cd0b9f

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

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

Smart changeset deletion: Obselete 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.





Anexe
=================================

.. toctree::
   glossary