threads / discuss / 50886

git glossary --help ?

Subject: git glossary --help ?

## tl;dr

8 messages between Apr 6, 2019 and Apr 8, 2019.

replies: 7people: 5as markdown or json

Philip Oakley· Apr 6, 2019, 17:31 UTC · lore

Following the discussions about the tag peeling issue, I thought to have a look at what the git glossary says.

I had it in my head that when the git guides were linked to the help system, that the --help option provided a short circuit direct to help item. However this did not happen.

I found that the capability had been lost, which given that a lot of the underpinning knowledge is in the guides this would appear to be a loss.

I don't have an older version to test, but I thought I remember the capability from about the time of my 65f98358c0 ("builtin/help.c: add --guide option", 2013-04-02).

Have I misremembered the --help capability?

cc'ing Duy in case he remembers something from the recent update

As a side note, the glossary does mention a few times the tag of tag capability but doesn't mention the peel/no-peel distinctions.

-- 
Philip

Andreas Schwab· Apr 6, 2019, 18:09 UTC · re: Philip Oakley · lore

Re: git glossary --help ?

On Apr 06 2019, Philip Oakley <philipoakley@iee.org> wrote:

Show 6 quoted lines

> Following the discussions about the tag peeling issue, I thought to have a
> look at what the git glossary says.
>
> I had it in my head that when the git guides were linked to the help
> system, that the --help option provided a short circuit direct to help
> item. However this did not happen.

$ git help glossary

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Philip Oakley· Apr 6, 2019, 20:27 UTC · re: Andreas Schwab · lore

Re: git glossary --help ?

Hi Andreas,

On 06/04/2019 19:09, Andreas Schwab wrote:

Show 12 quoted lines

> On Apr 06 2019, Philip Oakley <philipoakley@iee.org> wrote:
>
>> Following the discussions about the tag peeling issue, I thought to have a
>> look at what the git glossary says.
>>
>> I had it in my head that when the git guides were linked to the help
>> system, that the --help option provided a short circuit direct to help
>> item. However this did not happen.
> $ git help glossary
>
> Andreas.
>

Thanks. I was aware of that form, but as I remember it, as part of the 'git' command processing, there was an immediate shortcut if --help was an option, that would essentially re-write the cli as 'git help command', such that 'git foo --help' would become 'git help foo' and the help system would then provide the right long form help, including the guides and <concepts> docs (excepting the user-manual, which is unfortunate, but ..)

My question was whether the older systems did that re-write as described, should someone have one immediately to hand. Philip

Duy Nguyen· Apr 7, 2019, 03:20 UTC · re: Philip Oakley · lore

Re: git glossary --help ?

On Sun, Apr 7, 2019 at 12:31 AM Philip Oakley <philipoakley@iee.org> wrote:

Show 18 quoted lines

>
> Following the discussions about the tag peeling issue, I thought to have
> a look at what the git glossary says.
>
> I had it in my head that when the git guides were linked to the help
> system, that the --help option provided a short circuit direct to help
> item. However this did not happen.
>
> I found that the capability had been lost, which given that a lot of the
> underpinning knowledge is in the guides this would appear to be a loss.
>
> I don't have an older version to test, but I thought I remember the
> capability from about the time of my 65f98358c0 ("builtin/help.c: add
> --guide option", 2013-04-02).
>
> Have I misremembered the --help capability?
>
> cc'ing Duy in case he remembers something from the recent update

Phew... I didn't break anything!

That behavior has been gone since 2c6b6d9f7d (help: make option --help open man pages only for Git commands, 2016-08-26). Ralf did not mention why he thought "git <concept> --help" was a bad idea. But it was considered a bug by Junio [1]

[1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/

-- 
Duy

Philip Oakley· Apr 7, 2019, 11:52 UTC · re: Duy Nguyen · lore

Re: git glossary --help ?

Hi Duy,

On 07/04/2019 04:20, Duy Nguyen wrote:

Show 26 quoted lines

> On Sun, Apr 7, 2019 at 12:31 AM Philip Oakley <philipoakley@iee.org> wrote:
>> Following the discussions about the tag peeling issue, I thought to have
>> a look at what the git glossary says.
>>
>> I had it in my head that when the git guides were linked to the help
>> system, that the --help option provided a short circuit direct to help
>> item. However this did not happen.
>>
>> I found that the capability had been lost, which given that a lot of the
>> underpinning knowledge is in the guides this would appear to be a loss.
>>
>> I don't have an older version to test, but I thought I remember the
>> capability from about the time of my 65f98358c0 ("builtin/help.c: add
>> --guide option", 2013-04-02).
>>
>> Have I misremembered the --help capability?
>>
>> cc'ing Duy in case he remembers something from the recent update
> Phew... I didn't break anything!
>
> That behavior has been gone since 2c6b6d9f7d (help: make option --help
> open man pages only for Git commands, 2016-08-26). Ralf did not
> mention why he thought "git <concept> --help" was a bad idea. But it
> was considered a bug by Junio [1]
>
> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/

Thanks for the link. I see I responded later in the thread but didn't follow it up sufficiently (not sure what I was doing back then.. summer break maybe).

I do think we are sometimes a bit dismissive of features (accidental bias) that help the general user in getting help. If we think that 'git help' is the (one) right way of providing access to manuals (such as the concept guides) then maybe we shouldn't have the ubiquitous --help option for all the commands. Or,

Or, we should be liberal in what we accept from others (Postel's Law). It is normal to type 'git foo --help'. So maybe allow these multiple ways of accessing the documentation. Given the update to the command list capability, I'll add it to my todo list to see if we can accept guide names with --help and, one way or another, get folk to the right place (the guide or command they should have used/requested).

-- 
Philip

Junio C Hamano· Apr 7, 2019, 13:43 UTC · re: Duy Nguyen · lore

Re: git glossary --help ?

Duy Nguyen <pclouds@gmail.com> writes:

Show 8 quoted lines

> Phew... I didn't break anything!
>
> That behavior has been gone since 2c6b6d9f7d (help: make option --help
> open man pages only for Git commands, 2016-08-26). Ralf did not
> mention why he thought "git <concept> --help" was a bad idea. But it
> was considered a bug by Junio [1]
>
> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/

I do not think you are reading me correctly.

Yes, I do consider that "git foo --help" that does not say "there is no subcomand 'foo' in Git suite" is a bug. But that is only for 'foo' that is clearly meant as a command.

I do not imagine anybody labelling "git help glossary" as a bug.

I am fairly neutral about "git glossary --help". I personally would not ask git like so, as "glossary" is clearly not a command name, and the "--help" option is clearly meant as an option to the subcommand, which means that the request logically does not make much sense.

But unlike "git foo --help", if the word that ought to name a subcommand instead names a known concept, e.g. "glossary", I do not think it is too bad if we DWIMmed what the user meant to say, i.e. turning "git glossary --help" into "git help glossary".

Philip Oakley· Apr 7, 2019, 22:42 UTC · re: Junio C Hamano · lore

Re: git glossary --help ?

Hi Junio,

On 07/04/2019 14:43, Junio C Hamano wrote:

Show 29 quoted lines

> Duy Nguyen <pclouds@gmail.com> writes:
>
>> Phew... I didn't break anything!
>>
>> That behavior has been gone since 2c6b6d9f7d (help: make option --help
>> open man pages only for Git commands, 2016-08-26). Ralf did not
>> mention why he thought "git <concept> --help" was a bad idea. But it
>> was considered a bug by Junio [1]
>>
>> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/
> I do not think you are reading me correctly.
>
> Yes, I do consider that "git foo --help" that does not say "there is
> no subcomand 'foo' in Git suite" is a bug.  But that is only for
> 'foo' that is clearly meant as a command.
>
> I do not imagine anybody labelling "git help glossary" as a bug.
>
> I am fairly neutral about "git glossary --help".  I personally would
> not ask git like so, as "glossary" is clearly not a command name,
> and the "--help" option is clearly meant as an option to the
> subcommand, which means that the request logically does not make
> much sense.
>
> But unlike "git foo --help", if the word that ought to name a
> subcommand instead names a known concept, e.g. "glossary", I do not
> think it is too bad if we DWIMmed what the user meant to say,
> i.e. turning "git glossary --help" into "git help glossary".
>

Given the earlier report that started the thread Duy linked, I guess there will need to be a balance between the two expectations.

The DWIMming may need to both report that it's not a command, but then offer the concept guide as the primary target if correct, or perhaps as one of the alternate "commands" if closely named to a guide (e.g. revisions vs revision).

One of the issues back then was the lack of a complete list of 'guides' to check against, so the badly spelt command logic wasn't brought into play. -- Philip

Junio C Hamano· Apr 8, 2019, 01:06 UTC · re: Philip Oakley · lore

Re: git glossary --help ?

Philip Oakley <philipoakley@iee.org> writes:

Show 12 quoted lines

>> But unlike "git foo --help", if the word that ought to name a
>> subcommand instead names a known concept, e.g. "glossary", I do not
>> think it is too bad if we DWIMmed what the user meant to say,
>> i.e. turning "git glossary --help" into "git help glossary".
>>
> Given the earlier report that started the thread Duy linked, I guess
> there will need to be a balance between the two expectations.
>
> The DWIMming may need to both report that it's not a command, but
> then offer the concept guide as the primary target if correct, or
> perhaps as one of the alternate "commands" if closely named to a guide
> (e.g. revisions vs revision).

The "or perhaps" part feels a bit overkill, but I do not mind seeing it if somebody does it cleanly and correctly ;-)

> One of the issues back then was the lack of a complete list of
> 'guides' to check against, so the badly spelt command logic wasn't
> brought into play.

Yeah, thanks for spelling it out; I think we are on the same page, having followed the same discussion in the archive, where we knew that a list of 'concepts-not-commands' would help the error message situation.