Re: git glossary --help ?

From: Philip Oakley <philipoakley@talktalk.net>
Date: Apr 7, 2019, 11:52 UTC
Message-ID: <8e40eb85-0368-d12f-f238-acababdcd858@talktalk.net>
In-Reply-To: <CACsJy8DE4WfbU2y8+__4qD7V5FLodKjxX-bu+seE8mh65q8FYQ@mail.gmail.com>

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