--- a/hgext/evolve.py	Fri Nov 06 18:37:16 2015 -0500
+++ b/hgext/evolve.py	Fri Nov 06 15:04:45 2015 -0500
@@ -1544,38 +1544,66 @@
     ] + mergetoolopts,
     _('[OPTIONS]...'))
 def evolve(ui, repo, **opts):
-    """solve troubles in your repository
-
-    - rebase unstable changesets to make them stable again,
-    - create proper diffs from bumped changesets,
-    - fuse divergent changesets back together,
-    - update to a successor if the working directory parent is
-      obsolete
-
-    If no argument are passed and the current working copy parent is obsolete,
-    :hg:`evolve` will update the working copy to the successors of this working
-    copy parent. If the working copy parent is not obsolete (and still no
-    argument passed) each invocation of :hg:`evolve` will evolve a single
-    unstable changeset, It will only select a changeset to be evolved if it
-    will result in a new children for the current working copy parent or its
-    descendants. The working copy will be updated on the result
-    (this last behavior will most likely to change in the future).
-    You can evolve all the unstable changesets that will be evolved on the
-    parent of the working copy and all its descendants recursively by using
-    :hg:`evolve` --all.
-
-    You can decide to evolve other categories of trouble using the --divergent
-    and --bumped flags. If no other option are specified, this will try to
-    solve the specified troubles for the working copy parent.
-
-    You can also evolve changesets affected by troubles of the selected
-    category using the --rev options. You can pick the next one anywhere in the
-    repo using --any.
-
-    You can evolve all the changesets affected by troubles of the selected
-    category using --all --any.
-
-    The working directory is updated to the newly created revision.
+    """solve troubled changesets in your repository
+
+    Modifying history can lead to various types of troubled changesets: unstable,
+    bumped, or divergent. The evolve command resolves your troubles by executing one
+    of the following actions:
+
+    - update working copy to a successor
+    - rebase an unstable changeset
+    - extract the desired changes from a bumped changeset
+    - fuse divergent changesets back together
+
+    If you pass no arguments, evolve works in automatic mode: it will execute a
+    single action to reduce instability related to your working copy. There are two
+    cases for this action. First, if the parent of your working copy is obsolete,
+    evolve updates to the parent's successor. Second, if the working copy parent is
+    not obsolete but has obsolete predecessors, then evolve determines if there is an
+    unstable changeset that can be rebased onto the working copy parent in order to
+    reduce instability. If so, evolve rebases that changeset. If not, evolve refuses
+    to guess your intention, and gives a hint about what you might want to do next.
+
+    Any time evolve creates a changeset, it updates the working copy to the new
+    changeset. (Currently, every successful evolve operation involves an update as
+    well; this may change in future.)
+
+    Automatic mode only handles common use cases. For example, it avoids taking
+    action in the case of ambiguity, and it ignores unstable changesets that are not
+    related to your working copy. It also refuses to solve bumped or divergent
+    changesets unless you explicity request such behavior (see below).
+
+    Eliminating all instability around your working copy may require multiple
+    invocations of :hg:`evolve`. Alternately, use ``--all`` to recursively select and
+    evolve all unstable changesets that can be rebased onto the working copy parent.
+    This is more powerful than successive invocations, since ``--all`` handles
+    ambiguous cases (e.g. unstable changesets with multiple children) by evolving all
+    branches.
+
+    When your repository cannot be handled by automatic mode, you might need to use
+    ``--rev`` to specify a changeset to evolve. For example, if you have an unstable
+    changeset that is not related to the working copy parent, you could use ``--rev``
+    to evolve it. Or, if some changeset has multiple unstable children, evolve in
+    automatic mode refuses to guess which one to evolve; you have to use ``--rev``
+    in that case.
+
+    Alternately, ``--any`` makes evolve search for the next evolvable changeset
+    regardless of whether it is related to the working copy parent.
+
+    You can supply multiple revisions to evolve multiple troubled changesets in a
+    single invocation. In revset terms, ``--any`` is equivalent to ``--rev
+    first(unstable())``. ``--rev`` and ``--all`` are mutually exclusive, as are
+    ``--rev`` and ``--any``.
+
+    ``hg evolve --any --all`` is useful for cleaning up instability across all
+    branches, letting evolve figure out the appropriate order and destination.
+
+    When you have troubled changesets that are not unstable, :hg:`evolve` refuses to
+    consider them unless you specify the category of trouble you wish to resolve,
+    with ``--bumped`` or ``--divergent``. These options are currently mutually
+    exclusive with each other and with ``--unstable`` (the default). You can combine
+    ``--bumped`` or ``--divergent`` with ``--rev``, ``--all``, or ``--any``.
+
     """
 
     # Options