Re: [PATCH] help: allow redirecting to help for aliased command

From: Rasmus Villemoes <rv@rasmusvillemoes.dk>
Date: Sep 28, 2018, 08:18 UTC
Message-ID: <3677a12b-5b9b-ad2a-1e3a-7de251baa40d@rasmusvillemoes.dk>
In-Reply-To: <20180926184914.GC30680@sigill.intra.peff.net>

On 2018-09-26 20:49, Jeff King wrote:

Show 22 quoted lines

> On Wed, Sep 26, 2018 at 08:16:36AM -0700, Junio C Hamano wrote:
> 
>>
>> If we expect users to use "git cp --help" a lot more often than "git
>> help cp" (or the other way around), one way to give a nicer experience
>> may be to unconditionally make "git cp --help" to directly show the
>> manpage of cherry-pick, while keeping "git help cp" to never do
>> that.  Then those who want to remember what "co" is aliased to can
>> ask "git help co".
> 
> I like that direction much better. I also wondered if we could leverage
> the "-h" versus "--help" distinction. The problem with printing the
> alias definition along with "--help" is that the latter will start a
> pager that obliterates what we wrote before (and hence all of this delay
> trickery).
> 
> But for "-h" we generally expect the command to output a usage message.
> 
> So what if the rules were:
> 
>   - "git help cp" shows "cp is an alias for cherry-pick" (as it does
>     now)

Sounds good.

Show 6 quoted lines

>   - "git cp -h" shows "cp is an alias for cherry-pick", followed by
>     actually running "cherry-pick -h", which will show the usage
>     message. For a single-word command that does very little, since the
>     usage message starts with "cherry-pick". But if your alias is
>     actually "cp = cherry-pick -n", then it _is_ telling you extra
>     information.

Funny, I never noticed this difference, and that '-h' for an alias would actually give more information than '--help'. I sort-of knew that -h would give the synopsis, so I guess I've just gotten used to always use --help, and just noticed that for aliases that doesn't provide much help.

Adding the 'is an alias for' info to -h sounds quite sensible.

And this could even work with "!" aliases: we define

>     it, and then it is up to the alias to handle "-h" sensibly.

I'd be nervous about doing this, though, especially if we introduce this without a new opt-in config option (which seems to be the direction the discussion is taking). There are lots of commands that don't respond with a help message to -h, or that only recognize -h as the first word, or... There are really too many ways this could cause headaches.

But, now that I test it, it seems that we already let the alias handle -h (and any other following words, with --help as the first word special-cased). So what you're suggesting is (correct me if I'm wrong) to _also_ intercept -h as the first word, and then print the alias info, in addition to spawning the alias with the entire argv as usual. The alias info would probably need to go to stderr in this case.

>   - "git cp --help" opens the manpage for cherry-pick. We don't bother
>     with the alias definition, as it's available through other means
>     (and thus we skip the obliteration/timing thing totally).

It sounds like you suggest doing this unconditionally, and without any opt-in via config option or a short wait? That would certainly work for me. It is, in fact, how I expect 'git cp --help' to work, until I get reminded that it does not... Also, as Junio noted, is consistent with --help generally providing more information than -h - except that one loses the 'is an alias for' part for --help.

>     This really only works for non-! aliases. Those would continue to
>     show the alias definition.

Yes.

Thanks, Rasmus