comparison docs/user-guide.rst @ 1268:ba3ff8c00304 stable

docs: explain --hidden option

Also move the discussion of revision numbers up, and splice the
explanation of --hidden into it.

1267:8cc6e90354a9

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.

Seeing hidden changesets
========================

TODO

Under the hood: Prune an unwanted changeset
===========================================

``prune`` (example 4 above) is the simplest history modification

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

TODO


Understanding revision numbers
==============================

If you're trying these examples on your own, especially using ``hg
log`` without ``--hidden``, you have probably noticed some funny
business going on with revision numbers: there are now gaps in the
sequence. That's something you don't see with plain vanilla Mercurial;
normally, revision N is always followed by revision N+1.

This is just the visible manifestation of hidden changesets. If
revision 95 is followed by revision 98, that means there are two
hidden changesets, 96 and 97, in between.

Note that changeset IDs are still the permanent, immutable identifier
for changesets. Revision numbers are, as ever, a handy shorthand that
work in your local repository, but cannot be used across repositories.
They also have the useful property of showing when there are hidden
changesets lurking under the covers, which is why this document uses
revision numbers.


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

1268:ba3ff8c00304

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

As the name implies, hidden changesets are normally not visible. If
you run ``hg log`` on the repository from Figure 2, Mercurial will
show revisions 0 and 3, but not 1 and 2. That's something you don't
see with plain vanilla Mercurial—normally, revision *N* is always
followed by revision *N* + 1.

This is just the visible manifestation of hidden changesets. If
revision 0 is followed by revision 3, that means there are two hidden
changesets, 1 and 2, in between.

To see those hidden changesets, use the ``--hidden`` option::

  $ hg --hidden log --graph --template '{rev}:{node|short}  {desc|firstline}\n'
  @  3:934359450037  implement feature Y
  |
  | x  2:6c5f78d5d467  temporary amend commit for fe0ecd3bd2a4
  | |
  | x  1:fe0ecd3bd2a4  implement feature Y
  |/
  o  0:08c4b6f4efc8  init

Note that changeset IDs are still the permanent, immutable identifier
for changesets. Revision numbers are, as ever, a handy shorthand that
work in your local repository, but cannot be used across repositories.
They also have the useful property of showing when there are hidden
changesets lurking under the covers, which is why this document uses
revision numbers.


Under the hood: Prune an unwanted changeset
===========================================

``prune`` (example 4 above) is the simplest history modification

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

TODO


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