Re: [PATCH] help: show manpage for aliased command on git <alias> --help

From: Jeff King <peff@peff.net>
Date: Mar 5, 2013, 17:38 UTC
Message-ID: <20130305173831.GB9379@sigill.intra.peff.net>
In-Reply-To: <1362494681-11419-1-git-send-email-avarab@gmail.com>

On Tue, Mar 05, 2013 at 02:44:41PM +0000, Ævar Arnfjörð Bjarmason wrote:

Show 21 quoted lines

> Change the semantics of "git <alias> --help" to show the help for the
> command <alias> is aliased to, instead of just saying:
> 
>     `git <alias>' is aliased to `<whatever>'
> 
> E.g. if you have "checkout" aliased to "co" you won't get:
> 
>     $ git co --help
>     `git co' is aliased to `checkout'
> 
> But will instead get the manpage for git-checkout. The behavior this
> is replacing was originally added by Jeff King in 2156435. I'm
> changing it because of this off-the-cuff comment on IRC:
> 
>     14:27:43 <@Tux> git can be very unhelpful, literally:
>     14:27:46 <@Tux> $ git co --help
>     14:27:46 <@Tux> `git co' is aliased to `checkout'
>     14:28:08 <@Tux> I know!, gimme the help for checkout, please
> 
> And because I also think it makes more sense than showing you what the
> thing is aliased to.

In this simple case, I think it is helpful to show the "checkout" manpage, because there is no other information to give (and by showing the checkout manpage, you implicitly indicate that "co" maps to "checkout").

But like others, I am concerned about the other cases, where there is no manpage, it is not a git command with a manpage, or it is a git command with options. You are losing useful information that is currently given to the user in all but the single-word case.

In an ideal world, we could say "here is how the alias expands, and by the way, here is the manpage for the expanded command". And obviously just omit the latter part when there is no such page. But we are relying on external programs to do the presentation and paging. Doing the C equivalent of:

  echo "'git co' is aliased to 'checkout'" &&
  man checkout

does not quite work, because "man" will start a pager. We can run our own pager (which should suppress man's invocation), but that is a regression for anyone who uses MANPAGER.

The user may also be using help.format to use something besides man. If help.format is set to "html", we will spawn a browser. In that case we can still output the alias information, but it may or may not be seen (though come to think of it, that is probably already a problem for "git help <alias>" on Windows systems, or anybody invoking git help from a GUI porcelain).

So I'd only be in favor of this patch if it managed to avoid information loss in the more complicated cases. And I'm not sure how best to do that. The "only trigger for a single-word alias" suggestion seems like the least ugly to me.

-Peff