changeset 1270:0683e3030316 stable

docs: cover 'touch' command

--- a/docs/user-guide.rst	Mon Apr 13 15:18:01 2015 -0400
+++ b/docs/user-guide.rst	Tue Apr 14 12:01:05 2015 -0400
@@ -572,4 +572,30 @@
 Example 11: Recover an obsolete changeset
 =========================================
 
-TODO
+Sometimes you might obsolete a changeset, and then change your mind. You'll
+probably start looking for an “unobsolete” command to restore a changeset
+to normal state. For complicated implementation reasons, that command
+doesn't exist. (If you have already pushed an obsolescence marker to
+another repo, then Mercurial would need a way to revoke that remote
+obsolesence marker. That's a hard problem.)
+
+Instead, ``evolve`` provides a ``touch`` command to resurrect an
+obsolete changeset. An unexpected quirk: you almost certainly need to
+use ``--hidden``, since obsolete changesets tend to be hidden, and you
+can't reference a hidden changeset otherwise. Typical usage thus looks
+like ::
+
+  $ hg --hidden touch REV
+
+This creates a new, normal changeset which is the same as ``REV``—except
+with a different changeset ID. The new changeset will have the same parent
+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