Am 18.10.2017 um 01:22 schrieb Junio C Hamano:
> René Scharfe <l....@web.de> writes:
>
>> Stop advertising -h as the short equivalent of --heads, because it's
>> used for showing a short help text for almost all other git commands.
>> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only
>> been working when used together with other parameters anyway.
>>
>> Signed-off-by: Rene Scharfe <l....@web.de>
>> ---
>> That would be step on the way towards more consistent command line
>> switches, in the same vein as d69155119 (t0012: test "-h" with
>> builtins).
>
> Sorry, but I am not sure whom this and the other approach are trying
> to help.
>
> The rule we have currently seems to be that "git cmd -h" (no other
> arguments) consistently gives a short help, and if a subcommand
> supports an option "-h" specific to it that is not about giving a
> short help, the caller needs to be aware of it to invoke the option,
> by making sure that there is some other arguments on the command
> line if "-h" form of that subcommand specific option is used, by
> doing e.g. "git ls-remote -h origin" or "git ls-remote --head".
>
> I can see that this "alternative" approach makes it less convenent
> for folks who have followed that rule by hiding "-h" (with the
> intention of deprecating and possibly removing it in the future) and
> encouraging (and later foring) "--head" to be used instead.
>
> The other approach burdens new users by changing the rule to "some
> subcommands that have their own '-h' option cannot be asked for a
> brief usage with 'git cmd -h'". But the thing is, these new users
> who do not know which subcommands do have their own '-h' and which
> ones do not are the ones that benefit most from the consistent "'git
> cmd -h' with no other argument gets short help" rule.
They would help by aligning documentation and code, at a price. But
of course there is another way to do that -- I just didn't see it the
other day. We don't have to take anything away:
-- >8 --
Subject: [PATCH] ls-remote: document behavior of lone parameter -h
Reported-by: Thomas Rikl <tr...@online.de>
Analyzed-by: Martin Ågren <martin.ag...@gmail.com>
Analyzed-by: Junio C Hamano <gits...@pobox.com>
Signed-off-by: Rene Scharfe <l....@web.de>
---
Documentation/git-ls-remote.txt | 10 ++++++++++
builtin/ls-remote.c | 5 ++++-
2 files changed, 14 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index 5f2628c8f8..82622e7fbc 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -29,6 +29,9 @@ OPTIONS
These options are _not_ mutually exclusive; when given
both, references stored in refs/heads and refs/tags are
displayed.
++
+*NOTE*: -h without any other parameters shows a short help text instead
+of any refs.
--refs::
Do not show peeled tags or pseudorefs like HEAD in the output.
@@ -89,6 +92,13 @@ EXAMPLES
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
+ $ git ls-remote -hh
+ From https://git.kernel.org/pub/scm/git/git.git/
+ 4c2224e83951a685185bb8c1f83b28e22fee0e27 refs/heads/maint
+ 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
+ 76aedb4517c834be2dc89efb5f9d15908e324422 refs/heads/next
+ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu
+ 5d38b589ccc7a8355c62f1577865df5b8216c00d refs/heads/todo
GIT
---
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index c4be98ab9e..0438dfec05 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -56,7 +56,10 @@ int cmd_ls_remote(int argc, const char **argv, const char
*prefix)
N_("path of git-upload-pack on the remote host"),
PARSE_OPT_HIDDEN },
OPT_BIT('t', "tags", &flags, N_("limit to tags"), REF_TAGS),
- OPT_BIT('h', "heads", &flags, N_("limit to heads"), REF_HEADS),
+ OPT_BIT(0, "heads", &flags, N_("limit to heads"), REF_HEADS),
+ OPT_BIT('h', NULL, &flags,
+ N_("if only parameter: show this help text, otherwise
limit to heads"),
+ REF_HEADS),
OPT_BIT(0, "refs", &flags, N_("do not show peeled tags"),
REF_NORMAL),
OPT_BOOL(0, "get-url", &get_url,
N_("take url.<base>.insteadOf into account")),
--
2.14.2
