I have a few (unsent) patches I've been working on that touch the help mechanism, so I have some thoughts below. On Sat, Jul 26, 2025 at 4:13 AM Jeff King <peff@xxxxxxxx> wrote: > > On Fri, Jul 25, 2025 at 04:52:40PM -0700, Junio C Hamano wrote: > > > When it redirects to our commands, it is less risky as we aim to > > make all our commands honor a single "-h" via t0450. > > > > $ git -c alias.c=checkout c -h > > 'c' is aliased to 'checkout' > > usage: git checkout [<options>] <branch> > > or: git checkout [<options>] [<branch>] -- <file>... > > > > -b <branch> create and checkout a new branch > > -B <branch> create/reset and checkout a branch > > ... > > --pathspec-from-file <file> > > read pathspec from file > > --pathspec-file-nul with --pathspec-from-file, pathspec elements are separated with NUL character > > > > But then, it may not be such a good idea to pay attention to "do we > > have extra '-h'?" when alias expands to our commands, e.g. > > Another interesting case: even for our own commands, the alias itself > may add extra arguments, which confuses things further. So: > > $ git -c alias.gi='grep --cached' gi -h > 'gi' is aliased to 'grep --cached' > fatal: no pattern given > > runs git-grep, but even though the user said only "-h" the alias added > another option which prevents the help-mode from activating. > > In this case it is not too harmful, but you can come up with > pathological cases where it actually runs a real command: > > git -c alias.grep-for-foo='grep -e foo' grep-for-foo -h > > which runs a real grep. > > I guess one way to deal with it would be if the user runs "foo -h", and > alias.foo is "bar --other arguments", then we run just "bar -h", > dropping the extra arguments provided by the alias. This is intriguing: it would mean that an alias is not purely a textual replacement? That's true for ! aliases today, but other than shelling out it's pretty close. > > (Another fun corner case: not all git-foo are our commands. But maybe it > is enough to say "if you make a third-party git-foo it should probably > respect bare -h as an option"). > > > $ git -c alias.c=checkout c -h main > > usage: git checkout [<options>] <branch> > > or: git checkout [<options>] [<branch>] -- <file>... > > > > -b <branch> create and checkout a new branch > > -B <branch> create/reset and checkout a branch > > ... > > --pathspec-from-file <file> > > read pathspec from file > > --pathspec-file-nul with --pathspec-from-file, pathspec elements are separated with NUL character > > > > We get the same short-help, without what alias expansion caused this > > mess, and without any indication that we lost 'main' on the command > > line. > > Yeah, that is the flip side of René's patch. Right now we overly guess > that "-h" means help. And after the patch, we'd sometimes under-guess > that it meant help, even for commands which treat it as such. I think > that may be the lesser of two evils, though; if you are asking for help > then "git c -h" is the most-strict way to do it. > > So IMHO the patch under discussion is a strict improvement, even though > it leaves many other questionable cases unsolved. I'd also be happy if > on top we did: > > 1. When alias.foo="bar --options", turn "git foo -h" into "git bar > -h", dropping "--options". > > 2. When alias.foo="!bar", report only the alias and do not run "bar" > at all. The collateral damage here would be: > > !git bar $(some_shell_magic_we_need) > > but IMHO that is not all that bad. If we report the alias content, > the user can probably figure out which "git help" to run next. And if the user actually wanted to run `bar -h`, say, because `-h` didn't mean help for that command? I can't come up with a compelling example, but this goes back to "textual substitution" vs. "trying to decide what the user actually wants." At any rate, a (3) to consider is "--help-all": the patches I've been working on are to make that flag work more often outside of Git repositories. I just need to clean things up a bit and get to tests. But if we do treat "git alias -h" specially, perhaps "--help-all" then also warrants treatment. > > -Peff > -- D. Ben Knoble
