comparison docs/index.rst @ 2887:c1cf3c8947f1

index: edit pass by native english speaker

2886:00518926094f

  those changes to other repositories.

* It can automatically detect and handle the complex issues that can arise from
  exchanging draft changesets.

* It makes it even possible for multiple developers to rewrite the same part of
  the history in a distributed way.

* It fully respects the Phases concept so unsure users will only rewrite parts
  of the history that are safe to be changed. Phases have been part of Mercurial
  since early 2012.

.. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
.. _`Mercurial`: https://www.mercurial-scm.org/

Installation and setup

Then add in your `hgrc` config::

   [extensions]
   evolve=

You can easily edit the `hgrc` of repository using `hg config --local` or your
user configuration `hg config --edit`.

Table of Content
----------------

.. toctree::
   :maxdepth: 2

   index

   concepts
   from-mq

.. _`changeset evolution`:

What is Changeset Evolution ?
-----------------------------

With core Mercurial, changesets are permanent and immutable. You can
commit new changesets to modify your source code, but you cannot
modify or remove old changesets.

For years, Mercurial has included various commands that allow
history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
But there's a catch: until now, Mercurial's various mechanisms for
modifying history have been *unsafe*, in that changesets were
destroyed (“stripped”) rather than simply made hidden.

``evolve`` makes things better by changing the behaviour of most existing
history modification commands so they use a safer mechanism (*changeset
obsolescence*, covered below) rather than the older, less safe *strip*
operation.

  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
    Mercurial knows how history has been modified, specifically when
    one changeset replaces another. In the obsolescence model, a
    changeset is neither removed nor modified, but is instead marked
    *obsolete* and typically replaced by a *successor*. Obsolete
    changesets usually become *hidden* as well. Obsolescence is an
    disabled feature in Mercurial until you start using ``evolve``.

Some of the things you can do with ``evolve`` are:

  * Fix a mistake immediately: “Oops! I just committed a changeset

    unreviewed changesets, but you can't block every commit waiting
    for code review. The solution is to share mutable history with
    your reviewer, amending each changeset until it passes review.

  * Explore and audit the rewrite history of a changeset. Since Mercurial is
    tracking the edition you make to a changeset, you can look at the history of
    these editions. This is similar to Mercurial tracking the history of a file
    edition, but at the changeset level.

Why the `evolve` extension
--------------------------

Mercurial core already has some support for `changeset evolution`_ so why have a
dedicated extension?

The long-term plan for ``evolve`` is to add it to core Mercurial. However,
having the extension helps us experimenting with various user experience
approaches and technical prototype. Having a dedicated extensions help current
user to deploy the later changes quickly and provides the developers with
low latency feedbacks.

Whenever we are happy with a direction experimented in the extension, the
relevant code go upstream.

Development status
------------------

While well on the way, the full implementation of the `changeset evolution`_
concept is still in progress. Core Mercurial already supports many of the
associated features, but for now they are still disabled by default. The current
implementation has been usable for multiple years already, and some parts of it
are used in production in multiple projects and companies (including the
Mercurial project itself, Facebook, Google, etc…).

However, there are still some areas were the current implementation has gaps.
This means some use cases or performance issues are not handled as well as they
currently are without evolution. Mercurial has been around for a long time and
is strongly committed to backward compatibility, and turning evolution on by
default nowadays could regress the experience of some of our current users. The
feature will be enabled by default at the point where users who do not use or
care about the new features added by evolution won't be impacted by it. 

.. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE

Ressources
----------

  * For a practical guide to using ``evolve`` in a single repository,
    see the `user guide`_.
  * For more advanced tricks, see `sharing mutable history`_.
  * To learn about the concepts underlying ``evolve``, see `concepts`_

2887:c1cf3c8947f1

  those changes to other repositories.

* It can automatically detect and handle the complex issues that can arise from
  exchanging draft changesets.

* It even makes it possible for multiple developers to safely rewrite the same
  parts of history in a distributed way.

* It fully respects the Phases concept so users will only be able to rewrite
  parts of the history that are safe to change. Phases have been part of
  Mercurial since early 2012.

.. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
.. _`Mercurial`: https://www.mercurial-scm.org/

Installation and setup

Then add in your `hgrc` config::

   [extensions]
   evolve=

You can easily edit the `hgrc` of a repository using `hg config --local`.
Alternatively, you can edit your user configuration with `hg config --edit`.

Table of Contents
-----------------

.. toctree::
   :maxdepth: 2

   index

   concepts
   from-mq

.. _`changeset evolution`:

What is Changeset Evolution?
----------------------------

With core Mercurial, changesets are permanent and immutable. You can
commit new changesets to modify your source code, but you cannot
modify or remove old changesets.

For years, Mercurial has included various commands that allow
history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
However, there's a catch: until now, Mercurial's various mechanisms for
modifying history have been *unsafe*, in that changesets were
destroyed (“stripped”) rather than simply hidden and still easy to recover.

``evolve`` makes things better by changing the behaviour of most existing
history modification commands so they use a safer mechanism (*changeset
obsolescence*, covered below) rather than the older, less safe *strip*
operation.

  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
    Mercurial knows how history has been modified, specifically when
    one changeset replaces another. In the obsolescence model, a
    changeset is neither removed nor modified, but is instead marked
    *obsolete* and typically replaced by a *successor*. Obsolete
    changesets usually become *hidden* as well. Obsolescence is a
    disabled feature in Mercurial until you start using ``evolve``.

Some of the things you can do with ``evolve`` are:

  * Fix a mistake immediately: “Oops! I just committed a changeset

    unreviewed changesets, but you can't block every commit waiting
    for code review. The solution is to share mutable history with
    your reviewer, amending each changeset until it passes review.

  * Explore and audit the rewrite history of a changeset. Since Mercurial is
    tracking the edits you make to a changeset, you can look at the history of
    these edits. This is similar to Mercurial tracking the history of file
    edits, but at the changeset level.

Why the `evolve` extension?
---------------------------

Mercurial core already has some support for `changeset evolution`_ so why have a
dedicated extension?

The long-term plan for ``evolve`` is to add it to core Mercurial. However,
having the extension helps us experiment with various user experience
approaches and technical prototypes. Having a dedicated extension helps current
users deploy the latest changes quickly and provides developers with low latency
feedback.

Whenever we are happy with a experimental direction in the extension, the
relevant code can go upstream into Core Mercurial.

Development status
------------------

While well underway, the full implementation of the `changeset evolution`_
concept is still a work in progress. Core Mercurial already supports many of the
associated features, but for now they are still disabled by default. The current
implementation has been usable for multiple years already, and some parts of it
are used in production by multiple projects and companies (including the
Mercurial project itself, Facebook, Google, etc…).

However, there are still some areas were the current implementation has gaps.
This means some use cases or performance issues are not handled as well as they
currently are without evolution. Mercurial has been around for a long time and
is strongly committed to backward compatibility. Therefore turning evolution on
by default today could regress the experience of some of our current users. The
features will only be enabled by default at the point where users who do not use
or care about the new features added by evolution won't be negatively impacted
by the new default.

.. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE

Resources
---------

  * For a practical guide to using ``evolve`` in a single repository,
    see the `user guide`_.
  * For more advanced tricks, see `sharing mutable history`_.
  * To learn about the concepts underlying ``evolve``, see `concepts`_