comparison docs/user-guide.rst @ 4618:803d32f4e498

docs: change `unstable` references to `orphan`

Per https://www.mercurial-scm.org/wiki/CEDVocabulary

4617:2cab06f5c4d4

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

So far, every obsolete changeset we have seen is also hidden. However,
these are *not* the same thing—that's why they have different names.
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.

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 instability like unstable changesets and provides
a consistent way for you to get back to a stable repository.

(Incidentally, there are two other types of instability that changesets
can get into with ``evolve``: they may be *divergent* or
*bumped*. Both of those states are more likely to occur when

  $ hg update 11
  [...fix mistake...]
  $ hg amend

At this point, revision 11 is *obsolete* and revisions 12 and 13—the
descendants of 11—are in a funny state: they are *unstable*.

.. figure:: figures/figure-ug06.svg

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

(15-17) replace them.

.. figure:: figures/figure-ug07.svg

   Figure 7: evolve your repository (``hg evolve --all``) to take care
   of instability. Unstable changesets become obsolete, and are
   replaced by successors just like the amended changeset was.

Example 8: Prune an older changeset
===================================

You want to drop revision 19, but keep 18 and 20. No problem::

  $ hg prune 19
  1 changesets pruned
  1 new unstable changesets

As above, this leaves your repository in a funny intermediate state:
revision 20 is the non-obsolete descendant of obsolete revision 19.
That is, revision 20 is unstable.

.. figure:: figures/figure-ug08.svg

   Figure 8: ``hg prune`` marks a changeset obsolete without creating
   a successor. Just like with ``hg amend``, non-obsolete descendants
   of the pruned changeset are now unstable.

As before, the solution to unstable changesets is to evolve your
repository::

  $ hg evolve --all

This rebases revision 20 on top of 18 as the new revision 21, leaving

directory::

  $ hg update 22
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg uncommit file2.c
  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::

``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.

This is where things get tricky. As usual when a repository has
unstable changesets, we want to evolve it::

  $ hg evolve --all

The problem is that ``hg evolve`` rebases revision 27 onto revision
28, creating 30 (the successor of 27). This is entirely logical: 27

successor (30) should be the child of 26's successor (28).
Unfortunately, that leaves us with a two-headed repository:

.. figure:: figures/figure-ug12.svg

   Figure 12: ``evolve`` takes care of unstable changesets; it does
   not solve all the world's problems.

As usual when faced with a two-headed repository, you can either merge
or rebase. It's up to you.

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

4618:803d32f4e498

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

So far, every obsolete changeset we have seen is also hidden. However,
these are *not* the same thing—that's why they have different names.
It's entirely possible to have obsolete changesets that are not
hidden. We'll see examples of that soon, when we create *orphan*
changesets.

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

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 *orphan* changesets,
which is an unavoidable consequence of obsolescence. What really sets
``evolve`` apart from other history modification mechanisms is the
fact that it recognizes instability like orphan changesets and provides
a consistent way for you to get back to a stable repository.

(Incidentally, there are two other types of instability that changesets
can get into with ``evolve``: they may be *divergent* or
*bumped*. Both of those states are more likely to occur when

  $ hg update 11
  [...fix mistake...]
  $ hg amend

At this point, revision 11 is *obsolete* and revisions 12 and 13—the
descendants of 11—are in a funny state: they are *orphan*.

.. figure:: figures/figure-ug06.svg

   Figure 6: amending a changeset with descendants means the amended
   changeset is obsolete but remains visible; its non-obsolete
   descendants are *orphan*. 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
orphans. 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::

(15-17) replace them.

.. figure:: figures/figure-ug07.svg

   Figure 7: evolve your repository (``hg evolve --all``) to take care
   of instability. Orphan changesets become obsolete, and are
   replaced by successors just like the amended changeset was.

Example 8: Prune an older changeset
===================================

You want to drop revision 19, but keep 18 and 20. No problem::

  $ hg prune 19
  1 changesets pruned
  1 new orphan changesets

As above, this leaves your repository in a funny intermediate state:
revision 20 is the non-obsolete descendant of obsolete revision 19.
That is, revision 20 is an orphan.

.. figure:: figures/figure-ug08.svg

   Figure 8: ``hg prune`` marks a changeset obsolete without creating
   a successor. Just like with ``hg amend``, non-obsolete descendants
   of the pruned changeset are now orphans.

As before, the solution to orphan changesets is to evolve your
repository::

  $ hg evolve --all

This rebases revision 20 on top of 18 as the new revision 21, leaving

directory::

  $ hg update 22
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg uncommit file2.c
  1 new orphan changesets
  $ hg status
  M file2.c

Now your repository has orphan 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::

``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 orphan 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 orphan 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.

This is where things get tricky. As usual when a repository has
orphan changesets, we want to evolve it::

  $ hg evolve --all

The problem is that ``hg evolve`` rebases revision 27 onto revision
28, creating 30 (the successor of 27). This is entirely logical: 27

successor (30) should be the child of 26's successor (28).
Unfortunately, that leaves us with a two-headed repository:

.. figure:: figures/figure-ug12.svg

   Figure 12: ``evolve`` takes care of orphan changesets; it does
   not solve all the world's problems.

As usual when faced with a two-headed repository, you can either merge
or rebase. It's up to you.

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
orphan. It's also *divergent*, another type of trouble that we'll learn
about in the `next section`_.

.. _`next section`: sharing.html