git glossary --help ?

git glossary --help ?

[Philip Oakley]

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

Re: git glossary --help ?

[Andreas Schwab]

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.

-- 
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."

Re: git glossary --help ?

[Philip Oakley]

Hi Andreas,

On 06/04/2019 19:09, Andreas Schwab wrote:
> 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

Re: git glossary --help ?

[Duy Nguyen]

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/
-- 
Duy

Re: git glossary --help ?

[Philip Oakley]

Hi Duy,

On 07/04/2019 04:20, Duy Nguyen wrote:
> 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

Re: git glossary --help ?

[Junio C Hamano]

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".

Re: git glossary --help ?

[Philip Oakley]

Hi Junio,

On 07/04/2019 14:43, Junio C Hamano wrote:
> 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

Re: git glossary --help ?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

>> 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.