{"thread":{"id":"33077","subject":"[PATCH] help: show manpage for aliased command on git --help","startedAt":"2013-03-05T14:44:41Z","lastAt":"2013-03-06T23:55:47Z","messageCount":10,"participants":["Ævar Arnfjörð Bjarmason","Johannes Sixt","H.Merijn Brand","Junio C Hamano","Matthieu Moy","Jeff King","Michael J Gruber"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"210626","messageId":"1362494681-11419-1-git-send-email-avarab@gmail.com","threadId":"33077","inReplyTo":null,"subject":"[PATCH] help: show manpage for aliased command on git --help","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2013-03-05T14:44:41Z","receivedAt":"2013-03-05T14:44:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the semantics of \"git --help\" to show the help for the\ncommand is aliased to, instead of just saying:\n\n `git ' is aliased to `'\n\nE.g. if you have \"checkout\" aliased to \"co\" you won't get:\n\n $ git co --help\n `git co' is aliased to `checkout'\n\nBut will instead get the manpage for git-checkout. The behavior this\nis replacing was originally added by Jeff King in 2156435. I'm\nchanging it because of this off-the-cuff comment on IRC:\n\n 14:27:43 <@Tux> git can be very unhelpful, literally:\n 14:27:46 <@Tux> $ git co --help\n 14:27:46 <@Tux> `git co' is aliased to `checkout'\n 14:28:08 <@Tux> I know!, gimme the help for checkout, please\n\nAnd because I also think it makes more sense than showing you what the\nthing is aliased to.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n builtin/help.c | 12 +++++++-----\n 1 file changed, 7 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/help.c b/builtin/help.c\nindex d1d7181..fdb3312 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -417,6 +417,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n {\n \tint nongit;\n \tconst char *alias;\n+\tconst char *show_help_for;\n \tenum help_format parsed_help_format;\n \tload_command_list(\"git-\", &main_cmds, &other_cmds);\n \n@@ -449,20 +450,21 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \n \talias = alias_lookup(argv[0]);\n \tif (alias && !is_git_command(argv[0])) {\n-\t\tprintf_ln(_(\"`git %s' is aliased to `%s'\"), argv[0], alias);\n-\t\treturn 0;\n+\t\tshow_help_for = alias;\n+\t} else {\n+\t\tshow_help_for = argv[0];\n \t}\n \n \tswitch (help_format) {\n \tcase HELP_FORMAT_NONE:\n \tcase HELP_FORMAT_MAN:\n-\t\tshow_man_page(argv[0]);\n+\t\tshow_man_page(show_help_for);\n \t\tbreak;\n \tcase HELP_FORMAT_INFO:\n-\t\tshow_info_page(argv[0]);\n+\t\tshow_info_page(show_help_for);\n \t\tbreak;\n \tcase HELP_FORMAT_WEB:\n-\t\tshow_html_page(argv[0]);\n+\t\tshow_html_page(show_help_for);\n \t\tbreak;\n \t}\n \n-- \n1.7.10.4\n"},{"id":"210630","messageId":"5136127C.2090402@viscovery.net","threadId":"33077","inReplyTo":"1362494681-11419-1-git-send-email-avarab@gmail.com","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2013-03-05T15:42:52Z","receivedAt":"2013-03-05T15:42:52Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 3/5/2013 15:44, schrieb Ævar Arnfjörð Bjarmason:\n> Change the semantics of \"git --help\" to show the help for the\n> command is aliased to, instead of just saying:\n> \n> `git ' is aliased to `'\n> \n> E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n> \n> $ git co --help\n> `git co' is aliased to `checkout'\n> \n> But will instead get the manpage for git-checkout.\n...\n> \talias = alias_lookup(argv[0]);\n> \tif (alias && !is_git_command(argv[0])) {\n> -\t\tprintf_ln(_(\"`git %s' is aliased to `%s'\"), argv[0], alias);\n> -\t\treturn 0;\n> +\t\tshow_help_for = alias;\n> +\t} else {\n> +\t\tshow_help_for = argv[0];\n> \t}\n\nThis needs a lot more scrutiny. The alias can be more than just a single\nword, and it can even be a shell scriptlet, i.e., not a git command at all.\n\nIt may make sense to show the help of the aliased-to command if the alias\nresolves to just a single word.\n\n-- Hannes\n"},{"id":"210634","messageId":"20130305165453.6077226c@pc09.procura.nl","threadId":"33077","inReplyTo":"5136127C.2090402@viscovery.net","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"H.Merijn Brand","fromEmail":"h.m.brand@xs4all.nl","sentAt":"2013-03-05T15:54:53Z","receivedAt":"2013-03-05T15:54:53Z","isPatch":true,"sender":{"key":"h.m.brand@xs4all.nl","avatar":"https://gravatar.com/avatar/5b8f83ee35c427a646cbea3b104346e00ab3663b99bbf435cddeb75cd4b3857b?d=mp&s=160"},"body":"On Tue, 05 Mar 2013 16:42:52 +0100, Johannes Sixt\n wrote:\n\n> Am 3/5/2013 15:44, schrieb Ævar Arnfjörð Bjarmason:\n> > Change the semantics of \"git --help\" to show the help for the\n> > command is aliased to, instead of just saying:\n> > \n> > `git ' is aliased to `'\n> > \n> > E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n> > \n> > $ git co --help\n> > `git co' is aliased to `checkout'\n> > \n> > But will instead get the manpage for git-checkout.\n> ...\n> > \talias = alias_lookup(argv[0]);\n> > \tif (alias && !is_git_command(argv[0])) {\n> > -\t\tprintf_ln(_(\"`git %s' is aliased to `%s'\"), argv[0], alias);\n> > -\t\treturn 0;\n> > +\t\tshow_help_for = alias;\n> > +\t} else {\n> > +\t\tshow_help_for = argv[0];\n> > \t}\n> \n> This needs a lot more scrutiny. The alias can be more than just a single\n> word, and it can even be a shell scriptlet, i.e., not a git command at all.\n> \n> It may make sense to show the help of the aliased-to command if the alias\n> resolves to just a single word.\n\nA single word that is (already) known to git as being a valid command\nto do --help with. I which case I fully agree.\n\n-- \nH.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/\nusing perl5.00307 .. 5.17 porting perl5 on HP-UX, AIX, and openSUSE\nhttp://mirrors.develooper.com/hpux/ http://www.test-smoke.org/\nhttp://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/\n"},{"id":"210637","messageId":"7v8v61vn3h.fsf@alter.siamese.dyndns.org","threadId":"33077","inReplyTo":"1362494681-11419-1-git-send-email-avarab@gmail.com","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-05T16:16:18Z","receivedAt":"2013-03-05T16:16:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Change the semantics of \"git --help\" to show the help for the\n> command is aliased to, instead of just saying:\n>\n> `git ' is aliased to `'\n>\n> E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n>\n> $ git co --help\n> `git co' is aliased to `checkout'\n\nIf you had \"lg\" aliased to \"log --oneline\" and you made\n\n $ git lg --help\n\nto give anything but\n\n 'git lg' is aliased to `log --oneline'\n\nI would say that is a grave regression.\n"},{"id":"210638","messageId":"CACBZZX5=ARahxswkN_mLbBF3fQxV-HtKgehe_3ogHg5-i7utYw@mail.gmail.com","threadId":"33077","inReplyTo":"7v8v61vn3h.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2013-03-05T16:32:13Z","receivedAt":"2013-03-05T16:32:13Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, Mar 5, 2013 at 5:16 PM, Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Change the semantics of \"git --help\" to show the help for the\n>> command is aliased to, instead of just saying:\n>>\n>> `git ' is aliased to `'\n>>\n>> E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n>>\n>> $ git co --help\n>> `git co' is aliased to `checkout'\n>\n> If you had \"lg\" aliased to \"log --oneline\" and you made\n>\n> $ git lg --help\n>\n> to give anything but\n>\n> 'git lg' is aliased to `log --oneline'\n>\n> I would say that is a grave regression.\n\nGood point. I'll fix that up.\n\nNo objection to the patch in principle though? I.e. not showing you\nwhat the alias points to.\n"},{"id":"210641","messageId":"vpqy5e17qak.fsf@grenoble-inp.fr","threadId":"33077","inReplyTo":"20130305165453.6077226c@pc09.procura.nl","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-03-05T16:41:07Z","receivedAt":"2013-03-05T16:41:07Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"H.Merijn Brand\" writes:\n\n> A single word that is (already) known to git as being a valid command\n> to do --help with. I which case I fully agree.\n\nJust to insist on \"that is known to git as being a valid command\".\n\nCompare:\n\n$ git foo --help\n`git foo' is aliased to `bar'\n\nwith\n\n$ git foo --help\nNo manual entry for gitbar\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"210640","messageId":"7v4ngpvlfj.fsf@alter.siamese.dyndns.org","threadId":"33077","inReplyTo":"CACBZZX5=ARahxswkN_mLbBF3fQxV-HtKgehe_3ogHg5-i7utYw@mail.gmail.com","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-05T16:52:16Z","receivedAt":"2013-03-05T16:52:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> No objection to the patch in principle though? I.e. not showing you\n> what the alias points to.\n\nI am not interested enough to even strongly object to such a change,\nbecause it is not reasonable to react with a \"I know!\" to the output\nof \"git co --help\", i.e. \"'git co' is aliased to 'checkout'\", in the\nfirst place. Also some users may find it inconsistent if a single\nbareword jumps directly to the manpage and other input shows alias\nexpansion.\n\nSo,... I do not see a very big plus in the proposed (and then\namended by others in the thread) change, but if the damage to the\ncode that is necessary to implement it is not too bad, perhaps it is\nan OK thing to do. I don't know without seeing the patch.\n"},{"id":"210645","messageId":"20130305173831.GB9379@sigill.intra.peff.net","threadId":"33077","inReplyTo":"1362494681-11419-1-git-send-email-avarab@gmail.com","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2013-03-05T17:38:31Z","receivedAt":"2013-03-05T17:38:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Mar 05, 2013 at 02:44:41PM +0000, Ævar Arnfjörð Bjarmason wrote:\n\n> Change the semantics of \"git --help\" to show the help for the\n> command is aliased to, instead of just saying:\n> \n> `git ' is aliased to `'\n> \n> E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n> \n> $ git co --help\n> `git co' is aliased to `checkout'\n> \n> But will instead get the manpage for git-checkout. The behavior this\n> is replacing was originally added by Jeff King in 2156435. I'm\n> changing it because of this off-the-cuff comment on IRC:\n> \n> 14:27:43 <@Tux> git can be very unhelpful, literally:\n> 14:27:46 <@Tux> $ git co --help\n> 14:27:46 <@Tux> `git co' is aliased to `checkout'\n> 14:28:08 <@Tux> I know!, gimme the help for checkout, please\n> \n> And because I also think it makes more sense than showing you what the\n> thing is aliased to.\n\nIn this simple case, I think it is helpful to show the \"checkout\"\nmanpage, because there is no other information to give (and by showing\nthe checkout manpage, you implicitly indicate that \"co\" maps to\n\"checkout\").\n\nBut like others, I am concerned about the other cases, where there is no\nmanpage, it is not a git command with a manpage, or it is a git command\nwith options. You are losing useful information that is currently given\nto the user in all but the single-word case.\n\nIn an ideal world, we could say \"here is how the alias expands, and by\nthe way, here is the manpage for the expanded command\". And obviously\njust omit the latter part when there is no such page. But we are relying\non external programs to do the presentation and paging. Doing the\nC equivalent of:\n\n echo \"'git co' is aliased to 'checkout'\" &&\n man checkout\n\ndoes not quite work, because \"man\" will start a pager. We can run our\nown pager (which should suppress man's invocation), but that is a\nregression for anyone who uses MANPAGER.\n\nThe user may also be using help.format to use something besides man. If\nhelp.format is set to \"html\", we will spawn a browser. In that case we\ncan still output the alias information, but it may or may not be seen\n(though come to think of it, that is probably already a problem for \"git\nhelp \" on Windows systems, or anybody invoking git help from a\nGUI porcelain).\n\nSo I'd only be in favor of this patch if it managed to avoid information\nloss in the more complicated cases. And I'm not sure how best to do\nthat. The \"only trigger for a single-word alias\" suggestion seems like\nthe least ugly to me.\n\n-Peff\n"},{"id":"210696","messageId":"51374029.6080906@drmicha.warpmail.net","threadId":"33077","inReplyTo":"20130305173831.GB9379@sigill.intra.peff.net","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2013-03-06T13:10:01Z","receivedAt":"2013-03-06T13:10:01Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 05.03.2013 18:38:\n> On Tue, Mar 05, 2013 at 02:44:41PM +0000, Ævar Arnfjörð Bjarmason wrote:\n> \n>> Change the semantics of \"git --help\" to show the help for the\n>> command is aliased to, instead of just saying:\n>>\n>> `git ' is aliased to `'\n>>\n>> E.g. if you have \"checkout\" aliased to \"co\" you won't get:\n>>\n>> $ git co --help\n>> `git co' is aliased to `checkout'\n>>\n>> But will instead get the manpage for git-checkout. The behavior this\n>> is replacing was originally added by Jeff King in 2156435. I'm\n>> changing it because of this off-the-cuff comment on IRC:\n>>\n>> 14:27:43 <@Tux> git can be very unhelpful, literally:\n>> 14:27:46 <@Tux> $ git co --help\n>> 14:27:46 <@Tux> `git co' is aliased to `checkout'\n>> 14:28:08 <@Tux> I know!, gimme the help for checkout, please\n>>\n>> And because I also think it makes more sense than showing you what the\n>> thing is aliased to.\n> \n> In this simple case, I think it is helpful to show the \"checkout\"\n> manpage, because there is no other information to give (and by showing\n> the checkout manpage, you implicitly indicate that \"co\" maps to\n> \"checkout\").\n\nWell, even in the simple case one has to wonder: Why does the user\ninvoke help for \"co\"? There are two very likely cases:\n\nA) User does not remember what \"co\" is aliased to.\nB) User wants to see the man page.\n\nIf A is not the case then it's easy for the user to request help for\n\"checkout\" (or \"commit\" or ...).\n\nRemoving the only easy way to look up the definition of an alias is a\nmajor regression. And no, \"git config --get alias.co\" is not an easy way.\n\nRemoving that easy way would be OK only after introducing a \"git alias\"\ncommand which works similar to shell's alias. You can even set it up as\nan alias for git config, of course.\n\n> But like others, I am concerned about the other cases, where there is no\n> manpage, it is not a git command with a manpage, or it is a git command\n> with options. You are losing useful information that is currently given\n> to the user in all but the single-word case.\n> \n> In an ideal world, we could say \"here is how the alias expands, and by\n> the way, here is the manpage for the expanded command\". And obviously\n> just omit the latter part when there is no such page. But we are relying\n> on external programs to do the presentation and paging. Doing the\n> C equivalent of:\n> \n> echo \"'git co' is aliased to 'checkout'\" &&\n> man checkout\n> \n> does not quite work, because \"man\" will start a pager. We can run our\n> own pager (which should suppress man's invocation), but that is a\n> regression for anyone who uses MANPAGER.\n> \n> The user may also be using help.format to use something besides man. If\n> help.format is set to \"html\", we will spawn a browser. In that case we\n> can still output the alias information, but it may or may not be seen\n> (though come to think of it, that is probably already a problem for \"git\n> help \" on Windows systems, or anybody invoking git help from a\n> GUI porcelain).\n> \n> So I'd only be in favor of this patch if it managed to avoid information\n> loss in the more complicated cases. And I'm not sure how best to do\n> that. The \"only trigger for a single-word alias\" suggestion seems like\n> the least ugly to me.\n> \n> -Peff\n> \n"},{"id":"210732","messageId":"7vtxoonkvw.fsf@alter.siamese.dyndns.org","threadId":"33077","inReplyTo":"51374029.6080906@drmicha.warpmail.net","subject":"Re: [PATCH] help: show manpage for aliased command on git --help","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-06T23:55:47Z","receivedAt":"2013-03-06T23:55:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> Well, even in the simple case one has to wonder: Why does the user\n> invoke help for \"co\"? There are two very likely cases:\n>\n> A) User does not remember what \"co\" is aliased to.\n> B) User wants to see the man page.\n>\n> If A is not the case then it's easy for the user to request help for\n> \"checkout\" (or \"commit\" or ...).\n>\n> Removing the only easy way to look up the definition of an alias is a\n> major regression.\n\nVery well said ;-).\n"}]}