bookmarks: improve the bookmark help (issue4244)

mercurial/commands.py

@@ -795,31 +795,45 b' def bisect(ui, repo, rev=None, extra=Non'
     ('i', 'inactive', False, _('mark a bookmark inactive'))],
     _('hg bookmarks [OPTIONS]... [NAME]...'))
 def bookmark(ui, repo, *names, **opts):
-    '''track a line of development with movable markers
-
-    Bookmarks are pointers to certain commits that move when committing.
-    Bookmarks are local. They can be renamed, copied and deleted. It is
-    possible to use :hg:`merge NAME` to merge from a given bookmark, and
-    :hg:`update NAME` to update to a given bookmark.
-
-    You can use :hg:`bookmark NAME` to set a bookmark on the working
-    directory's parent revision with the given name. If you specify
-    a revision using -r REV (where REV may be an existing bookmark),
-    the bookmark is assigned to that revision.
-
-    Bookmarks can be pushed and pulled between repositories (see :hg:`help
-    push` and :hg:`help pull`). This requires both the local and remote
-    repositories to support bookmarks. For versions prior to 1.8, this means
-    the bookmarks extension must be enabled.
-
-    If you set a bookmark called '@', new clones of the repository will
-    have that revision checked out (and the bookmark made active) by
-    default.
-
-    With -i/--inactive, the new bookmark will not be made the active
-    bookmark. If -r/--rev is given, the new bookmark will not be made
-    active even if -i/--inactive is not given. If no NAME is given, the
-    current active bookmark will be marked inactive.
+    '''create a new bookmark or list existing bookmarks
+
+    Bookmarks are labels on changesets to help track lines of development.
+    Bookmarks are unversioned and can be moved, renamed and deleted.
+    Deleting or moving a bookmark has no effect on the associated changesets.
+
+    Creating or updating to a bookmark causes it to be marked as 'active'.
+    Active bookmarks are indicated with a '*'.
+    When a commit is made, an active bookmark will advance to the new commit.
+    A plain :hg:`update` will also advance an active bookmark, if possible.
+    Updating away from a bookmark will cause it to be deactivated.
+
+    Bookmarks can be pushed and pulled between repositories (see
+    :hg:`help push` and :hg:`help pull`). If a shared bookmark has
+    diverged, a new 'divergent bookmark' of the form 'name@path' will
+    be created. Using :hg:'merge' will resolve the divergence.
+
+    A bookmark named '@' has the special property that :hg:`clone` will
+    check it out by default if it exists.
+
+    .. container:: verbose
+
+      Examples:
+
+      - create an active bookmark for a new line of development::
+
+          hg book new-feature
+
+      - create an inactive bookmark as a place marker::
+
+          hg book -i reviewed
+
+      - create an inactive bookmark on another changeset::
+
+          hg book -r .^ tested
+
+      - move the '@' bookmark from another branch::
+
+          hg book -f @
     '''
     force = opts.get('force')
     rev = opts.get('rev')

tests/test-globalopts.t

@@ -290,7 +290,7 b' Testing -h/--help:'
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
-   bookmarks     track a line of development with movable markers
+   bookmarks     create a new bookmark or list existing bookmarks
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
@@ -372,7 +372,7 b' Testing -h/--help:'
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
-   bookmarks     track a line of development with movable markers
+   bookmarks     create a new bookmark or list existing bookmarks
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file

tests/test-help.t

@@ -55,7 +55,7 b' Short help:'
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
-   bookmarks     track a line of development with movable markers
+   bookmarks     create a new bookmark or list existing bookmarks
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
@@ -131,7 +131,7 b' Short help:'
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
-   bookmarks     track a line of development with movable markers
+   bookmarks     create a new bookmark or list existing bookmarks
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
@@ -687,7 +687,7 b' Test that default list of commands omits'
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
-   bookmarks     track a line of development with movable markers
+   bookmarks     create a new bookmark or list existing bookmarks
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
@@ -952,7 +952,7 b' Test keyword search help'
   
   Commands:
   
-   bookmarks track a line of development with movable markers
+   bookmarks create a new bookmark or list existing bookmarks
    clone     make a copy of an existing repository
    paths     show aliases for remote repositories
    update    update working directory (or switch revisions)
@@ -1402,7 +1402,7 b' Dish up an empty repo; serve it cold.'
   bookmarks
   </a>
   </td><td>
-  track a line of development with movable markers
+  create a new bookmark or list existing bookmarks
   </td></tr>
   <tr><td>
   <a href="/help/branch">