import docstring from doc/hg.1.txt

mercurial/commands.py

@@ -476,7 +476,16 def help_(ui, cmd=None, with_version=Fal
 # Commands start here, listed alphabetically
 
 def add(ui, repo, *pats, **opts):
-    '''add the specified files on the next commit'''
+    """add the specified files on the next commit
+
+    Schedule files to be version controlled and added to the repository.
+
+    The files will be added to the repository at the next commit.
+
+    If no names are given, add all files in the current directory and
+    its subdirectories.
+    """
+
     names = []
     for src, abs, rel, exact in walk(repo, pats, opts):
         if exact:
@@ -488,7 +497,13 def add(ui, repo, *pats, **opts):
     repo.add(names)
 
 def addremove(ui, repo, *pats, **opts):
-    """add all new files, delete all missing files"""
+    """add all new files, delete all missing files
+
+    Add all new files and remove all missing files from the repository.
+
+    New files are ignored if they match any of the patterns in .hgignore. As
+    with add, these changes take effect at the next commit.
+    """
     add, remove = [], []
     for src, abs, rel, exact in walk(repo, pats, opts):
         if src == 'f' and repo.dirstate.state(abs) == '?':
@@ -503,7 +518,17 def addremove(ui, repo, *pats, **opts):
     repo.remove(remove)
 
 def annotate(ui, repo, *pats, **opts):
-    """show changeset information per file line"""
+    """show changeset information per file line
+
+    List changes in files, showing the revision id responsible for each line
+
+    This command is useful to discover who did a change or when a change took
+    place.
+
+    Without the -a option, annotate will avoid processing files it
+    detects as binary. With -a, annotate will generate an annotation
+    anyway, probably with undesirable results.
+    """
     def getnode(rev):
         return short(repo.changelog.node(rev))
 
@@ -551,7 +576,20 def annotate(ui, repo, *pats, **opts):
                 ui.write("%s: %s" % (" ".join(p), l[1]))
 
 def bundle(ui, repo, fname, dest="default-push", **opts):
-    """create a changegroup file"""
+    """create a changegroup file
+
+    Generate a compressed changegroup file collecting all changesets
+    not found in the other repository.
+
+    This file can then be transferred using conventional means and
+    applied to another repository with the unbundle command. This is
+    useful when native push and pull are not available or when
+    exporting an entire repository is undesirable. The standard file
+    extension is ".hg".
+
+    Unlike import/export, this exactly preserves all changeset
+    contents including permissions, rename data, and revision history.
+    """
     f = open(fname, "wb")
     dest = ui.expandpath(dest)
     other = hg.repository(ui, dest)
@@ -572,7 +610,19 def bundle(ui, repo, fname, dest="defaul
         raise
 
 def cat(ui, repo, file1, *pats, **opts):
-    """output the latest or given revisions of files"""
+    """output the latest or given revisions of files
+
+    Print the specified files as they were at the given revision.
+    If no revision is given then the tip is used.
+
+    Output may be to a file, in which case the name of the file is
+    given using a format string.  The formatting rules are the same as
+    for the export command, with the following additions:
+
+    %s   basename of file being printed
+    %d   dirname of file being printed, or '.' if in repo root
+    %p   root-relative path name of file being printed
+    """
     mf = {}
     if opts['rev']:
         change = repo.changelog.read(repo.lookup(opts['rev']))
@@ -593,7 +643,22 def cat(ui, repo, file1, *pats, **opts):
         fp.write(r.read(n))
 
 def clone(ui, source, dest=None, **opts):
-    """make a copy of an existing repository"""
+    """make a copy of an existing repository
+
+    Create a copy of an existing repository in a new directory.
+
+    If no destination directory name is specified, it defaults to the
+    basename of the source.
+
+    The location of the source is added to the new repository's
+    .hg/hgrc file, as the default to be used for future pulls.
+
+    For efficiency, hardlinks are used for cloning whenever the source
+    and destination are on the same filesystem.  Some filesystems,
+    such as AFS, implement hardlinking incorrectly, but do not report
+    errors.  In these cases, use the --pull option to avoid
+    hardlinking.
+    """
     if dest is None:
         dest = os.path.basename(os.path.normpath(source))
 
@@ -668,7 +733,16 def clone(ui, source, dest=None, **opts)
     d.close()
 
 def commit(ui, repo, *pats, **opts):
-    """commit the specified files or all outstanding changes"""
+    """commit the specified files or all outstanding changes
+
+    Commit changes to the given files into the repository.
+
+    If a list of files is omitted, all changes reported by "hg status"
+    from the root of the repository will be commited.
+
+    The HGEDITOR or EDITOR environment variables are used to start an
+    editor to add a commit comment.
+    """
     if opts['text']:
         ui.warn(_("Warning: -t and --text is deprecated,"
                   " please use -m or --message instead.\n"))
@@ -786,7 +860,22 def docopy(ui, repo, pats, opts):
     return errs, copied
 
 def copy(ui, repo, *pats, **opts):
-    """mark files as copied for the next commit"""
+    """mark files as copied for the next commit
+
+    Mark dest as having copies of source files.  If dest is a
+    directory, copies are put in that directory.  If dest is a file,
+    there can only be one source.
+
+    By default, this command copies the contents of files as they
+    stand in the working directory.  If invoked with --after, the
+    operation is recorded, but no copying is performed.
+
+    This command takes effect in the next commit.
+
+    NOTE: This command should be treated as experimental. While it
+    should properly record copied files, this information is not yet
+    fully used by merge, nor fully reported by log.
+    """
     errs, copied = docopy(ui, repo, pats, opts)
     return errs
 
@@ -927,7 +1016,22 def debugwalk(ui, repo, *pats, **opts):
         ui.write("%s\n" % line.rstrip())
 
 def diff(ui, repo, *pats, **opts):
-    """diff working directory (or selected files)"""
+    """diff working directory (or selected files)
+
+    Show differences between revisions for the specified files.
+
+    Differences between files are shown using the unified diff format.
+
+    When two revision arguments are given, then changes are shown
+    between those revisions. If only one revision is specified then
+    that revision is compared to the working directory, and, when no
+    revisions are specified, the working directory files are compared
+    to its parent.
+
+    Without the -a option, diff will avoid generating diffs of files
+    it detects as binary. With -a, diff will generate a diff anyway,
+    probably with undesirable results.
+    """
     node1, node2 = None, None
     revs = [repo.lookup(x) for x in opts['rev']]
 
@@ -968,7 +1072,29 def doexport(ui, repo, changeset, seqno,
         fp.close()
 
 def export(ui, repo, *changesets, **opts):
-    """dump the header and diffs for one or more changesets"""
+    """dump the header and diffs for one or more changesets
+
+    Print the changeset header and diffs for one or more revisions.
+
+    The information shown in the changeset header is: author,
+    changeset hash, parent and commit comment.
+
+    Output may be to a file, in which case the name of the file is
+    given using a format string.  The formatting rules are as follows:
+
+    %%   literal "%" character
+    %H   changeset hash (40 bytes of hexadecimal)
+    %N   number of patches being generated
+    %R   changeset revision number
+    %b   basename of the exporting repository
+    %h   short-form changeset hash (12 bytes of hexadecimal)
+    %n   zero-padded sequence number, starting at 1
+    %r   zero-padded changeset revision number
+
+    Without the -a option, export will avoid generating diffs of files
+    it detects as binary. With -a, export will generate a diff anyway,
+    probably with undesirable results.
+    """
     if not changesets:
         raise util.Abort(_("export requires at least one changeset"))
     seqno = 0
@@ -981,7 +1107,10 def export(ui, repo, *changesets, **opts
         doexport(ui, repo, cset, seqno, total, revwidth, opts)
 
 def forget(ui, repo, *pats, **opts):
-    """don't add the specified files on the next commit"""
+    """don't add the specified files on the next commit
+
+    Undo an 'hg add' scheduled for the next commit.
+    """
     forget = []
     for src, abs, rel, exact in walk(repo, pats, opts):
         if repo.dirstate.state(abs) == 'a':
@@ -991,7 +1120,21 def forget(ui, repo, *pats, **opts):
     repo.forget(forget)
 
 def grep(ui, repo, pattern, *pats, **opts):
-    """search for a pattern in specified files and revisions"""
+    """search for a pattern in specified files and revisions
+
+    Search revisions of files for a regular expression.
+
+    This command behaves differently than Unix grep.  It only accepts
+    Python/Perl regexps.  It searches repository history, not the
+    working directory.  It always prints the revision number in which
+    a match appears.
+
+    By default, grep only prints output for the first revision of a
+    file in which it finds a match.  To get it to print every revision
+    that contains a change in match status ("-" for a match that
+    becomes a non-match, or "+" for a non-match that becomes a match),
+    use the --all flag.
+    """
     reflags = 0
     if opts['ignore_case']:
         reflags |= re.I
@@ -1110,7 +1253,14 def grep(ui, repo, pattern, *pats, **opt
     return (count == 0 and 1) or 0
 
 def heads(ui, repo, **opts):
-    """show current repository heads"""
+    """show current repository heads
+
+    Show all repository head changesets.
+
+    Repository "heads" are changesets that don't have children
+    changesets. They are where development generally takes place and
+    are the usual targets for update and merge operations.
+    """
     heads = repo.changelog.heads()
     br = None
     if opts['branches']:
@@ -1119,7 +1269,13 def heads(ui, repo, **opts):
         show_changeset(ui, repo, changenode=n, brinfo=br)
 
 def identify(ui, repo):
-    """print information about the working copy"""
+    """print information about the working copy
+    Print a short summary of the current state of the repo.
+
+    This summary identifies the repository state using one or two parent
+    hash identifiers, followed by a "+" if there are uncommitted changes
+    in the working directory, followed by a list of tags for this revision.
+    """
     parents = [p for p in repo.dirstate.parents() if p != nullid]
     if not parents:
         ui.write(_("unknown\n"))
@@ -1141,7 +1297,19 def identify(ui, repo):
     ui.write("%s\n" % ' '.join(output))
 
 def import_(ui, repo, patch1, *patches, **opts):
-    """import an ordered set of patches"""
+    """import an ordered set of patches
+
+    Import a list of patches and commit them individually.
+
+    If there are outstanding changes in the working directory, import
+    will abort unless given the -f flag.
+
+    If a patch looks like a mail message (its first line starts with
+    "From " or looks like an RFC822 header), it will not be applied
+    unless the -f option is used.  The importer neither parses nor
+    discards mail headers, so use -f only to override the "mailness"
+    safety check, not to import a real mail message.
+    """
     patches = (patch1,) + patches
 
     if not opts['force']:
@@ -1204,7 +1372,14 def import_(ui, repo, patch1, *patches,
         repo.commit(files, message, user)
 
 def incoming(ui, repo, source="default", **opts):
-    """show new changesets found in source"""
+    """show new changesets found in source
+
+    Show new changesets found in the specified repo or the default
+    pull repo. These are the changesets that would be pulled if a pull
+    was requested.
+
+    Currently only local repositories are supported.
+    """
     source = ui.expandpath(source)
     other = hg.repository(ui, source)
     if not other.local():
@@ -1224,13 +1399,35 def incoming(ui, repo, source="default",
             ui.write("\n")
 
 def init(ui, dest="."):
-    """create a new repository in the given directory"""
+    """create a new repository in the given directory
+
+    Initialize a new repository in the given directory.  If the given
+    directory does not exist, it is created.
+
+    If no directory is given, the current directory is used.
+    """
     if not os.path.exists(dest):
         os.mkdir(dest)
     hg.repository(ui, dest, create=1)
 
 def locate(ui, repo, *pats, **opts):
-    """locate files matching specific patterns"""
+    """locate files matching specific patterns
+
+    Print all files under Mercurial control whose names match the
+    given patterns.
+
+    This command searches the current directory and its
+    subdirectories.  To search an entire repository, move to the root
+    of the repository.
+
+    If no patterns are given to match, this command prints all file
+    names.
+
+    If you want to feed the output of this command into the "xargs"
+    command, use the "-0" option to both this command and "xargs".
+    This will avoid the problem of "xargs" treating single filenames
+    that contain white space as multiple filenames.
+    """
     end = opts['print0'] and '\0' or '\n'
 
     for src, abs, rel, exact in walk(repo, pats, opts, '(?:.*/|)'):
@@ -1242,7 +1439,15 def locate(ui, repo, *pats, **opts):
             ui.write(rel, end)
 
 def log(ui, repo, *pats, **opts):
-    """show revision history of entire repository or files"""
+    """show revision history of entire repository or files
+
+    Print the revision history of the specified files or the entire project.
+
+    By default this command outputs: changeset id and hash, tags,
+    parents, user, date and time, and a summary for each commit. The
+    -v switch adds some more detail, such as changed files, manifest
+    hashes or message signatures.
+    """
     class dui:
         # Implement and delegate some ui protocol.  Save hunks of
         # output for later display in the desired order.
@@ -1310,7 +1515,13 def log(ui, repo, *pats, **opts):
                 ui.write(*args)
 
 def manifest(ui, repo, rev=None):
-    """output the latest or given revision of the project manifest"""
+    """output the latest or given revision of the project manifest
+
+    Print a list of version controlled files for the given revision.
+
+    The manifest is the list of files being version controlled. If no revision
+    is given then the tip is used.
+    """
     if rev:
         try:
             # assume all revision numbers are for changesets
@@ -1330,7 +1541,12 def manifest(ui, repo, rev=None):
         ui.write("%40s %3s %s\n" % (hex(m[f]), mf[f] and "755" or "644", f))
 
 def outgoing(ui, repo, dest="default-push", **opts):
-    """show changesets not found in destination"""
+    """show changesets not found in destination
+
+    Show changesets not found in the specified destination repo or the
+    default push repo. These are the changesets that would be pushed
+    if a push was requested.
+    """
     dest = ui.expandpath(dest)
     other = hg.repository(ui, dest)
     o = repo.findoutgoing(other)
@@ -1346,7 +1562,10 def outgoing(ui, repo, dest="default-pus
             ui.write("\n")
 
 def parents(ui, repo, rev=None):
-    """show the parents of the working dir or revision"""
+    """show the parents of the working dir or revision
+
+    Print the working directory's parent revisions.
+    """
     if rev:
         p = repo.changelog.parents(repo.lookup(rev))
     else:
@@ -1357,7 +1576,14 def parents(ui, repo, rev=None):
             show_changeset(ui, repo, changenode=n)
 
 def paths(ui, search=None):
-    """show definition of symbolic path names"""
+    """show definition of symbolic path names
+
+    Show definition of symbolic path name NAME. If no name is given, show
+    definition of available names.
+
+    Path names are defined in the [paths] section of /etc/mercurial/hgrc
+    and $HOME/.hgrc.  If run inside a repository, .hg/hgrc is used, too.
+    """
     try:
         repo = hg.repository(ui=ui)
     except hg.RepoError:
@@ -1375,7 +1601,26 def paths(ui, search=None):
             ui.write("%s = %s\n" % (name, path))
 
 def pull(ui, repo, source="default", **opts):
-    """pull changes from the specified source"""
+    """pull changes from the specified source
+
+    Pull changes from a remote repository to a local one.
+
+    This finds all changes from the repository at the specified path
+    or URL and adds them to the local repository. By default, this
+    does not update the copy of the project in the working directory.
+
+    Valid URLs are of the form:
+
+      local/filesystem/path
+      http://[user@]host[:port][/path]
+      https://[user@]host[:port][/path]
+      ssh://[user@]host[:port][/path]
+
+    SSH requires an accessible shell account on the destination machine
+    and a copy of hg in the remote path.  With SSH, paths are relative
+    to the remote user's home directory by default; use two slashes at
+    the start of a path to specify it as relative to the filesystem root.
+    """
     source = ui.expandpath(source)
     ui.status(_('pulling from %s\n') % (source))
 
@@ -1395,7 +1640,27 def pull(ui, repo, source="default", **o
     return r
 
 def push(ui, repo, dest="default-push", force=False, ssh=None, remotecmd=None):
-    """push changes to the specified destination"""
+    """push changes to the specified destination
+
+    Push changes from the local repository to the given destination.
+
+    This is the symmetrical operation for pull. It helps to move
+    changes from the current repository to a different one. If the
+    destination is local this is identical to a pull in that directory
+    from the current one.
+
+    By default, push will refuse to run if it detects the result would
+    increase the number of remote heads. This generally indicates the
+    the client has forgotten to sync and merge before pushing.
+
+    Valid URLs are of the form:
+
+      local/filesystem/path
+      ssh://[user@]host[:port][/path]
+
+    SSH requires an accessible shell account on the destination
+    machine and a copy of hg in the remote path.
+    """
     dest = ui.expandpath(dest)
     ui.status('pushing to %s\n' % (dest))
 
@@ -1409,7 +1674,13 def push(ui, repo, dest="default-push",
     return r
 
 def rawcommit(ui, repo, *flist, **rc):
-    "raw commit interface"
+    """raw commit interface
+
+    Lowlevel commit, for use in helper scripts.
+
+    This command is not intended to be used by normal users, as it is
+    primarily useful for importing from other SCMs.
+    """
     if rc['text']:
         ui.warn(_("Warning: -t and --text is deprecated,"
                   " please use -m or --message instead.\n"))
@@ -1434,11 +1705,25 def rawcommit(ui, repo, *flist, **rc):
         raise util.Abort(str(inst))
 
 def recover(ui, repo):
-    """roll back an interrupted transaction"""
+    """roll back an interrupted transaction
+
+    Recover from an interrupted commit or pull.
+
+    This command tries to fix the repository status after an interrupted
+    operation. It should only be necessary when Mercurial suggests it.
+    """
     repo.recover()
 
 def remove(ui, repo, pat, *pats, **opts):
-    """remove the specified files on the next commit"""
+    """remove the specified files on the next commit
+
+    Schedule the indicated files for removal from the repository.
+
+    This command schedules the files to be removed at the next commit.
+    This only removes files from the current branch, not from the
+    entire project history.  If the files still exist in the working
+    directory, they will be deleted from it.
+    """
     names = []
     def okaytoremove(abs, rel, exact):
         c, a, d, u = repo.changes(files = [abs])
@@ -1457,7 +1742,22 def remove(ui, repo, pat, *pats, **opts)
     repo.remove(names, unlink=True)
 
 def rename(ui, repo, *pats, **opts):
-    """rename files; equivalent of copy + remove"""
+    """rename files; equivalent of copy + remove
+
+    Mark dest as copies of sources; mark sources for deletion.  If
+    dest is a directory, copies are put in that directory.  If dest is
+    a file, there can only be one source.
+
+    By default, this command copies the contents of files as they
+    stand in the working directory.  If invoked with --after, the
+    operation is recorded, but no copying is performed.
+
+    This command takes effect in the next commit.
+
+    NOTE: This command should be treated as experimental. While it
+    should properly record rename files, this information is not yet
+    fully used by merge, nor fully reported by log.
+    """
     errs, copied = docopy(ui, repo, pats, opts)
     names = []
     for abs, rel, exact in copied:
@@ -1467,7 +1767,21 def rename(ui, repo, *pats, **opts):
     return errs
 
 def revert(ui, repo, *names, **opts):
-    """revert modified files or dirs back to their unmodified states"""
+    """revert modified files or dirs back to their unmodified states
+
+    Revert any uncommitted modifications made to the named files or
+    directories.  This restores the contents of the affected files to
+    an unmodified state.
+
+    If a file has been deleted, it is recreated.  If the executable
+    mode of a file was changed, it is reset.
+
+    If a directory is given, all files in that directory and its
+    subdirectories are reverted.
+
+    If no arguments are given, all files in the current directory and
+    its subdirectories are reverted.
+    """
     node = opts['rev'] and repo.lookup(opts['rev']) or \
            repo.dirstate.parents()[0]
     root = os.path.realpath(repo.root)
@@ -1515,11 +1829,20 def revert(ui, repo, *names, **opts):
     return r
 
 def root(ui, repo):
-    """print the root (top) of the current working dir"""
+    """print the root (top) of the current working dir
+
+    Print the root directory of the current repository.
+    """
     ui.write(repo.root + "\n")
 
 def serve(ui, repo, **opts):
-    """export the repository via HTTP"""
+    """export the repository via HTTP
+
+    Start a local HTTP repository browser and pull server.
+
+    By default, the server logs accesses to stdout and errors to
+    stderr.  Use the "-A" and "-E" options to log to files.
+    """
 
     if opts["stdio"]:
         fin, fout = sys.stdin, sys.stdout
@@ -1619,13 +1942,18 def serve(ui, repo, **opts):
     httpd.serve_forever()
 
 def status(ui, repo, *pats, **opts):
-    '''show changed files in the working directory
+    """show changed files in the working directory
 
+    Show changed files in the working directory.  If no names are
+    given, all files are shown.  Otherwise, only files matching the
+    given names are shown.
+
+    The codes used to show the status of files are:
     M = modified
     A = added
     R = removed
     ? = not tracked
-    '''
+    """
 
     cwd = repo.getcwd()
     files, matchfn, anypats = matchpats(repo, cwd, pats, opts)
@@ -1650,7 +1978,21 def status(ui, repo, *pats, **opts):
             ui.write(format % f)
 
 def tag(ui, repo, name, rev=None, **opts):
-    """add a tag for the current tip or a given revision"""
+    """add a tag for the current tip or a given revision
+
+    Name a particular revision using <name>.
+
+    Tags are used to name particular revisions of the repository and are
+    very useful to compare different revision, to go back to significant
+    earlier versions or to mark branch points as releases, etc.
+
+    If no revision is given, the tip is used.
+
+    To facilitate version control, distribution, and merging of tags,
+    they are stored as a file named ".hgtags" which is managed
+    similarly to other project files and can be hand-edited if
+    necessary.
+    """
     if opts['text']:
         ui.warn(_("Warning: -t and --text is deprecated,"
                   " please use -m or --message instead.\n"))
@@ -1686,7 +2028,12 def tag(ui, repo, name, rev=None, **opts
         raise util.Abort(str(inst))
 
 def tags(ui, repo):
-    """list repository tags"""
+    """list repository tags
+
+    List the repository tags.
+
+    This lists both regular and local tags.
+    """
 
     l = repo.tagslist()
     l.reverse()
@@ -1698,12 +2045,19 def tags(ui, repo):
         ui.write("%-30s %s\n" % (t, r))
 
 def tip(ui, repo):
-    """show the tip revision"""
+    """show the tip revision
+
+    Show the tip revision.
+    """
     n = repo.changelog.tip()
     show_changeset(ui, repo, changenode=n)
 
 def unbundle(ui, repo, fname):
-    """apply a changegroup file"""
+    """apply a changegroup file
+
+    Apply a compressed changegroup file generated by the bundle
+    command.
+    """
     f = urllib.urlopen(fname)
 
     if f.read(4) != "HG10":
@@ -1733,7 +2087,9 def undo(ui, repo):
     repo.undo()
 
 def update(ui, repo, node=None, merge=False, clean=False, branch=None):
-    '''update or merge working directory
+    """update or merge working directory
+
+    Update the working directory to the specified revision.
 
     If there are no outstanding changes in the working directory and
     there is a linear relationship between the current version and the
@@ -1744,7 +2100,10 def update(ui, repo, node=None, merge=Fa
     changed between either parent are marked as changed for the next
     commit and a commit must be performed before any further updates
     are allowed.
-    '''
+
+    By default, update will refuse to run if doing so would require
+    merging or discarding local changes.
+    """
     if branch:
         br = repo.branchlookup(branch=branch)
         found = []
@@ -1767,7 +2126,15 def update(ui, repo, node=None, merge=Fa
     return repo.update(node, allow=merge, force=clean)
 
 def verify(ui, repo):
-    """verify the integrity of the repository"""
+    """verify the integrity of the repository
+
+    Verify the integrity of the current repository.
+
+    This will perform an extensive check of the repository's
+    integrity, validating the hashes and checksums of each entry in
+    the changelog, manifest, and tracked files, as well as the
+    integrity of their crosslinks and indices.
+    """
     return repo.verify()
 
 # Command options and aliases are listed here, alphabetically
@@ -1775,23 +2142,23 def verify(ui, repo):
 table = {
     "^add":
         (add,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          "hg add [OPTION]... [FILE]..."),
     "addremove":
         (addremove,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
-         _("hg addremove [OPTION]... [FILE]...")),
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
+         "hg addremove [OPTION]... [FILE]..."),
     "^annotate":
         (annotate,
-         [('r', 'rev', '', _('revision')),
+         [('r', 'rev', '', _('annotate the specified revision')),
           ('a', 'text', None, _('treat all files as text')),
-          ('u', 'user', None, _('show user')),
-          ('n', 'number', None, _('show revision number')),
-          ('c', 'changeset', None, _('show changeset')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+          ('u', 'user', None, _('list the author')),
+          ('n', 'number', None, _('list the revision number (default)')),
+          ('c', 'changeset', None, _('list the changeset')),
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          _('hg annotate [OPTION]... FILE...')),
     "bundle":
         (bundle,
@@ -1799,34 +2166,34 table = {
          _('hg bundle FILE DEST')),
     "cat":
         (cat,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search')),
-          ('o', 'output', "", _('output to file')),
-          ('r', 'rev', '', _('revision'))],
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns')),
+          ('o', 'output', "", _('print output to file with formatted name')),
+          ('r', 'rev', '', _('print the given revision'))],
          _('hg cat [OPTION]... FILE...')),
     "^clone":
         (clone,
-         [('U', 'noupdate', None, _('skip update after cloning')),
-          ('e', 'ssh', "", _('ssh command')),
+         [('U', 'noupdate', None, _('do not update the new working directory')),
+          ('e', 'ssh', "", _('specify ssh command to use')),
           ('', 'pull', None, _('use pull protocol to copy metadata')),
-          ('', 'remotecmd', "", _('remote hg command'))],
+          ('', 'remotecmd', "", _('specify hg command to run on the remote side'))],
          _('hg clone [OPTION]... SOURCE [DEST]')),
     "^commit|ci":
         (commit,
-         [('A', 'addremove', None, _('run add/remove during commit')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search')),
-          ('m', 'message', "", _('commit message')),
+         [('A', 'addremove', None, _('run addremove during commit')),
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns')),
+          ('m', 'message', "", _('use <text> as commit message')),
           ('t', 'text', "", _('commit message (deprecated: use -m)')),
-          ('l', 'logfile', "", _('commit message file')),
-          ('d', 'date', "", _('date code')),
-          ('u', 'user', "", _('user'))],
+          ('l', 'logfile', "", _('read the commit message from <file>')),
+          ('d', 'date', "", _('record datecode as commit date')),
+          ('u', 'user', "", _('record user as commiter'))],
          _('hg commit [OPTION]... [FILE]...')),
     "copy|cp": (copy,
-             [('I', 'include', [], _('include path in search')),
-              ('X', 'exclude', [], _('exclude path from search')),
-              ('A', 'after', None, _('record a copy after it has happened')),
-              ('f', 'force', None, _('replace destination if it exists')),
+             [('I', 'include', [], _('include names matching the given patterns')),
+              ('X', 'exclude', [], _('exclude names matching the given patterns')),
+              ('A', 'after', None, _('record a copy that has already occurred')),
+              ('f', 'force', None, _('forcibly copy over an existing managed file')),
               ('p', 'parents', None, _('append source path to dest'))],
              _('hg copy [OPTION]... [SOURCE]... DEST')),
     "debugancestor": (debugancestor, [], _('debugancestor INDEX REV1 REV2')),
@@ -1840,38 +2207,38 table = {
     "debugrename": (debugrename, [], _('debugrename FILE [REV]')),
     "debugwalk":
         (debugwalk,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          _('debugwalk [OPTION]... [FILE]...')),
     "^diff":
         (diff,
          [('r', 'rev', [], _('revision')),
           ('a', 'text', None, _('treat all files as text')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          _('hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...')),
     "^export":
         (export,
-         [('o', 'output', "", _('output to file')),
+         [('o', 'output', "", _('print output to file with formatted name')),
           ('a', 'text', None, _('treat all files as text'))],
-         _("hg export [-a] [-o OUTFILE] REV...")),
+         "hg export [-a] [-o OUTFILE] REV..."),
     "forget":
         (forget,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
-         _("hg forget [OPTION]... FILE...")),
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
+         "hg forget [OPTION]... FILE..."),
     "grep":
         (grep,
          [('0', 'print0', None, _('end fields with NUL')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('include path in search')),
-          ('', 'all', None, _('print all revisions with matches')),
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('include names matching the given patterns')),
+          ('', 'all', None, _('print all revisions that match')),
           ('i', 'ignore-case', None, _('ignore case when matching')),
-          ('l', 'files-with-matches', None, _('print names of files and revs with matches')),
-          ('n', 'line-number', None, _('print line numbers')),
-          ('r', 'rev', [], _('search in revision rev')),
-          ('u', 'user', None, _('print user who made change'))],
-         _("hg grep [OPTION]... PATTERN [FILE]...")),
+          ('l', 'files-with-matches', None, _('print only filenames and revs that match')),
+          ('n', 'line-number', None, _('print matching line numbers')),
+          ('r', 'rev', [], _('search in given revision range')),
+          ('u', 'user', None, _('print user who committed change'))],
+         "hg grep [OPTION]... PATTERN [FILE]..."),
     "heads":
         (heads,
          [('b', 'branches', None, _('find branch info'))],
@@ -1880,10 +2247,11 table = {
     "identify|id": (identify, [], _('hg identify')),
     "import|patch":
         (import_,
-         [('p', 'strip', 1, _('path strip')),
-          ('f', 'force', None, _('skip check for outstanding changes')),
+         [('p', 'strip', 1, _('directory strip option for patch. This has the same\n') +
+                            _('meaning as the corresponding patch option')),
+          ('f', 'force', None, _('skip check for outstanding uncommitted changes')),
           ('b', 'base', "", _('base path'))],
-         _("hg import [-f] [-p NUM] [-b BASE] PATCH...")),
+         "hg import [-f] [-p NUM] [-b BASE] PATCH..."),
     "incoming|in": (incoming,
          [('M', 'no-merges', None, _("do not show merges")),
           ('p', 'patch', None, _('show patch'))],
@@ -1891,19 +2259,19 table = {
     "^init": (init, [], _('hg init [DEST]')),
     "locate":
         (locate,
-         [('r', 'rev', '', _('revision')),
-          ('0', 'print0', None, _('end filenames with NUL')),
-          ('f', 'fullpath', None, _('print complete paths')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+         [('r', 'rev', '', _('search the repository as it stood at rev')),
+          ('0', 'print0', None, _('end filenames with NUL, for use with xargs')),
+          ('f', 'fullpath', None, _('print complete paths from the filesystem root')),
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          _('hg locate [OPTION]... [PATTERN]...')),
     "^log|history":
         (log,
-         [('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search')),
+         [('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns')),
           ('b', 'branch', None, _('show branches')),
           ('k', 'keyword', [], _('search for a keyword')),
-          ('r', 'rev', [], _('revision')),
+          ('r', 'rev', [], _('show the specified revision or range')),
           ('M', 'no-merges', None, _("do not show merges")),
           ('m', 'only-merges', None, _("show only merges")),
           ('p', 'patch', None, _('show patch'))],
@@ -1917,15 +2285,15 table = {
     "paths": (paths, [], _('hg paths [NAME]')),
     "^pull":
         (pull,
-         [('u', 'update', None, _('update working directory')),
-          ('e', 'ssh', "", _('ssh command')),
-          ('', 'remotecmd', "", _('remote hg command'))],
+         [('u', 'update', None, _('update the working directory to tip after pull')),
+          ('e', 'ssh', "", _('specify ssh command to use')),
+          ('', 'remotecmd', "", _('specify hg command to run on the remote side'))],
          _('hg pull [-u] [-e FILE] [--remotecmd FILE] [SOURCE]')),
     "^push":
         (push,
          [('f', 'force', None, _('force push')),
-          ('e', 'ssh', "", _('ssh command')),
-          ('', 'remotecmd', "", _('remote hg command'))],
+          ('e', 'ssh', "", _('specify ssh command to use')),
+          ('', 'remotecmd', "", _('specify hg command to run on the remote side'))],
          _('hg push [-f] [-e FILE] [--remotecmd FILE] [DEST]')),
     "rawcommit":
         (rawcommit,
@@ -1939,32 +2307,32 table = {
          _('hg rawcommit [OPTION]... [FILE]...')),
     "recover": (recover, [], _("hg recover")),
     "^remove|rm": (remove,
-                   [('I', 'include', [], _('include path in search')),
-                    ('X', 'exclude', [], _('exclude path from search'))],
+                   [('I', 'include', [], _('include names matching the given patterns')),
+                    ('X', 'exclude', [], _('exclude names matching the given patterns'))],
                    _("hg remove [OPTION]... FILE...")),
     "rename|mv": (rename,
-                  [('I', 'include', [], _('include path in search')),
-                   ('X', 'exclude', [], _('exclude path from search')),
-                   ('A', 'after', None, _('record a copy after it has happened')),
-                   ('f', 'force', None, _('replace destination if it exists')),
+                  [('I', 'include', [], _('include names matching the given patterns')),
+                   ('X', 'exclude', [], _('exclude names matching the given patterns')),
+                   ('A', 'after', None, _('record a rename that has already occurred')),
+                   ('f', 'force', None, _('forcibly copy over an existing managed file')),
                    ('p', 'parents', None, _('append source path to dest'))],
                   _('hg rename [OPTION]... [SOURCE]... DEST')),
     "^revert":
         (revert,
-         [("n", "nonrecursive", None, _("don't recurse into subdirs")),
-          ("r", "rev", "", _("revision"))],
+         [("n", "nonrecursive", None, _("do not recurse into subdirectories")),
+          ("r", "rev", "", _("revision to revert to"))],
          _("hg revert [-n] [-r REV] [NAME]...")),
     "root": (root, [], _("hg root")),
     "^serve":
         (serve,
-         [('A', 'accesslog', '', _('access log file')),
-          ('E', 'errorlog', '', _('error log file')),
-          ('p', 'port', 0, _('listen port')),
-          ('a', 'address', '', _('interface address')),
-          ('n', 'name', "", _('repository name')),
+         [('A', 'accesslog', '', _('name of access log file to write to')),
+          ('E', 'errorlog', '', _('name of error log file to write to')),
+          ('p', 'port', 0, _('port to use (default: 8000)')),
+          ('a', 'address', '', _('address to use')),
+          ('n', 'name', "", _('name to show in web pages (default: working dir)')),
           ('', 'stdio', None, _('for remote clients')),
-          ('t', 'templates', "", _('template directory')),
-          ('', 'style', "", _('template style')),
+          ('t', 'templates', "", _('web templates to use')),
+          ('', 'style', "", _('template style to use')),
           ('6', 'ipv6', None, _('use IPv6 in addition to IPv4'))],
          _("hg serve [OPTION]...")),
     "^status":
@@ -1974,17 +2342,17 table = {
           ('r', 'removed', None, _('show only removed files')),
           ('u', 'unknown', None, _('show only unknown (not tracked) files')),
           ('n', 'no-status', None, _('hide status prefix')),
-          ('0', 'print0', None, _('end filenames with NUL')),
-          ('I', 'include', [], _('include path in search')),
-          ('X', 'exclude', [], _('exclude path from search'))],
+          ('0', 'print0', None, _('end filenames with NUL, for use with xargs')),
+          ('I', 'include', [], _('include names matching the given patterns')),
+          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
          _("hg status [OPTION]... [FILE]...")),
     "tag":
         (tag,
          [('l', 'local', None, _('make the tag local')),
-          ('m', 'message', "", _('commit message')),
+          ('m', 'message', "", _('message for tag commit log entry')),
           ('t', 'text', "", _('commit message (deprecated: use -m)')),
-          ('d', 'date', "", _('date code')),
-          ('u', 'user', "", _('user'))],
+          ('d', 'date', "", _('record datecode as commit date')),
+          ('u', 'user', "", _('record user as commiter'))],
          _('hg tag [OPTION]... NAME [REV]')),
     "tags": (tags, [], _('hg tags')),
     "tip": (tip, [], _('hg tip')),
@@ -1996,7 +2364,7 table = {
     "^update|up|checkout|co":
         (update,
          [('b', 'branch', "", _('checkout the head of a specific branch')),
-          ('m', 'merge', None, _('allow merging of conflicts')),
+          ('m', 'merge', None, _('allow merging of branches')),
           ('C', 'clean', None, _('overwrite locally modified files'))],
          _('hg update [-b TAG] [-m] [-C] [REV]')),
     "verify": (verify, [], _('hg verify')),
@@ -2004,18 +2372,18 table = {
 }
 
 globalopts = [
-    ('R', 'repository', "", _('repository root directory')),
-    ('', 'cwd', '', _('change working directory')),
-    ('y', 'noninteractive', None, _('run non-interactively')),
-    ('q', 'quiet', None, _('quiet mode')),
-    ('v', 'verbose', None, _('verbose mode')),
-    ('', 'debug', None, _('debug mode')),
-    ('', 'debugger', None, _('start debugger')),
-    ('', 'traceback', None, _('print traceback on exception')),
-    ('', 'time', None, _('time how long the command takes')),
-    ('', 'profile', None, _('profile')),
-    ('', 'version', None, _('output version information and exit')),
-    ('h', 'help', None, _('display help and exit')),
+    ('R', 'repository', "", _("repository root directory")),
+    ('', 'cwd', '', _("change working directory")),
+    ('y', 'noninteractive', None, _("do not prompt, assume 'yes' for any required answers")),
+    ('q', 'quiet', None, _("suppress output")),
+    ('v', 'verbose', None, _("enable additional output")),
+    ('', 'debug', None, _("enable debugging output")),
+    ('', 'debugger', None, _("start debugger")),
+    ('', 'traceback', None, _("print traceback on exception")),
+    ('', 'time', None, _("time how long the command takes")),
+    ('', 'profile', None, _("print command execution profile")),
+    ('', 'version', None, _("output version information and exit")),
+    ('h', 'help', None, _("display help and exit")),
 ]
 
 norepo = ("clone init version help debugancestor debugconfig debugdata"

tests/test-help.out

@@ -124,33 +124,66 hg add [OPTION]... [FILE]...
 
 add the specified files on the next commit
 
+    Schedule files to be version controlled and added to the repository.
+
+    The files will be added to the repository at the next commit.
+
+    If no names are given, add all files in the current directory and
+    its subdirectories.
+
 options:
 
- -I --include  include path in search
- -X --exclude  exclude path from search
+ -I --include  include names matching the given patterns
+ -X --exclude  exclude names matching the given patterns
 hg add: option --skjdfks not recognized
 hg add [OPTION]... [FILE]...
 
 add the specified files on the next commit
 
+    Schedule files to be version controlled and added to the repository.
+
+    The files will be added to the repository at the next commit.
+
+    If no names are given, add all files in the current directory and
+    its subdirectories.
+
 options:
 
- -I --include  include path in search
- -X --exclude  exclude path from search
+ -I --include  include names matching the given patterns
+ -X --exclude  exclude names matching the given patterns
 hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...
 
 diff working directory (or selected files)
 
+    Show differences between revisions for the specified files.
+
+    Differences between files are shown using the unified diff format.
+
+    When two revision arguments are given, then changes are shown
+    between those revisions. If only one revision is specified then
+    that revision is compared to the working directory, and, when no
+    revisions are specified, the working directory files are compared
+    to its parent.
+
+    Without the -a option, diff will avoid generating diffs of files
+    it detects as binary. With -a, diff will generate a diff anyway,
+    probably with undesirable results.
+
 options:
 
  -r --rev      revision
  -a --text     treat all files as text
- -I --include  include path in search
- -X --exclude  exclude path from search
+ -I --include  include names matching the given patterns
+ -X --exclude  exclude names matching the given patterns
 hg status [OPTION]... [FILE]...
 
 show changed files in the working directory
 
+    Show changed files in the working directory.  If no names are
+    given, all files are shown.  Otherwise, only files matching the
+    given names are shown.
+
+    The codes used to show the status of files are:
     M = modified
     A = added
     R = removed
@@ -163,9 +196,9 options:
  -r --removed    show only removed files
  -u --unknown    show only unknown (not tracked) files
  -n --no-status  hide status prefix
- -0 --print0     end filenames with NUL
- -I --include    include path in search
- -X --exclude    exclude path from search
+ -0 --print0     end filenames with NUL, for use with xargs
+ -I --include    include names matching the given patterns
+ -X --exclude    exclude names matching the given patterns
 hg status [OPTION]... [FILE]...
 
 show changed files in the working directory