* git glossary --help ?
@ 2019-04-06 17:31 Philip Oakley
2019-04-06 18:09 ` Andreas Schwab
2019-04-07 3:20 ` Duy Nguyen
0 siblings, 2 replies; 8+ messages in thread
From: Philip Oakley @ 2019-04-06 17:31 UTC (permalink / raw)
To: Git List, Duy Nguyen
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-06 17:31 git glossary --help ? Philip Oakley
@ 2019-04-06 18:09 ` Andreas Schwab
2019-04-06 20:27 ` Philip Oakley
2019-04-07 3:20 ` Duy Nguyen
1 sibling, 1 reply; 8+ messages in thread
From: Andreas Schwab @ 2019-04-06 18:09 UTC (permalink / raw)
To: Philip Oakley; +Cc: Git List, Duy Nguyen
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."
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-06 18:09 ` Andreas Schwab
@ 2019-04-06 20:27 ` Philip Oakley
0 siblings, 0 replies; 8+ messages in thread
From: Philip Oakley @ 2019-04-06 20:27 UTC (permalink / raw)
To: Andreas Schwab; +Cc: Git List, Duy Nguyen
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-06 17:31 git glossary --help ? Philip Oakley
2019-04-06 18:09 ` Andreas Schwab
@ 2019-04-07 3:20 ` Duy Nguyen
2019-04-07 11:52 ` Philip Oakley
2019-04-07 13:43 ` Junio C Hamano
1 sibling, 2 replies; 8+ messages in thread
From: Duy Nguyen @ 2019-04-07 3:20 UTC (permalink / raw)
To: Philip Oakley; +Cc: Git List, Ralf Thielow, Junio C Hamano
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-07 3:20 ` Duy Nguyen
@ 2019-04-07 11:52 ` Philip Oakley
2019-04-07 13:43 ` Junio C Hamano
1 sibling, 0 replies; 8+ messages in thread
From: Philip Oakley @ 2019-04-07 11:52 UTC (permalink / raw)
To: Duy Nguyen, Philip Oakley; +Cc: Git List, Ralf Thielow, Junio C Hamano
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-07 3:20 ` Duy Nguyen
2019-04-07 11:52 ` Philip Oakley
@ 2019-04-07 13:43 ` Junio C Hamano
2019-04-07 22:42 ` Philip Oakley
1 sibling, 1 reply; 8+ messages in thread
From: Junio C Hamano @ 2019-04-07 13:43 UTC (permalink / raw)
To: Duy Nguyen; +Cc: Philip Oakley, Git List, Ralf Thielow
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".
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-07 13:43 ` Junio C Hamano
@ 2019-04-07 22:42 ` Philip Oakley
2019-04-08 1:06 ` Junio C Hamano
0 siblings, 1 reply; 8+ messages in thread
From: Philip Oakley @ 2019-04-07 22:42 UTC (permalink / raw)
To: Junio C Hamano, Duy Nguyen; +Cc: Git List, Ralf Thielow
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: git glossary --help ?
2019-04-07 22:42 ` Philip Oakley
@ 2019-04-08 1:06 ` Junio C Hamano
0 siblings, 0 replies; 8+ messages in thread
From: Junio C Hamano @ 2019-04-08 1:06 UTC (permalink / raw)
To: Philip Oakley; +Cc: Duy Nguyen, Git List, Ralf Thielow
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2019-04-08 1:08 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-06 17:31 git glossary --help ? Philip Oakley
2019-04-06 18:09 ` Andreas Schwab
2019-04-06 20:27 ` Philip Oakley
2019-04-07 3:20 ` Duy Nguyen
2019-04-07 11:52 ` Philip Oakley
2019-04-07 13:43 ` Junio C Hamano
2019-04-07 22:42 ` Philip Oakley
2019-04-08 1:06 ` Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).