comparison docs/user-guide.rst @ 2931:83d2c9637e89

user-guide: edit pass

2930:7932a0deae18

*draft* phase by default: they are mutable. This means that they can
be modified by Mercurial's existing history-editing commands
(``rebase``, ``histedit``, etc.), and also by the ``evolve``
extension. Specifically, ``evolve`` adds a number of commands that can
be used to modify history: ``amend``, ``uncommit``, ``prune``,
``fold``, and ``evolve``. Generally speaking, changesets remain in
*draft* phase until they are pushed to another repository, at which
point they enter *public* phase. ::

  $ hg commit -m 'implement feature X'
  $ hg phase -r .
  1: draft

(Strictly speaking, changesets only become public when they are pushed
to a *publishing* repository. But all repositories are publishing by
default; you have to explicitly configure repositories to be
*non-publishing*. Non-publishing repositories are an advanced topic
which we'll see when we get to `sharing mutable history`_.)

.. _`sharing mutable history`: sharing.html

  $ hg commit --amend -m 'implement feature Y'

to create a new, amended changeset. The drawback of doing this with
vanilla Mercurial is that your original, flawed, changeset is removed
from the repository. This is *unsafe* history editing. It's probably
not too serious if all you did was fix a syntax error, but still.

.. figure:: figures/figure-ug01.svg

   Figure 1: unsafe history modification with core Mercurial (not
   using ``evolve``): the original revision 1 is destroyed.

(Incidentally, Mercurial's traditional history modification mechanism
isn't *really* unsafe: any changeset(s) removed from the repository
are kept in a backup directory, so you can manually restore them later
if you change your mind. But it's awkward and inconvenient compared to
the features provided by ``evolve`` and changeset obsolescence.)

Life with ``evolve`` (basic usage)
----------------------------------

Once you enable the ``evolve`` extension, a number of features are

difference is that ``hg amend`` reuses the existing commit message by
default, whereas ``hg commit --amend`` runs your editor if you don't
pass ``-m`` or ``-l``.)

Under the hood, though, things are quite different. Mercurial has
simply marked the old changeset *obsolete*, replacing it with a new
one. We'll explore what this means in detail later, after working
through a few more examples.

Example 4: Prune an unwanted changeset
======================================

  8:be6d5bc8e4cc  step 2
  9:35f432d9f7c1  step 3

and fold them::

  $ hg fold -m 'fix bug 64' -r 7::
  3 changesets folded
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

This time, Mercurial marks three changesets obsolete, replacing them
all with a single *successor*.

understand the more advanced use cases we'll see later.

When you have the ``evolve`` extension enabled, all history
modification uses the same underlying mechanism: the original
changesets are marked *obsolete* and replaced by zero or more
*successors*. The obsolete changesets are the *precursors* of their
successors. This applies equally to built-in commands (``commit
--amend``), commands added by ``evolve`` (``amend``, ``prune``,
``uncommit``, ``fold``), and commands provided by other extensions
(``rebase``, ``histedit``).

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

Consider Example 2, amending a changeset with ``evolve``. We saw above
that you can do this using the exact same command-line syntax as core
Mercurial, namely ``hg commit --amend``. But the implementation is
quite different, and Figure 2 shows how.

.. figure:: figures/figure-ug02.svg

   Figure 2: safe history modification using ``evolve``: the original
   revision 1 is preserved as an obsolete changeset. (The "temporary
   amend commit", marked with T, is an implementation detail stemming
   from limitations in Mercurial's current merge machinery. Future
   versions of Mercurial will not create them.)

In this case, the obsolete changesets are also *hidden*. That is the
usual end state for obsolete changesets. But many scenarios result in
obsolete changesets that are still visible, which indicates your
history modification work is not yet done. We'll see examples of that
later, when we cover advanced usage.


Understanding revision numbers and hidden changesets

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

``prune`` (example 4 above) is the simplest history modification
command provided by ``evolve``. All it does is mark the specified
changeset(s) obsolete, with no successor/precursor relationships
involved. (If the working directory parent was one of the obsolete
changesets, ``prune`` updates back to a suitable ancestor.)

.. figure:: figures/figure-ug03.svg

   Figure 3: pruning a changeset marks it obsolete with no successors.

Under the hood: Uncommit changes to certain files
=================================================

In one sense, ``uncommit`` is a simplified version of ``amend``. Like
``amend``, it obsoletes one changeset and leaves it with a single
successor. Unlike ``amend``, there is no ugly "temporary amend commit"
cluttering up the repository.

In another sense, ``uncommit`` is the inverse of ``amend``: ``amend``
takes any uncommitted changes in the working dir and “adds”
them to the working directory's parent changeset. (In reality, of
course, it creates a successor changeset, marking the original
obsolete.) In contrast, ``uncommit`` takes some changes in the working
directory's parent and moves them to the working dir, creating a new
successor changeset in the process. Figure 4 illustrates.

It's entirely possible to have obsolete changesets that are not
hidden. We'll see examples of that soon, when we create *unstable*
changesets.

Note that all hidden changesets are obsolete: hidden is a subset of
obsolete.


Life with ``evolve`` (advanced usage)
-------------------------------------

Now that you've got a solid understanding of how ``evolve`` works in
concert with changeset obsolescence, let's explore some more advanced
scenarios. All of these scenarios will involve *unstable* changesets,
which is an unavoidable consequence of obsolescence. What really sets
``evolve`` apart from other history modification mechanisms is the
fact that it recognizes troubles like unstable changesets and provides
a consistent way for you to get out of trouble.

(Incidentally, there are two other types of trouble that changesets
can get into with ``evolve``: they may be *divergent* or *bumped*.
Both of those states are more likely to occur when `sharing mutable
history`_, so we won't see them in this user guide.)

.. _`sharing mutable history`: sharing.html


Example 7: Amend an older changeset
===================================

Sometimes you don't notice your mistakes until after you have
committed new changesets on top of them. ::

  $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
  $ hg commit -m 'cleanup'            # rev 12
  $ hg commit -m 'feature 23'         # rev 13

   Figure 6: amending a changeset with descendants means the amended
   changeset is obsolete but remains visible; its non-obsolete
   descendants are *unstable*. The temporary amend commit, revision
   14, is hidden because it has no non-obsolete descendants.

All non-obsolete descendants of an obsolete changeset are unstable. An
interesting consequence of this is that revision 11 is still visible,
even though it is obsolete. Obsolete changesets with non-obsolete
descendants are not hidden.

The fix is to *evolve* history::

  $ hg evolve --all

This is a separate step, not automatically part of ``hg amend``,
because there might be conflicts. If your amended changeset modifies a
file that one of its descendants also modified, Mercurial has to fire
up your merge tool to resolve the conflict. More importantly, you have
to switch contexts from "writing code" to "resolving conflicts". That
can be an expensive context switch, so Mercurial lets you decide when
to do it.

The end state, after ``evolve`` finishes, is that the original
revisions (11-13) are obsolete and hidden. Their successor revisions
(15-17) replace them.

  1 new unstable changesets
  $ hg status
  M file2.c

Now your repository has unstable changesets, so you need to evolve it.
But ``hg evolve`` requires a clean working directory to resolve merge
conflicts, so you need to decide what to do with ``file2.c``.

In this case, the change to ``file2.c`` was a temporary debugging
hack, so we can discard it and immediately evolve the instability away::

  $ hg commit -u dan -d '11 0' -m 'fix a bug'     # rev 26 (oops)
  $ echo 'new feature' >> file1.c
  $ hg commit -u dan -d '12 0' -m 'new feature'   # rev 27 (fine)

As before, we update back to the flawed changeset (this time,
revision 26) and ``uncommit``, leaving uncommitted changes to
``file2.c`` in the working dir::

  $ hg update -q 26
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg uncommit -q file2.c                        # obsoletes rev 26, creates rev 28
  1 new unstable changesets
  $ hg status
  M file2.c

This time, let's save that useful change before evolving::

  $ hg commit -m 'useful tweak'                   # rev 29

Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26
and created revision 28, the successor of 26. Then we committed
revision 29, a child of 28. We still have to deal with the unstable
revision 27.

.. figure:: figures/figure-ug11.svg

   Figure 11: Uncommitting a file and then committing that change
   separately will soon result in a two-headed repository.

as ``REV``, and will be a successor of ``REV``.

The current implementation of ``hg touch`` is not ideal, and is likely to
change in the future. Consider the history in Figure 12, where revision 27
is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
creates a new revision which is a non-obsolete child of 26—i.e., it is
unstable. It's also *divergent*, another type of trouble that we'll learn
about in the `next section`_.

.. _`next section`: sharing.html

2931:83d2c9637e89

*draft* phase by default: they are mutable. This means that they can
be modified by Mercurial's existing history-editing commands
(``rebase``, ``histedit``, etc.), and also by the ``evolve``
extension. Specifically, ``evolve`` adds a number of commands that can
be used to modify history: ``amend``, ``uncommit``, ``prune``,
``fold``, and ``evolve``. ::

  $ hg commit -m 'implement feature X'
  $ hg phase -r .
  1: draft

Generally speaking, changesets remain in *draft* phase until they are
pushed to another repository, at which point they enter the *public*
phase. (Strictly speaking, changesets only become public when they are
pushed to a *publishing* repository. But all repositories are publishing
by default; you have to explicitly configure repositories to be
*non-publishing*. Non-publishing repositories are an advanced topic
which we'll see when we get to `sharing mutable history`_.)

.. _`sharing mutable history`: sharing.html

  $ hg commit --amend -m 'implement feature Y'

to create a new, amended changeset. The drawback of doing this with
vanilla Mercurial is that your original, flawed, changeset is removed
from the repository. This is *unsafe* history editing. It's probably
not too serious if all you did was fix a syntax error, but for deeper
changes there can be more serious consequences to unsafe history editing.

.. figure:: figures/figure-ug01.svg

   Figure 1: unsafe history modification with core Mercurial (not
   using ``evolve``): the original revision 1 is destroyed.

(Incidentally, Mercurial's traditional history modification mechanism
isn't *really* unsafe: any changeset(s) removed from the repository
are kept in a backup directory, so you can manually restore them later
if you change your mind. However, this mechanism is very awkward and
inconvenient compared to the features provided by ``evolve`` and
changeset obsolescence.)

Life with ``evolve`` (basic usage)
----------------------------------

Once you enable the ``evolve`` extension, a number of features are

difference is that ``hg amend`` reuses the existing commit message by
default, whereas ``hg commit --amend`` runs your editor if you don't
pass ``-m`` or ``-l``.)

Under the hood, though, things are quite different. Mercurial has
simply marked the old changeset as *obsolete*, replacing it with a new
one. We'll explore what this means in detail later, after working
through a few more examples.

Example 4: Prune an unwanted changeset
======================================

  8:be6d5bc8e4cc  step 2
  9:35f432d9f7c1  step 3

and fold them::

  $ hg fold -m 'fix bug 64' -r 7:: --exact
  3 changesets folded
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

This time, Mercurial marks three changesets obsolete, replacing them
all with a single *successor*.

understand the more advanced use cases we'll see later.

When you have the ``evolve`` extension enabled, all history
modification uses the same underlying mechanism: the original
changesets are marked *obsolete* and replaced by zero or more
*successors*. The obsolete changesets are the *predecessors* of their
successors. This applies equally to built-in commands (``commit
--amend``), commands added by ``evolve`` (``amend``, ``prune``,
``uncommit``, ``fold``), and commands provided by other extensions
(``rebase``, ``histedit``).

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

Consider Example 2, amending a changeset with ``evolve``. We saw above
that you can do this using the exact same command-line syntax as core
Mercurial, namely ``hg commit --amend``. But the implementation is
quite different, as Figure 2 shows.

.. figure:: figures/figure-ug02.svg

   Figure 2: safe history modification using ``evolve``: the original
   revision 1 is preserved as an obsolete changeset. (The "temporary
   amend commit", marked with T, is an implementation detail stemming
   from limitations in Mercurial's current merge machinery. Future
   versions of Mercurial will not create them.)

In this case, the obsolete changesets are also *hidden*. That is the
usual end state for obsolete changesets. However, many scenarios result
in obsolete changesets that are still visible, which indicates your
history modification work is not yet done. We'll see examples of that
later, when we cover advanced usage.


Understanding revision numbers and hidden changesets

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

``prune`` (example 4 above) is the simplest history modification
command provided by ``evolve``. All it does is mark the specified
changeset(s) obsolete, with no successor/precursor relationships
involved. (If the working directory parent was one of the obsoleted
changesets, ``prune`` updates back to a suitable ancestor.)

.. figure:: figures/figure-ug03.svg

   Figure 3: pruning a changeset marks it obsolete with no successors.

Under the hood: Uncommit changes to certain files
=================================================

In one sense, ``uncommit`` is a simplified version of ``amend``. Like
``amend``, it obsoletes one changeset and leaves it with a single
successor. In another sense, ``uncommit`` is the inverse of ``amend``:
``amend`` takes any uncommitted changes in the working dir and “adds”
them to the working directory's parent changeset. (In reality, of
course, it creates a successor changeset, marking the original
obsolete.) In contrast, ``uncommit`` takes some changes in the working
directory's parent and moves them to the working dir, creating a new
successor changeset in the process. Figure 4 illustrates.

It's entirely possible to have obsolete changesets that are not
hidden. We'll see examples of that soon, when we create *unstable*
changesets.

Note that all hidden changesets are obsolete: hidden is a subset of
obsolete. This is explained in more depth in the `concepts`_ section.

.. _`concepts`: concepts.html

Life with ``evolve`` (advanced usage)
-------------------------------------

Now that you've got a solid understanding of how ``evolve`` works in
concert with changeset obsolescence, let's explore some more advanced
scenarios. All of these scenarios will involve *unstable* changesets,
which is an unavoidable consequence of obsolescence. What really sets
``evolve`` apart from other history modification mechanisms is the
fact that it recognizes troubles like unstable changesets and provides
a consistent way for you to get back to a stable repository.

(Incidentally, there are two other types of troubles that changesets
can get into with ``evolve``: they may be *divergent* or
*bumped*. Both of those states are more likely to occur when
`sharing mutable history`_, so we won't cover them in this user guide.)

.. _`sharing mutable history`: sharing.html


Example 7: Amend an older changeset
===================================

Sometimes you don't notice a mistake until after you have committed
new changesets on top of the changeset with the mistake. ::

  $ hg commit -m 'fix bug 17'         # rev 11 (mistake here)
  $ hg commit -m 'cleanup'            # rev 12
  $ hg commit -m 'feature 23'         # rev 13

   Figure 6: amending a changeset with descendants means the amended
   changeset is obsolete but remains visible; its non-obsolete
   descendants are *unstable*. The temporary amend commit, revision
   14, is hidden because it has no non-obsolete descendants.

All non-obsolete descendants of an obsolete changeset are considered
unstable. An interesting consequence of this is that revision 11 is
still visible, even though it is obsolete. Obsolete changesets with
non-obsolete descendants are not hidden.

The fix is to *evolve* history::

  $ hg evolve --all

This is a separate step, not automatically part of ``hg amend``,
because there might be conflicts. If your amended changeset modifies a
file that one of its descendants also modified, Mercurial has to fire
up your merge tool to resolve the conflict. More importantly, you have
to switch from "writing code" to "resolving conflicts". That can be an
expensive context switch, so Mercurial lets you decide when to do it.

The end state, after ``evolve`` finishes, is that the original
revisions (11-13) are obsolete and hidden. Their successor revisions
(15-17) replace them.

  1 new unstable changesets
  $ hg status
  M file2.c

Now your repository has unstable changesets, so you need to evolve it.
However, ``hg evolve`` requires a clean working directory to resolve merge
conflicts, so you need to decide what to do with ``file2.c``.

In this case, the change to ``file2.c`` was a temporary debugging
hack, so we can discard it and immediately evolve the instability away::

  $ hg commit -u dan -d '11 0' -m 'fix a bug'     # rev 26 (oops)
  $ echo 'new feature' >> file1.c
  $ hg commit -u dan -d '12 0' -m 'new feature'   # rev 27 (fine)

As before, we update back to the flawed changeset (this time,
revision 26) and use ``uncommit``, leaving uncommitted changes to
``file2.c`` in the working dir::

  $ hg update -q 26
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg uncommit -q file2.c  # obsoletes rev 26, creates rev 28
  1 new unstable changesets
  $ hg status
  M file2.c

This time, let's save that useful change before evolving::

  $ hg commit -m 'useful tweak'                   # rev 29

Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26
and created revision 28, the successor of 26. Then we committed
revision 29, a child of 28. We still have to deal with the revision 27,
which is an unstable changeset.

.. figure:: figures/figure-ug11.svg

   Figure 11: Uncommitting a file and then committing that change
   separately will soon result in a two-headed repository.

as ``REV``, and will be a successor of ``REV``.

The current implementation of ``hg touch`` is not ideal, and is likely to
change in the future. Consider the history in Figure 12, where revision 27
is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that
creates a new revision which is a non-obsolete child of 26—i.e., it is an
unstable. It's also *divergent*, another type of trouble that we'll learn
about in the `next section`_.

.. _`next section`: sharing.html