This patch changes the function which generates help text about commands and
options to use RST formatting. Tables describing options have been formatted
using RST table markup for some time already, so their appearance does not
change. Command lists, however, change appearance.
To format non-verbose command lists, RST field list markup was chosen, because
it resembles the old format:
<http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists>
In the old (hand-coded) format of non-verbose command lists, the left column is
12 characters wide. Our minirst implementation formats field lists with a left
column 14 characters wide, so this patch changes the appearance of help output
correspondingly:
<http://markmail.org/message/krl4cxopsnii7s6z?q=mercurial+reinert+from:%22Olav+Reinert%22&page=2>
The minirst markup most closely resembling the old verbose command lists is
definition lists. But using it would cause a blank line to be inserted between
each command definition, making the output excessively long, and no more
useful than before. To avoid this, I chose to use field lists also for verbose
command help, resulting in output like this example:
add add the specified files on the next commit
annotate, blame
show changeset information by line for each file
clone make a copy of an existing repository
commit, ci commit the specified files or all outstanding changes
diff diff repository (or selected files)
export dump the header and diffs for one or more changesets
forget forget the specified files on the next commit
init create a new repository in the given directory
log, history show revision history of entire repository or files
merge merge working directory with another revision
phase set or show the current phase name
pull pull changes from the specified source
push push changes to the specified destination
qdiff diff of the current patch and subsequent modifications
qinit init a new queue repository (DEPRECATED)
qnew create a new patch
qpop pop the current patch off the stack
qpush push the next patch onto the stack
qrefresh update the current patch
remove, rm remove the specified files on the next commit
serve start stand-alone webserver
status, st show changed files in the working directory
summary, sum summarize working directory state
update, up, checkout, co
update working directory (or switch revisions)
This change is a move towards generating all help text as a list of strings
marked up with RST.
Commands working without a repository, like "init", are listed in
commands.norepo. Commands optionally using a repository, like "showconfig", are
listed in commands.optionalrepo. Command aliases were inheriting the former but
not the latter.
The output of "hg help" is changed to ensure that the column containing
descriptions of commands, extensions, and other topics is correctly alignmened.
An alias for 'log' was stored in the same command table as
'^log|history'. If the hash function happens to give the latter first,
the alias is effectively ignored when matching 'log'.
Previously, if you set an alias for "ci", it'd also shadow "commit"
even though you didn't specify that. This occurred for all commands
with explicit short variations.
Example
$ hg clone --jump foo bar
hg clone: option --jump not recognized
hg clone [OPTION]... SOURCE [DEST]
make a copy of an existing repository
options:
-U --noupdate the clone will include an empty working copy (only a
repository)
-u --updaterev REV revision, tag or branch to check out
-r --rev REV [+] include the specified changeset
-b --branch BRANCH [+] clone only the specified branch
--pull use pull protocol to copy metadata
--uncompressed use uncompressed transfer (fast over LAN)
-e --ssh CMD specify ssh command to use
--remotecmd CMD specify hg command to run on the remote side
--insecure do not verify server certificate (ignoring
web.cacerts config)
[+] marked option can be specified multiple times
use "hg help clone" to show the full help text
Motivation for this change
If the user already has specified the command, he probably already knows
the command to some extent. Apparently, he has a problem with the options,
so we show him just the synopsis with the short help and the details about
the options, with a hint on the last line how to get the full help text.
Why is Mercurial better with this change?
Experts who just forgot about the details of an option don't get that
much text thrown at them, while the newbies still get a hint on the last
line how to get the full help text.
This patch modifies the check for shell aliases to prevent crashing when an invalid
global option is given.
When an invalid global option is given the check will simply return and let the
normal error handling for this case happen.
The testsuite lacks a testcase for the bug introduced in 2933824cb30c.
This patch amends 91db5130b446 (which fixed 2933824cb30c) by adding a
testcase for that bug.
With 2933824cb30c, test-alias.t (as modified by this patch) fails
with "hg tglog: invalid arguments".
This patch refactors the dispatch code to change how arguments to shell aliases
are handled.
A separate "pass" to determine whether a command is a shell alias has been
added. The rough steps dispatch now performs when a command is given are these:
* Parse all arguments up to the command name.
* If any arguments such as --repository or --cwd are given (which could change
the config file used, and therefore the definition of aliases), they are
taken into account.
* We determine whether the command is a shell alias.
* If so, execute the alias. The --repo and --cwd arguments are still in effect.
Any arguments *after* the command name are passed unchanged through to the
shell command (and interpolated as normal.
* If the command is *not* a shell alias, the dispatching is effectively "reset"
and reparsed as normal in its entirety.
The net effect of this patch is to make shell alias commands behave as you
would expect.
Any arguments you give to a shell alias *after* the alias name are passed
through unchanged. This lets you do something like the following:
[alias]
filereleased = !$HG log -r 'descendants(adds("$1")) and tagged()' -l1 $2 $3 $4 $5
$ hg filereleased hgext/bookmarks.py --style compact
Previously the `--style compact` part would fail because Mercurial would
interpret those arguments as arguments to the alias command itself (which
doesn't take any arguments).
Also: running something like `hg -R ~/src/hg-crew filereleased
hgext/bookmarks.py` when `filereleased` is only defined in that repo's config
will now work.
These global arguments can *only* be given to a shell alias *before* the alias
name. For example, this will *not* work in the above situation:
$ hg filereleased -R ~/src/hg-crew hgext/bookmarks.py
The reason for this is that you may want to pass arguments like --repository to
the alias (or, more likely, their short versions like -R):
[alias]
own = !chown $@ `$HG root`
$ hg own steve
$ hg own -R steve
This patch changes the functionality of shell aliases to add more powerful
options for working with shell alias arguments.
First: the alias name + arguments to a shell alias are set as an HG_ARGS
environment variable, delimited by spaces. This matches the behavior of hooks.
Second: any occurrences of "$@" (without quotes) are replaced with the
arguments, separated by spaces. This happens *before* the alias gets to the shell.
Third: any positive numeric variables ("$1", "$2", etc) are replaced with the
appropriate argument, indexed from 1. "$0" is replaced with the name of the
alias. Any "extra" numeric variables are replaced with an empty string. This
happens *before* the alias gets to the shell.
These changes allow for more flexible shell aliases:
[alias]
echo = !echo $@
count = !hg log -r "$@" --template='.' | wc -c | sed -e 's/ //g'
qqueuemv = !mv "`hg root`/.hg/patches-$1" "`hg root`/.hg/patches-$2"
In action:
$ hg echo foo
foo
$ hg count 'branch(default)'
901
$ hg count 'branch(stable) and keyword(fixes)'
102
$ hg qqueuemv myfeature somefeature
