changeset 8779:708938509732

Improve English for help text of many core hg commands. co-author: Greg Ward <greg-hg@gerg.ca>
author timeless <timeless@gmail.com>
date Tue, 09 Jun 2009 21:51:34 -0400
parents c5f36402daad
children 73728f5f69ab
files mercurial/commands.py tests/test-backout.out tests/test-globalopts.out tests/test-help.out tests/test-qrecord.out tests/test-strict.out
diffstat 6 files changed, 124 insertions(+), 118 deletions(-) [+]
line wrap: on
line diff
--- a/mercurial/commands.py	Wed Jun 10 15:10:21 2009 +0200
+++ b/mercurial/commands.py	Tue Jun 09 21:51:34 2009 -0400
@@ -72,17 +72,18 @@
     return cmdutil.addremove(repo, pats, opts, similarity=sim/100.)
 
 def annotate(ui, repo, *pats, **opts):
-    """show changeset information per file line
+    """show changeset information by line for each file
 
     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.
+    This command is useful for discovering when a change was made and
+    by whom.
 
     Without the -a/--text option, annotate will avoid processing files
-    it detects as binary. With -a, annotate will generate an
-    annotation anyway, probably with undesirable results.
+    it detects as binary. With -a, annotate will annotate the file
+    anyway, although the results will probably be neither useful
+    nor desirable.
     """
     datefunc = ui.quiet and util.shortdate or util.datestr
     getdate = util.cachefunc(lambda x: datefunc(x[0].date()))
@@ -134,7 +135,7 @@
                 ui.write("%s: %s" % (" ".join(p), l[1]))
 
 def archive(ui, repo, dest, **opts):
-    '''create unversioned archive of a repository revision
+    '''create an unversioned archive of a repository revision
 
     By default, the revision used is the parent of the working
     directory; use -r/--rev to specify a different revision.
@@ -183,9 +184,9 @@
     Commit the backed out changes as a new changeset. The new
     changeset is a child of the backed out changeset.
 
-    If you back out a changeset other than the tip, a new head is
+    If you backout a changeset other than the tip, a new head is
     created. This head will be the new tip and you should merge this
-    backout changeset with another head (current one by default).
+    backout changeset with another head.
 
     The --merge option remembers the parent of the working directory
     before starting the backout, then merges the new head with that
@@ -213,14 +214,14 @@
     op1, op2 = repo.dirstate.parents()
     a = repo.changelog.ancestor(op1, node)
     if a != node:
-        raise util.Abort(_('cannot back out change on a different branch'))
+        raise util.Abort(_('cannot backout change on a different branch'))
 
     p1, p2 = repo.changelog.parents(node)
     if p1 == nullid:
-        raise util.Abort(_('cannot back out a change with no parents'))
+        raise util.Abort(_('cannot backout a change with no parents'))
     if p2 != nullid:
         if not opts.get('parent'):
-            raise util.Abort(_('cannot back out a merge changeset without '
+            raise util.Abort(_('cannot backout a merge changeset without '
                                '--parent'))
         p = repo.lookup(opts['parent'])
         if p not in (p1, p2):
@@ -272,18 +273,18 @@
     bad, then mark the latest changeset which is free from the problem
     as good. Bisect will update your working directory to a revision
     for testing (unless the -U/--noupdate option is specified). Once
-    you have performed tests, mark the working directory as bad or
-    good and bisect will either update to another candidate changeset
+    you have performed tests, mark the working directory as good or
+    bad, and bisect will either update to another candidate changeset
     or announce that it has found the bad revision.
 
     As a shortcut, you can also use the revision argument to mark a
     revision as good or bad without checking it out first.
 
-    If you supply a command it will be used for automatic bisection.
-    Its exit status will be used as flag to mark revision as bad or
-    good. In case exit status is 0 the revision is marked as good, 125
-    - skipped, 127 (command not found) - bisection will be aborted;
-    any other status bigger than 0 will mark revision as bad.
+    If you supply a command, it will be used for automatic bisection.
+    Its exit status will be used to mark revisions as good or bad:
+    status 0 means good, 125 means to skip the revision, 127
+    (command not found) will abort the bisection, and any other
+    non-zero exit status means the revision is bad.
     """
     def print_result(nodes, good):
         displayer = cmdutil.show_changeset(ui, repo, {})
@@ -404,12 +405,13 @@
     """set or show the current branch name
 
     With no argument, show the current branch name. With one argument,
-    set the working directory branch name (the branch does not exist
-    in the repository until the next commit). It is recommended to use
-    the 'default' branch as your primary development branch.
+    set the working directory branch name (the branch will not exist
+    in the repository until the next commit). Standard practice
+    recommends that primary development take place on the 'default'
+    branch.
 
     Unless -f/--force is specified, branch will not let you set a
-    branch name that shadows an existing branch.
+    branch name that already exists, even if it's inactive.
 
     Use -C/--clean to reset the working directory branch to that of
     the parent of the working directory, negating a previous branch
@@ -590,8 +592,7 @@
 
     It is possible to specify an ssh:// URL as the destination, but no
     .hg/hgrc and working directory will be created on the remote side.
-    Look at the help text for URLs for important details about ssh://
-    URLs.
+    Please see 'hg help urls' for important details about ssh:// URLs.
 
     For efficiency, hardlinks are used for cloning whenever the source
     and destination are on the same filesystem (note this applies only
@@ -624,7 +625,7 @@
 
     Commit changes to the given files into the repository. Unlike a
     centralized RCS, this operation is a local operation. See hg push
-    for means to actively distribute your changes.
+    for a way to actively distribute your changes.
 
     If a list of files is omitted, all changes reported by "hg status"
     will be committed.
@@ -675,7 +676,7 @@
     the source must be a single file.
 
     By default, this command copies the contents of files as they
-    stand in the working directory. If invoked with -A/--after, the
+    exist in the working directory. If invoked with -A/--after, the
     operation is recorded, but no copying is performed.
 
     This command takes effect with the next commit. To undo a copy
@@ -788,8 +789,8 @@
     With multiple arguments, print names and values of all config
     items with matching section names.
 
-    With the --debug flag, the source (filename and line number) is
-    printed for each config item.
+    With --debug, the source (filename and line number) is printed
+    for each config item.
     """
 
     untrusted = bool(opts.get('untrusted'))
@@ -886,7 +887,7 @@
             short(node), short(pp[0]), short(pp[1])))
 
 def debugindexdot(ui, file_):
-    """dump an index DAG as a .dot file"""
+    """dump an index DAG as a graphviz dot file"""
     r = revlog.revlog(util.opener(os.getcwd(), audit=False), file_)
     ui.write("digraph G {\n")
     for i in r:
@@ -1107,7 +1108,7 @@
     diff anyway, probably with undesirable results.
 
     Use the -g/--git option to generate diffs in the git extended diff
-    format. Read the diffs help topic for more information.
+    format. See 'hg help diffs' for more information.
 
     With the --switch-parent option, the diff will be against the
     second parent. It can be useful to review a merge.
@@ -1301,7 +1302,7 @@
 
     With no arguments, show all repository head changesets.
 
-    If branch or revisions names are given this will show the heads of
+    If branch names or revisions are given this will show the heads of
     the specified branches or the branches those revisions are tagged
     with.
 
@@ -1311,7 +1312,7 @@
 
     Branch heads are changesets that have a given branch tag, but have
     no child changesets with that tag. They are usually where
-    development on the given branch takes place.
+    development on a given branch takes place.
     """
     if opts.get('rev'):
         start = repo.lookup(opts['rev'])
@@ -1353,7 +1354,7 @@
 def help_(ui, name=None, with_version=False):
     """show help for a given topic or a help overview
 
-    With no arguments, print a list of commands and short help.
+    With no arguments, print a list of commands with short help messages.
 
     Given a topic, extension, or command name, print help for that
     topic."""
@@ -1576,7 +1577,8 @@
     With no revision, print a summary of the current state of the
     repository.
 
-    With a path, do a lookup in another repository.
+    Specifying a path to a repository root or Mercurial bundle will
+    cause lookup to operate on that repository/bundle.
 
     This summary identifies the repository state using one or two
     parent hash identifiers, followed by a "+" if there are
@@ -1652,8 +1654,8 @@
     will abort unless given the -f/--force flag.
 
     You can import a patch straight from a mail message. Even patches
-    as attachments work (body part must be type text/plain or
-    text/x-patch to be used). From and Subject headers of email
+    as attachments work (to use the body part, it must have type
+    text/plain or text/x-patch). From and Subject headers of email
     message are used as default committer and commit message. All
     text/plain body parts before first diff are added to commit
     message.
@@ -1672,8 +1674,8 @@
     With -s/--similarity, hg will attempt to discover renames and
     copies in the patch in the same way as 'addremove'.
 
-    To read a patch from standard input, use patch name "-". See 'hg
-    help dates' for a list of formats valid for -d/--date.
+    To read a patch from standard input, use "-" as the patch name.
+    See 'hg help dates' for a list of formats valid for -d/--date.
     """
     patches = (patch1,) + patches
 
@@ -1774,8 +1776,8 @@
     """show new changesets found in source
 
     Show new changesets found in the specified path/URL or the default
-    pull location. These are the changesets that would be pulled if a
-    pull was requested.
+    pull location. These are the changesets that would have been pulled
+    if a pull at the time you issued this command.
 
     For remote repository, using --bundle avoids downloading the
     changesets twice if the incoming is followed by a pull.
@@ -1843,7 +1845,7 @@
     """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.
+    directory does not exist, it will be created.
 
     If no directory is given, the current directory is used.
 
@@ -1855,20 +1857,20 @@
 def locate(ui, repo, *pats, **opts):
     """locate files matching specific patterns
 
-    Print all files under Mercurial control whose names match the
-    given patterns.
-
-    This command searches the entire repository by default. To search
-    just the current directory and its subdirectories, use
-    "--include .".
-
-    If no patterns are given to match, this command prints all file
-    names.
+    Print files under Mercurial control in the working directory whose
+    names match the given patterns.
+
+    By default, this command searches all directories in the working
+    directory. To search just the current directory and its
+    subdirectories, use "--include .".
+
+    If no patterns are given to match, this command prints the names
+    of all files under Mercurial control in the working directory.
 
     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.
+    contain whitespace as multiple filenames.
     """
     end = opts.get('print0') and '\0' or '\n'
     rev = opts.get('rev') or None
@@ -1905,16 +1907,15 @@
 
     See 'hg help dates' for a list of formats valid for -d/--date.
 
-    By default this command outputs: changeset id and hash, tags,
-    non-trivial parents, user, date and time, and a summary for each
-    commit. When the -v/--verbose switch is used, the list of changed
-    files and full commit message is shown.
+    By default this command prints revision number and changeset id,
+    tags, non-trivial parents, user, date and time, and a summary for
+    each commit. When the -v/--verbose switch is used, the list of
+    changed files and full commit message are shown.
 
     NOTE: log -p/--patch may generate unexpected diff output for merge
     changesets, as it will only compare the merge changeset against
-    its first parent. Also, the files: list will only reflect files
-    that are different from BOTH parents.
-
+    its first parent. Also, only files different from BOTH parents
+    will appear in files:.
     """
 
     get = util.cachefunc(lambda r: repo[r].changeset())
@@ -2019,10 +2020,10 @@
 
     Print a list of version controlled files for the given revision.
     If no revision is given, the first parent of the working directory
-    is used, or the null revision if none is checked out.
-
-    With -v flag, print file permissions, symlink and executable bits.
-    With --debug flag, print file revision hashes.
+    is used, or the null revision if no revision is checked out.
+
+    With -v, print file permissions, symlink and executable bits.
+    With --debug, print file revision hashes.
     """
 
     if rev and node:
@@ -2043,18 +2044,18 @@
 def merge(ui, repo, node=None, **opts):
     """merge working directory with another revision
 
-    The contents of the current working directory is updated with all
-    changes made in the requested revision since the last common
-    predecessor revision.
+    The current working directory is updated with all changes made in
+    the requested revision since the last common predecessor revision.
 
     Files that changed between either parent are marked as changed for
     the next commit and a commit must be performed before any further
-    updates are allowed. The next commit has two parents.
+    updates to the repository are allowed. The next commit will have
+    two parents.
 
     If no revision is specified, the working directory's parent is a
     head revision, and the current branch contains exactly one other
     head, the other head is merged with by default. Otherwise, an
-    explicit revision to merge with must be provided.
+    explicit revision with which to merge with must be provided.
     """
 
     if opts.get('rev') and node:
@@ -2138,9 +2139,9 @@
 
     Print the working directory's parent revisions. If a revision is
     given via -r/--rev, the parent of that revision will be printed.
-    If a file argument is given, revision in which the file was last
-    changed (before the working directory revision or the argument to
-    --rev if given) is printed.
+    If a file argument is given, the revision in which the file was
+    last changed (before the working directory revision or the
+    argument to --rev if given) is printed.
     """
     rev = opts.get('rev')
     if rev:
@@ -2177,7 +2178,7 @@
     """show aliases for remote repositories
 
     Show definition of symbolic path name NAME. If no name is given,
-    show definition of available names.
+    show definition of all 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.
@@ -2211,14 +2212,17 @@
 def pull(ui, repo, source="default", **opts):
     """pull changes from the specified source
 
-    Pull changes from a remote repository to the local one.
+    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.
-
-    Use hg incoming if you want to see what will be added by the next
-    pull without actually adding the changes to the repository.
+    or URL and adds them to a local repository (the current one unless
+    -R is specified). By default, this does not update the copy of the
+    project in the working directory.
+
+    Use hg incoming if you want to see what would have been added by a
+    pull at the time you issued this command. If you then decide to
+    added those changes to the repository, you should use pull -r X
+    where X is the last changeset listed by hg incoming.
 
     If SOURCE is omitted, the 'default' path will be used.
     See 'hg help urls' for more information.
@@ -2249,12 +2253,12 @@
 
     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 pull and merge before pushing.
+    user forgot to pull and merge before pushing.
 
     If -r/--rev is used, the named revision and all its ancestors will
     be pushed to the remote repository.
 
-    Look at the help text for URLs for important details about ssh://
+    Please see 'hg help urls' for important details about ssh://
     URLs. If DESTINATION is omitted, a default path will be used.
     See 'hg help urls' for more information.
     """
@@ -2289,13 +2293,13 @@
     entire project history. -A/--after can be used to remove only
     files that have already been deleted, -f/--force can be used to
     force deletion, and -Af can be used to remove files from the next
-    revision without deleting them.
+    revision without deleting them from the working directory.
 
     The following table details the behavior of remove for different
     file states (columns) and option combinations (rows). The file
-    states are Added, Clean, Modified and Missing (as reported by hg
-    status). The actions are Warn, Remove (from branch) and Delete
-    (from disk).
+    states are Added [A], Clean [C], Modified [M] and Missing [!]
+    (as reported by hg status). The actions are Warn, Remove (from
+    branch) and Delete (from disk).
 
            A  C  M  !
     none   W  RD W  R
@@ -2372,9 +2376,9 @@
     will be overwritten if the merge is retried with resolve. The
     -m/--mark switch should be used to mark the file as resolved.
 
-    This command will also allow listing resolved files and manually
-    marking and unmarking files as resolved. All files must be marked
-    as resolved before the new commits are permitted.
+    This command also allows listing resolved files and manually
+    indicating whether or not files are resolved. All files must be
+    marked as resolved before a commit is permitted.
 
     The codes used to show the status of files are:
     U = unresolved
@@ -2737,10 +2741,10 @@
 
     Show status of files in the repository. If names are given, only
     files that match are shown. Files that are clean or ignored or
-    source of a copy/move operation, are not listed unless -c/--clean,
-    -i/--ignored, -C/--copies or -A/--all is given. Unless options
-    described with "show only ..." are given, the options -mardu are
-    used.
+    the source of a copy/move operation, are not listed unless
+    -c/--clean, -i/--ignored, -C/--copies or -A/--all are given.
+    Unless options described with "show only ..." are given, the
+    options -mardu are used.
 
     Option -q/--quiet hides untracked (unknown and ignored) files
     unless explicitly requested with -u/--unknown or -i/--ignored.
@@ -2751,7 +2755,8 @@
     to one merge parent.
 
     If one revision is given, it is used as the base revision.
-    If two revisions are given, the difference between them is shown.
+    If two revisions are given, the differences between them are
+    shown.
 
     The codes used to show the status of files are:
     M = modified
@@ -2761,7 +2766,7 @@
     ! = missing (deleted by non-hg command, but still tracked)
     ? = not tracked
     I = ignored
-      = the previous added file was copied from here
+      = origin of the previous file listed as A (added)
     """
 
     node1, node2 = cmdutil.revpair(repo, opts.get('rev'))
@@ -2902,9 +2907,9 @@
 def tip(ui, repo, **opts):
     """show the tip revision
 
-    The tip revision (usually just called the tip) is the most
-    recently added changeset in the repository, the most recently
-    changed head.
+    The tip revision (usually just called the tip) is the changeset
+    most recently added to the repository (and therefore the most
+    recently changed head).
 
     If you have just made a commit, that commit will be the tip. If
     you have just pulled changes from another repository, the tip of
--- a/tests/test-backout.out	Wed Jun 10 15:10:21 2009 +0200
+++ b/tests/test-backout.out	Tue Jun 09 21:51:34 2009 -0400
@@ -19,10 +19,10 @@
 adding a
 adding b
 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
-abort: cannot back out change on a different branch
+abort: cannot backout change on a different branch
 adding c
 created new head
-abort: cannot back out change on a different branch
+abort: cannot backout change on a different branch
 # backout with merge
 adding a
 reverting a
@@ -54,7 +54,7 @@
 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 (branch merge, don't forget to commit)
 # backout of merge should fail
-abort: cannot back out a merge changeset without --parent
+abort: cannot backout a merge changeset without --parent
 # backout of merge with bad parent should fail
 abort: cb9a9f314b8b is not a parent of b2f3bb92043e
 # backout of non-merge with parent should fail
--- a/tests/test-globalopts.out	Wed Jun 10 15:10:21 2009 +0200
+++ b/tests/test-globalopts.out	Tue Jun 09 21:51:34 2009 -0400
@@ -151,8 +151,8 @@
 
  add          add the specified files on the next commit
  addremove    add all new files, delete all missing files
- annotate     show changeset information per file line
- archive      create unversioned archive of a repository revision
+ annotate     show changeset information by line for each file
+ archive      create an unversioned archive of a repository revision
  backout      reverse effect of earlier changeset
  bisect       subdivision search of changesets
  branch       set or show the current branch name
@@ -216,8 +216,8 @@
 
  add          add the specified files on the next commit
  addremove    add all new files, delete all missing files
- annotate     show changeset information per file line
- archive      create unversioned archive of a repository revision
+ annotate     show changeset information by line for each file
+ archive      create an unversioned archive of a repository revision
  backout      reverse effect of earlier changeset
  bisect       subdivision search of changesets
  branch       set or show the current branch name
--- a/tests/test-help.out	Wed Jun 10 15:10:21 2009 +0200
+++ b/tests/test-help.out	Tue Jun 09 21:51:34 2009 -0400
@@ -3,7 +3,7 @@
 basic commands:
 
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)
@@ -21,7 +21,7 @@
 
 use "hg help" for the full list of commands or "hg -v" for details
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)
@@ -42,8 +42,8 @@
 
  add          add the specified files on the next commit
  addremove    add all new files, delete all missing files
- annotate     show changeset information per file line
- archive      create unversioned archive of a repository revision
+ annotate     show changeset information by line for each file
+ archive      create an unversioned archive of a repository revision
  backout      reverse effect of earlier changeset
  bisect       subdivision search of changesets
  branch       set or show the current branch name
@@ -103,8 +103,8 @@
 use "hg -v help" to show aliases and global options
  add          add the specified files on the next commit
  addremove    add all new files, delete all missing files
- annotate     show changeset information per file line
- archive      create unversioned archive of a repository revision
+ annotate     show changeset information by line for each file
+ archive      create an unversioned archive of a repository revision
  backout      reverse effect of earlier changeset
  bisect       subdivision search of changesets
  branch       set or show the current branch name
@@ -248,10 +248,10 @@
 
     Show status of files in the repository. If names are given, only
     files that match are shown. Files that are clean or ignored or
-    source of a copy/move operation, are not listed unless -c/--clean,
-    -i/--ignored, -C/--copies or -A/--all is given. Unless options
-    described with "show only ..." are given, the options -mardu are
-    used.
+    the source of a copy/move operation, are not listed unless
+    -c/--clean, -i/--ignored, -C/--copies or -A/--all are given.
+    Unless options described with "show only ..." are given, the
+    options -mardu are used.
 
     Option -q/--quiet hides untracked (unknown and ignored) files
     unless explicitly requested with -u/--unknown or -i/--ignored.
@@ -262,7 +262,8 @@
     to one merge parent.
 
     If one revision is given, it is used as the base revision.
-    If two revisions are given, the difference between them is shown.
+    If two revisions are given, the differences between them are
+    shown.
 
     The codes used to show the status of files are:
     M = modified
@@ -272,7 +273,7 @@
     ! = missing (deleted by non-hg command, but still tracked)
     ? = not tracked
     I = ignored
-      = the previous added file was copied from here
+      = origin of the previous file listed as A (added)
 
 options:
 
@@ -301,7 +302,7 @@
 basic commands:
 
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)
@@ -324,7 +325,7 @@
 basic commands:
 
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)
--- a/tests/test-qrecord.out	Wed Jun 10 15:10:21 2009 +0200
+++ b/tests/test-qrecord.out	Tue Jun 09 21:51:34 2009 -0400
@@ -5,7 +5,7 @@
 basic commands:
 
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)
--- a/tests/test-strict.out	Wed Jun 10 15:10:21 2009 +0200
+++ b/tests/test-strict.out	Tue Jun 09 21:51:34 2009 -0400
@@ -6,7 +6,7 @@
 basic commands:
 
  add        add the specified files on the next commit
- annotate   show changeset information per file line
+ annotate   show changeset information by line for each file
  clone      make a copy of an existing repository
  commit     commit the specified files or all outstanding changes
  diff       diff repository (or selected files)