git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads

From
René Scharfe <l.s.r@web.de>
Date
Oct 19, 2017, 18:26 UTC
Message-ID
<26112a15-f02c-a910-c8bb-794ca84dc1e5@web.de>
In-Reply-To
<xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com>
Am 18.10.2017 um 01:22 schrieb Junio C Hamano:
Show 35 quoted lines
> René Scharfe <l.s.r@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.s.r@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 <trikl@online.de>
Analyzed-by: Martin Ågren <martin.agren@gmail.com>
Analyzed-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Rene Scharfe <l.s.r@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
Previous: Junio C HamanoNext: Jeff King
Message 10 of 23 in “Bug: git ls-remote -h / --head results differ in output”
  1. Thomas RiklOct 15, 2017
  2. Martin ÅgrenOct 15, 2017
  3. René ScharfeOct 15, 2017
  4. 1/2 git: add NO_INTERNAL_HELP flag for builtinsRené Scharfe, Oct 17, 2017
  5. Jonathan NiederOct 17, 2017
  6. ls-remote: deprecate -h as short for --headsRené Scharfe, Oct 17, 2017
  7. Martin ÅgrenOct 17, 2017
  8. Jonathan NiederOct 17, 2017
  9. Junio C HamanoOct 17, 2017
  10. René ScharfeOct 19, 2017
  11. Jeff KingOct 19, 2017
  12. Junio C HamanoOct 20, 2017
  13. Jeff KingOct 20, 2017
  14. Junio C HamanoOct 20, 2017
  15. Jeff KingOct 21, 2017
  16. René ScharfeOct 21, 2017
  17. Junio C HamanoOct 21, 2017
  18. René ScharfeOct 23, 2017
  19. Junio C HamanoOct 24, 2017
  20. René ScharfeOct 24, 2017
  21. 2/2 ls-remote: use PARSE_OPT_NO_INTERNAL_HELPRené Scharfe, Oct 17, 2017
  22. Jonathan NiederOct 17, 2017
  23. Martin ÅgrenOct 17, 2017

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.