Am 18.10.2017 um 01:22 schrieb Junio C Hamano: > René Scharfe <l.s.r@xxxxxx> 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.s.r@xxxxxx> >> --- >> 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 <trikl@xxxxxxxxx> Analyzed-by: Martin Ågren <martin.agren@xxxxxxxxx> Analyzed-by: Junio C Hamano <gitster@xxxxxxxxx> Signed-off-by: Rene Scharfe <l.s.r@xxxxxx> --- 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
