{"thread":{"id":"49404","subject":"[PATCH] git help: promote 'git help -av'","startedAt":"2018-09-22T17:47:21Z","lastAt":"2018-10-01T18:14:58Z","messageCount":18,"participants":["Nguyễn Thái Ngọc Duy","Ævar Arnfjörð Bjarmason","Duy Nguyen","Jeff King","Taylor Blau","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"358700","messageId":"20180922174707.16498-1-pclouds@gmail.com","threadId":"49404","inReplyTo":null,"subject":"[PATCH] git help: promote 'git help -av'","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-22T17:47:07Z","receivedAt":"2018-09-22T17:47:21Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"When you type \"git help\" (or just \"git\") you are greeted with a list\nwith commonly used commands and their short description and are\nsuggested to use \"git help -a\" or \"git help -g\" for more details.\n\n\"git help -av\" would be more friendly and inline with what is shown\nwith \"git help\" since it shows list of commands with description as\nwell, and commands are properly grouped.\n\nSigned-off-by: Nguyễn Thái Ngọc Duy \n---\n git.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/git.c b/git.c\nindex a6f4b44af5..69c21f378b 100644\n--- a/git.c\n+++ b/git.c\n@@ -31,7 +31,7 @@ const char git_usage_string[] =\n \t \" []\");\n \n const char git_more_info_string[] =\n-\tN_(\"'git help -a' and 'git help -g' list available subcommands and some\\n\"\n+\tN_(\"'git help -av' and 'git help -g' list available subcommands and some\\n\"\n \t \"concept guides. See 'git help ' or 'git help '\\n\"\n \t \"to read about a specific subcommand or concept.\");\n \n-- \n2.19.0.647.gb9a6049235\n\n"},{"id":"358712","messageId":"87fty1jppt.fsf@evledraar.gmail.com","threadId":"49404","inReplyTo":"20180922174707.16498-1-pclouds@gmail.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2018-09-22T19:29:18Z","receivedAt":"2018-09-22T19:29:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sat, Sep 22 2018, Nguyễn Thái Ngọc Duy wrote:\n\n> When you type \"git help\" (or just \"git\") you are greeted with a list\n> with commonly used commands and their short description and are\n> suggested to use \"git help -a\" or \"git help -g\" for more details.\n>\n> \"git help -av\" would be more friendly and inline with what is shown\n> with \"git help\" since it shows list of commands with description as\n> well, and commands are properly grouped.\n>\n> Signed-off-by: Nguyễn Thái Ngọc Duy \n> ---\n> git.c | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/git.c b/git.c\n> index a6f4b44af5..69c21f378b 100644\n> --- a/git.c\n> +++ b/git.c\n> @@ -31,7 +31,7 @@ const char git_usage_string[] =\n> \t \" []\");\n>\n> const char git_more_info_string[] =\n> -\tN_(\"'git help -a' and 'git help -g' list available subcommands and some\\n\"\n> +\tN_(\"'git help -av' and 'git help -g' list available subcommands and some\\n\"\n> \t \"concept guides. See 'git help ' or 'git help '\\n\"\n> \t \"to read about a specific subcommand or concept.\");\n\nA side-effect of this not noted in your commit message is that we'll now\ninvoke the pager, perhaps we should just do:\n\n diff --git a/builtin/help.c b/builtin/help.c\n index 8d4f6dd301..1a3b174aaf 100644\n --- a/builtin/help.c\n +++ b/builtin/help.c\n @@ -436,9 +436,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n parsed_help_format = help_format;\n\n if (show_all) {\n + setup_pager();\n git_config(git_help_config, NULL);\n if (verbose) {\n - setup_pager();\n list_all_cmds_help();\n return 0;\n }\n @@ -460,8 +460,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n return 0;\n }\n\n - if (show_guides)\n + if (show_guides) {\n + setup_pager();\n list_common_guides_help();\n + }\n\n if (show_all || show_guides) {\n printf(\"%s\\n\", _(git_more_info_string));\n\nOr is there a good reason we shouldn't invoke the pager for e.g. -g when\nthe terminal is too small (per our default less config)?\n\nAnother thing I noticed: We don't list -v in the git-help manpage, but\nsince we use OPT_VERBOSE it's supported.\n"},{"id":"358714","messageId":"CACsJy8CjZ+eupz+j5go2bRbSyf-cXWvCJkPFjfDejj89Z3j9ig@mail.gmail.com","threadId":"49404","inReplyTo":"87fty1jppt.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-23T06:51:06Z","receivedAt":"2018-09-23T06:51:36Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sat, Sep 22, 2018 at 9:29 PM Ævar Arnfjörð Bjarmason\n wrote:\n>\n>\n> On Sat, Sep 22 2018, Nguyễn Thái Ngọc Duy wrote:\n>\n> > When you type \"git help\" (or just \"git\") you are greeted with a list\n> > with commonly used commands and their short description and are\n> > suggested to use \"git help -a\" or \"git help -g\" for more details.\n> >\n> > \"git help -av\" would be more friendly and inline with what is shown\n> > with \"git help\" since it shows list of commands with description as\n> > well, and commands are properly grouped.\n> >\n> > Signed-off-by: Nguyễn Thái Ngọc Duy \n> > ---\n> > git.c | 2 +-\n> > 1 file changed, 1 insertion(+), 1 deletion(-)\n> >\n> > diff --git a/git.c b/git.c\n> > index a6f4b44af5..69c21f378b 100644\n> > --- a/git.c\n> > +++ b/git.c\n> > @@ -31,7 +31,7 @@ const char git_usage_string[] =\n> > \" []\");\n> >\n> > const char git_more_info_string[] =\n> > - N_(\"'git help -a' and 'git help -g' list available subcommands and some\\n\"\n> > + N_(\"'git help -av' and 'git help -g' list available subcommands and some\\n\"\n> > \"concept guides. See 'git help ' or 'git help '\\n\"\n> > \"to read about a specific subcommand or concept.\");\n>\n> A side-effect of this not noted in your commit message is that we'll now\n> invoke the pager, perhaps we should just do:\n>\n> diff --git a/builtin/help.c b/builtin/help.c\n> index 8d4f6dd301..1a3b174aaf 100644\n> --- a/builtin/help.c\n> +++ b/builtin/help.c\n> @@ -436,9 +436,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n> parsed_help_format = help_format;\n>\n> if (show_all) {\n> + setup_pager();\n> git_config(git_help_config, NULL);\n> if (verbose) {\n> - setup_pager();\n> list_all_cmds_help();\n> return 0;\n> }\n> @@ -460,8 +460,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n> return 0;\n> }\n>\n> - if (show_guides)\n> + if (show_guides) {\n> + setup_pager();\n> list_common_guides_help();\n> + }\n>\n> if (show_all || show_guides) {\n> printf(\"%s\\n\", _(git_more_info_string));\n>\n> Or is there a good reason we shouldn't invoke the pager for e.g. -g when\n> the terminal is too small (per our default less config)?\n\nDifferent pagers may behave differently (and so far \"help -a\" still\nfits in my screen). So I don't think we should invoke pager more than\nnecessary.\n-- \nDuy\n"},{"id":"358771","messageId":"20180924181927.GB25341@sigill.intra.peff.net","threadId":"49404","inReplyTo":"20180922174707.16498-1-pclouds@gmail.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-09-24T18:19:28Z","receivedAt":"2018-09-24T18:19:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Sep 22, 2018 at 07:47:07PM +0200, Nguyễn Thái Ngọc Duy wrote:\n\n> When you type \"git help\" (or just \"git\") you are greeted with a list\n> with commonly used commands and their short description and are\n> suggested to use \"git help -a\" or \"git help -g\" for more details.\n> \n> \"git help -av\" would be more friendly and inline with what is shown\n> with \"git help\" since it shows list of commands with description as\n> well, and commands are properly grouped.\n\nI agree that \"help -av\" is likely to be more friendly. I kind of wonder\nif it should just be the default for \"-a\". Do we have any obligation not\nto change the format of that output?\n\nAssuming we want to keep \"-a\" and \"-av\" as-is, your patch seems quite\nsensible to me.\n\n-Peff\n"},{"id":"358777","messageId":"20180924202000.GA88744@syl","threadId":"49404","inReplyTo":"20180924181927.GB25341@sigill.intra.peff.net","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2018-09-24T20:20:00Z","receivedAt":"2018-09-24T20:20:15Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, Sep 24, 2018 at 02:19:28PM -0400, Jeff King wrote:\n> On Sat, Sep 22, 2018 at 07:47:07PM +0200, Nguyễn Thái Ngọc Duy wrote:\n>\n> > When you type \"git help\" (or just \"git\") you are greeted with a list\n> > with commonly used commands and their short description and are\n> > suggested to use \"git help -a\" or \"git help -g\" for more details.\n> >\n> > \"git help -av\" would be more friendly and inline with what is shown\n> > with \"git help\" since it shows list of commands with description as\n> > well, and commands are properly grouped.\n>\n> I agree that \"help -av\" is likely to be more friendly. I kind of wonder\n> if it should just be the default for \"-a\". Do we have any obligation not\n> to change the format of that output?\n\nI agree, though I'd like to clarify what you said before doing so\nwholeheartedly.\n\nDid you mean that all existing uses of 'git help -a' should instead mean\n'git help -av' (i.e., that '-a' after your proposed patch means the same\nas '-av' in revisions prior to this one?)\n\nIf so, I agree. I can't imagine a case where I'd like to provide '-a'\nand _not_ '-v', so certainly the later should come as a two-for-one\ndeal. Less, more well-intentioned knobs seems a positive trend to me, so\nI am for this idea.\n\nThanks,\nTaylor\n"},{"id":"358778","messageId":"20180924203049.GA26044@sigill.intra.peff.net","threadId":"49404","inReplyTo":"20180924202000.GA88744@syl","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-09-24T20:30:49Z","receivedAt":"2018-09-24T20:30:52Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Sep 24, 2018 at 03:20:00PM -0500, Taylor Blau wrote:\n\n> On Mon, Sep 24, 2018 at 02:19:28PM -0400, Jeff King wrote:\n> > On Sat, Sep 22, 2018 at 07:47:07PM +0200, Nguyễn Thái Ngọc Duy wrote:\n> >\n> > > When you type \"git help\" (or just \"git\") you are greeted with a list\n> > > with commonly used commands and their short description and are\n> > > suggested to use \"git help -a\" or \"git help -g\" for more details.\n> > >\n> > > \"git help -av\" would be more friendly and inline with what is shown\n> > > with \"git help\" since it shows list of commands with description as\n> > > well, and commands are properly grouped.\n> >\n> > I agree that \"help -av\" is likely to be more friendly. I kind of wonder\n> > if it should just be the default for \"-a\". Do we have any obligation not\n> > to change the format of that output?\n> \n> I agree, though I'd like to clarify what you said before doing so\n> wholeheartedly.\n> \n> Did you mean that all existing uses of 'git help -a' should instead mean\n> 'git help -av' (i.e., that '-a' after your proposed patch means the same\n> as '-av' in revisions prior to this one?)\n\nYes, exactly. I think the vast majority of uses would prefer the\ncategorized list.\n\nThe obvious exceptions are:\n\n - you can't remember the name of the command so an alphabetized list is\n easier for sifting through (without having to re-sift for each\n category).\n\n - you need a machine-readable version of the list (e.g., for\n programmable completion). We have \"git --list-cmds\", but we may need\n to advertise it better and mark it non-experimental.\n\nI dunno. Maybe it is not worth the effort. Duy's existing patch is an\neasy one liner. ;)\n\n-Peff\n"},{"id":"358784","messageId":"xmqq4leesjdc.fsf@gitster-ct.c.googlers.com","threadId":"49404","inReplyTo":"20180924181927.GB25341@sigill.intra.peff.net","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-24T20:58:23Z","receivedAt":"2018-09-24T20:58:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I agree that \"help -av\" is likely to be more friendly. I kind of wonder\n> if it should just be the default for \"-a\". Do we have any obligation not\n> to change the format of that output?\n\nI know that at least older versions of git-completion.bash (I think\nit was up to 2.17.x series, but do not quote me on that) have parsed\n\"git help -a\" output to obtain the list of commands. So such a\nchange would impact those minority users who keep stale completion\nscript in their $HOME/.bashrc without ever update it, thinking it is\ngood enough.\n\nI personally find \"help -av\" a bit too loud to my taste than plain\n\"-a\", and more importantly, I look at \"help -a\" primarily to check\nthe last section \"avaialble from elsewhere on your $PATH\" to find\nthings like \"clang-format\", which I do not think is available\nanywhere in \"help -av\", so I do not think \"-av\" can be promoted as\nan upward-compatible replacement in its current form.\n\nI probably am not a part of the target audience, though.\n\n\n"},{"id":"358836","messageId":"CACsJy8D1EMCqvBdxbta4oocMF33jwDf1=opXwZ0aRN7LYu=JXg@mail.gmail.com","threadId":"49404","inReplyTo":"xmqq4leesjdc.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-25T15:15:38Z","receivedAt":"2018-09-25T15:16:07Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Sep 24, 2018 at 10:58 PM Junio C Hamano wrote:\n> I personally find \"help -av\" a bit too loud to my taste than plain\n> \"-a\", and more importantly, I look at \"help -a\" primarily to check\n> the last section \"avaialble from elsewhere on your $PATH\" to find\n> things like \"clang-format\", which I do not think is available\n> anywhere in \"help -av\", so I do not think \"-av\" can be promoted as\n> an upward-compatible replacement in its current form.\n\nYep. I also thought \"help -a\" was denser but wasn't sure if it\nactually helps or not. Whenever I look at that block of commands, I\nend up searching anyway. For my use case, \"help -a\" could be better\nserved with something like \"git apropos\".\n\nI think adding another section about external commands in \"help -av\"\nwould address the \"clang-format\" stuff. With that, it's probably good\nenough to completely replace \"help -a\". It may also be good to list\naliases there too in a separate section so you have \"all you can type\"\nin one (big) list.\n--\nDuy\n"},{"id":"358847","messageId":"20180925174451.GA29454@duynguyen.home","threadId":"49404","inReplyTo":"CACsJy8D1EMCqvBdxbta4oocMF33jwDf1=opXwZ0aRN7LYu=JXg@mail.gmail.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-25T17:44:51Z","receivedAt":"2018-09-25T17:44:59Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Sep 25, 2018 at 05:15:38PM +0200, Duy Nguyen wrote:\n> On Mon, Sep 24, 2018 at 10:58 PM Junio C Hamano wrote:\n> > I personally find \"help -av\" a bit too loud to my taste than plain\n> > \"-a\", and more importantly, I look at \"help -a\" primarily to check\n> > the last section \"avaialble from elsewhere on your $PATH\" to find\n> > things like \"clang-format\", which I do not think is available\n> > anywhere in \"help -av\", so I do not think \"-av\" can be promoted as\n> > an upward-compatible replacement in its current form.\n> \n> Yep. I also thought \"help -a\" was denser but wasn't sure if it\n> actually helps or not. Whenever I look at that block of commands, I\n> end up searching anyway. For my use case, \"help -a\" could be better\n> served with something like \"git apropos\".\n> \n> I think adding another section about external commands in \"help -av\"\n> would address the \"clang-format\" stuff. With that, it's probably good\n> enough to completely replace \"help -a\". It may also be good to list\n> aliases there too in a separate section so you have \"all you can type\"\n> in one (big) list.\n\nHere's the patch that adds that external commands and aliases\nsections. I feel that external commands section is definitely good to\nhave even if we don't replace \"help -a\". Aliases are more\nsubjective...\n\n-- 8< --\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 8d4f6dd301..23a34b36e7 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -38,7 +38,6 @@ static const char *html_path;\n static int show_all = 0;\n static int show_guides = 0;\n static int show_config;\n-static int verbose;\n static unsigned int colopts;\n static enum help_format help_format = HELP_FORMAT_NONE;\n static int exclude_guides;\n@@ -53,7 +52,6 @@ static struct option builtin_help_options[] = {\n \t\t\tHELP_FORMAT_WEB),\n \tOPT_SET_INT('i', \"info\", &help_format, N_(\"show info page\"),\n \t\t\tHELP_FORMAT_INFO),\n-\tOPT__VERBOSE(&verbose, N_(\"print command description\")),\n \tOPT_END(),\n };\n \n@@ -437,14 +435,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \n \tif (show_all) {\n \t\tgit_config(git_help_config, NULL);\n-\t\tif (verbose) {\n-\t\t\tsetup_pager();\n-\t\t\tlist_all_cmds_help();\n-\t\t\treturn 0;\n-\t\t}\n-\t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n-\t\tload_command_list(\"git-\", &main_cmds, &other_cmds);\n-\t\tlist_commands(colopts, &main_cmds, &other_cmds);\n+\t\tsetup_pager();\n+\t\tlist_all_cmds_help();\n+\t\treturn 0;\n \t}\n \n \tif (show_config) {\ndiff --git a/help.c b/help.c\nindex 96f6d221ed..4a168230dc 100644\n--- a/help.c\n+++ b/help.c\n@@ -98,7 +98,8 @@ static int cmd_name_cmp(const void *elem1, const void *elem2)\n \treturn strcmp(e1->name, e2->name);\n }\n \n-static void print_cmd_by_category(const struct category_description *catdesc)\n+static void print_cmd_by_category(const struct category_description *catdesc,\n+\t\t\t\t int *longest_p)\n {\n \tstruct cmdname_help *cmds;\n \tint longest = 0;\n@@ -124,6 +125,8 @@ static void print_cmd_by_category(const struct category_description *catdesc)\n \t\tprint_command_list(cmds, mask, longest);\n \t}\n \tfree(cmds);\n+\tif (longest_p)\n+\t\t*longest_p = longest;\n }\n \n void add_cmdname(struct cmdnames *cmds, const char *name, int len)\n@@ -193,26 +196,6 @@ void exclude_cmds(struct cmdnames *cmds, struct cmdnames *excludes)\n \tcmds->cnt = cj;\n }\n \n-static void pretty_print_cmdnames(struct cmdnames *cmds, unsigned int colopts)\n-{\n-\tstruct string_list list = STRING_LIST_INIT_NODUP;\n-\tstruct column_options copts;\n-\tint i;\n-\n-\tfor (i = 0; i < cmds->cnt; i++)\n-\t\tstring_list_append(&list, cmds->names[i]->name);\n-\t/*\n-\t * always enable column display, we only consult column.*\n-\t * about layout strategy and stuff\n-\t */\n-\tcolopts = (colopts & ~COL_ENABLE_MASK) | COL_ENABLED;\n-\tmemset(&copts, 0, sizeof(copts));\n-\tcopts.indent = \" \";\n-\tcopts.padding = 2;\n-\tprint_columns(&list, colopts, &copts);\n-\tstring_list_clear(&list, 0);\n-}\n-\n static void list_commands_in_dir(struct cmdnames *cmds,\n \t\t\t\t\t const char *path,\n \t\t\t\t\t const char *prefix)\n@@ -285,29 +268,10 @@ void load_command_list(const char *prefix,\n \texclude_cmds(other_cmds, main_cmds);\n }\n \n-void list_commands(unsigned int colopts,\n-\t\t struct cmdnames *main_cmds, struct cmdnames *other_cmds)\n-{\n-\tif (main_cmds->cnt) {\n-\t\tconst char *exec_path = git_exec_path();\n-\t\tprintf_ln(_(\"available git commands in '%s'\"), exec_path);\n-\t\tputchar('\\n');\n-\t\tpretty_print_cmdnames(main_cmds, colopts);\n-\t\tputchar('\\n');\n-\t}\n-\n-\tif (other_cmds->cnt) {\n-\t\tprintf_ln(_(\"git commands available from elsewhere on your $PATH\"));\n-\t\tputchar('\\n');\n-\t\tpretty_print_cmdnames(other_cmds, colopts);\n-\t\tputchar('\\n');\n-\t}\n-}\n-\n void list_common_cmds_help(void)\n {\n \tputs(_(\"These are common Git commands used in various situations:\"));\n-\tprint_cmd_by_category(common_categories);\n+\tprint_cmd_by_category(common_categories, NULL);\n }\n \n void list_all_main_cmds(struct string_list *list)\n@@ -405,7 +369,7 @@ void list_common_guides_help(void)\n \t\t{ CAT_guide, N_(\"The common Git guides are:\") },\n \t\t{ 0, NULL }\n \t};\n-\tprint_cmd_by_category(catdesc);\n+\tprint_cmd_by_category(catdesc, NULL);\n \tputchar('\\n');\n }\n \n@@ -494,9 +458,48 @@ void list_config_help(int for_human)\n \tstring_list_clear(&keys, 0);\n }\n \n+static int get_alias(const char *var, const char *value, void *data)\n+{\n+\tstruct string_list *list = data;\n+\n+\tif (skip_prefix(var, \"alias.\", &var))\n+\t\tstring_list_append(list, var)->util = xstrdup(value);\n+\n+\treturn 0;\n+}\n+\n void list_all_cmds_help(void)\n {\n-\tprint_cmd_by_category(main_categories);\n+\tstruct string_list others = STRING_LIST_INIT_DUP;\n+\tstruct string_list alias_list = STRING_LIST_INIT_DUP;\n+\tstruct cmdname_help *aliases;\n+\tint i, longest;\n+\n+\tprintf_ln(_(\"See 'git help ' to read about a specific subcommand\"));\n+\tprint_cmd_by_category(main_categories, &longest);\n+\n+\tlist_all_other_cmds(&others);\n+\tif (others.nr)\n+\t\tprintf(\"\\n%s\\n\", _(\"External commands\"));\n+\tfor (i = 0; i < others.nr; i++)\n+\t\tprintf(\" %s\\n\", others.items[i].string);\n+\tstring_list_clear(&others, 0);\n+\n+\tgit_config(get_alias, &alias_list);\n+\tstring_list_sort(&alias_list);\n+\tif (alias_list.nr) {\n+\t\tprintf(\"\\n%s\\n\", _(\"Command aliases\"));\n+\t\tALLOC_ARRAY(aliases, alias_list.nr + 1);\n+\t\tfor (i = 0; i < alias_list.nr; i++) {\n+\t\t\taliases[i].name = alias_list.items[i].string;\n+\t\t\taliases[i].help = alias_list.items[i].util;\n+\t\t\taliases[i].category = 1;\n+\t\t}\n+\t\taliases[alias_list.nr].name = NULL;\n+\t\tprint_command_list(aliases, 1, longest);\n+\t\tfree(aliases);\n+\t}\n+\tstring_list_clear(&alias_list, 1);\n }\n \n int is_in_cmdlist(struct cmdnames *c, const char *s)\ndiff --git a/help.h b/help.h\nindex 9eab6a3f89..105de6195a 100644\n--- a/help.h\n+++ b/help.h\n@@ -37,7 +37,6 @@ extern void add_cmdname(struct cmdnames *cmds, const char *name, int len);\n /* Here we require that excludes is a sorted list. */\n extern void exclude_cmds(struct cmdnames *cmds, struct cmdnames *excludes);\n extern int is_in_cmdlist(struct cmdnames *cmds, const char *name);\n-extern void list_commands(unsigned int colopts, struct cmdnames *main_cmds, struct cmdnames *other_cmds);\n \n /*\n * call this to die(), when it is suspected that the user mistyped a\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bc27df7f38..964615de2f 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -30,8 +30,7 @@ test_expect_success \"setup\" '\n test_expect_success 'basic help commands' '\n \tgit help >/dev/null &&\n \tgit help -a >/dev/null &&\n-\tgit help -g >/dev/null &&\n-\tgit help -av >/dev/null\n+\tgit help -g >/dev/null\n '\n \n test_expect_success \"works for commands and guides by default\" '\n-- 8< --\n\n--\nDuy\n"},{"id":"358870","messageId":"20180925205446.GB21956@sigill.intra.peff.net","threadId":"49404","inReplyTo":"20180925174451.GA29454@duynguyen.home","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-09-25T20:54:47Z","receivedAt":"2018-09-25T20:54:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Sep 25, 2018 at 07:44:51PM +0200, Duy Nguyen wrote:\n\n> > I think adding another section about external commands in \"help -av\"\n> > would address the \"clang-format\" stuff. With that, it's probably good\n> > enough to completely replace \"help -a\". It may also be good to list\n> > aliases there too in a separate section so you have \"all you can type\"\n> > in one (big) list.\n> \n> Here's the patch that adds that external commands and aliases\n> sections. I feel that external commands section is definitely good to\n> have even if we don't replace \"help -a\". Aliases are more\n> subjective...\n\nJust eyeballing the output, it looks pretty reasonable to me. The lack\nof explanation for external commands really stands out, but there's not\nmuch we can do.\n\nThat part of the output is not very compact, and we _could_ put it in\ncolumns, but that might be confusing since the rest of the output is\none-per-line.\n\nMentioning aliases seems reasonable to me. The definitions of some of\nmine are pretty nasty bits of shell, but I guess that people either\ndon't have any ugly aliases, or are comfortable enough with them that\nthey won't be scared away. :)\n\n> -- 8< --\n> @@ -53,7 +52,6 @@ static struct option builtin_help_options[] = {\n> \t\t\tHELP_FORMAT_WEB),\n> \tOPT_SET_INT('i', \"info\", &help_format, N_(\"show info page\"),\n> \t\t\tHELP_FORMAT_INFO),\n> -\tOPT__VERBOSE(&verbose, N_(\"print command description\")),\n> \tOPT_END(),\n> };\n\nWould we want to continue respecting \"-v\" as a noop? I admit I did not\neven know it existed until this thread, but if people have trained\nthemselves to run \"git help -av\", we should probably continue to give\nthem this output.\n\n-Peff\n"},{"id":"358954","messageId":"CACsJy8DCdwAre9dhwwC_5STNq_BuWahv-9Hoim+YUtVssJbzdQ@mail.gmail.com","threadId":"49404","inReplyTo":"20180925205446.GB21956@sigill.intra.peff.net","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-26T16:18:00Z","receivedAt":"2018-09-26T16:18:30Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Sep 25, 2018 at 10:54 PM Jeff King wrote:\n> Mentioning aliases seems reasonable to me. The definitions of some of\n> mine are pretty nasty bits of shell, but I guess that people either\n> don't have any ugly aliases, or are comfortable enough with them that\n> they won't be scared away. :)\n\nI have one with a very long pretty format for git-log. Well, you wrote\nyour aliases you learn to live with them :) We could certainly cut too\nlong aliased commands to keep the listing pretty, but I don't think we\nshould do that until somebody asks for it.\n\n> > -- 8< --\n> > @@ -53,7 +52,6 @@ static struct option builtin_help_options[] = {\n> > HELP_FORMAT_WEB),\n> > OPT_SET_INT('i', \"info\", &help_format, N_(\"show info page\"),\n> > HELP_FORMAT_INFO),\n> > - OPT__VERBOSE(&verbose, N_(\"print command description\")),\n> > OPT_END(),\n> > };\n>\n> Would we want to continue respecting \"-v\" as a noop? I admit I did not\n> even know it existed until this thread, but if people have trained\n> themselves to run \"git help -av\", we should probably continue to give\n> them this output.\n\n-v was recently added just for the new \"help -a\" in May 2018. I think\nit's ok to get rid of it. Memory muscles probably take a couple more\nmonths to kick in.\n-- \nDuy\n"},{"id":"358959","messageId":"xmqqd0t0maqn.fsf@gitster-ct.c.googlers.com","threadId":"49404","inReplyTo":"CACsJy8DCdwAre9dhwwC_5STNq_BuWahv-9Hoim+YUtVssJbzdQ@mail.gmail.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-26T17:25:52Z","receivedAt":"2018-09-26T17:25:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> -v was recently added just for the new \"help -a\" in May 2018. I think\n> it's ok to get rid of it. Memory muscles probably take a couple more\n> months to kick in.\n\nIf it is not hurting, keeping it lets people say \"--no-verbose\" to\nget a less verbose output to help those who do not like the new\ndefault.\n\nUnless you are removing code to show the current \"help -a\" output,\nthat is.\n"},{"id":"358960","messageId":"xmqq8t3omam8.fsf@gitster-ct.c.googlers.com","threadId":"49404","inReplyTo":"20180925174451.GA29454@duynguyen.home","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-26T17:28:31Z","receivedAt":"2018-09-26T17:28:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> Here's the patch that adds that external commands and aliases\n> sections. I feel that external commands section is definitely good to\n> have even if we don't replace \"help -a\". Aliases are more\n> subjective...\n\nI didn't apply this (so I didn't try running it), but a quick\neyeballing tells me that the listing of external commands in -av\noutput done in this patch seems reasonable.\n\nI do not think removing \"-v\" and making the current \"help -a\" output\nunavailable is a wise idea, though.\n"},{"id":"359175","messageId":"20180928023724.GA89283@syl","threadId":"49404","inReplyTo":"xmqq8t3omam8.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2018-09-28T02:37:24Z","receivedAt":"2018-09-28T02:37:29Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Sep 26, 2018 at 10:28:31AM -0700, Junio C Hamano wrote:\n> Duy Nguyen writes:\n>\n> > Here's the patch that adds that external commands and aliases\n> > sections. I feel that external commands section is definitely good to\n> > have even if we don't replace \"help -a\". Aliases are more\n> > subjective...\n>\n> I didn't apply this (so I didn't try running it), but a quick\n> eyeballing tells me that the listing of external commands in -av\n> output done in this patch seems reasonable.\n>\n> I do not think removing \"-v\" and making the current \"help -a\" output\n> unavailable is a wise idea, though.\n\nI think that your point about having to react in a split-second in order\nto ^C before we open the manual page for a command is a good one. So, I\nagree with this.\n\nThanks,\nTaylor\n"},{"id":"359216","messageId":"xmqqefddeg90.fsf@gitster-ct.c.googlers.com","threadId":"49404","inReplyTo":"20180928023724.GA89283@syl","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-28T16:30:51Z","receivedAt":"2018-09-28T16:30:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n> On Wed, Sep 26, 2018 at 10:28:31AM -0700, Junio C Hamano wrote:\n>> Duy Nguyen writes:\n>>\n>> > Here's the patch that adds that external commands and aliases\n>> > sections. I feel that external commands section is definitely good to\n>> > have even if we don't replace \"help -a\". Aliases are more\n>> > subjective...\n>>\n>> I didn't apply this (so I didn't try running it), but a quick\n>> eyeballing tells me that the listing of external commands in -av\n>> output done in this patch seems reasonable.\n>>\n>> I do not think removing \"-v\" and making the current \"help -a\" output\n>> unavailable is a wise idea, though.\n>\n> I think that your point about having to react in a split-second in order\n> to ^C before we open the manual page for a command is a good one. So, I\n> agree with this.\n\nResponding to a wrong thread? \n\nI thought \"now I need ^C within a handful of deciseconds if I want\nonly alias?\" was not about the change to make \"-v\" default when\n\"help -a\" is asked, but about what to do with \"git foo --help\" that\nonly gives \"foo is aliased to ...\".\n"},{"id":"359225","messageId":"20180928174946.GE23652@syl","threadId":"49404","inReplyTo":"xmqqefddeg90.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git help: promote 'git help -av'","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2018-09-28T17:49:46Z","receivedAt":"2018-09-28T17:49:50Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Fri, Sep 28, 2018 at 09:30:51AM -0700, Junio C Hamano wrote:\n> Taylor Blau writes:\n>\n> > On Wed, Sep 26, 2018 at 10:28:31AM -0700, Junio C Hamano wrote:\n> >> Duy Nguyen writes:\n> >>\n> >> > Here's the patch that adds that external commands and aliases\n> >> > sections. I feel that external commands section is definitely good to\n> >> > have even if we don't replace \"help -a\". Aliases are more\n> >> > subjective...\n> >>\n> >> I didn't apply this (so I didn't try running it), but a quick\n> >> eyeballing tells me that the listing of external commands in -av\n> >> output done in this patch seems reasonable.\n> >>\n> >> I do not think removing \"-v\" and making the current \"help -a\" output\n> >> unavailable is a wise idea, though.\n> >\n> > I think that your point about having to react in a split-second in order\n> > to ^C before we open the manual page for a command is a good one. So, I\n> > agree with this.\n>\n> Responding to a wrong thread?\n\nAh, I certainly am. Thanks for catching my mistake :-).\n\n> I thought \"now I need ^C within a handful of deciseconds if I want\n> only alias?\" was not about the change to make \"-v\" default when\n> \"help -a\" is asked, but about what to do with \"git foo --help\" that\n> only gives \"foo is aliased to ...\".\n\nThanks,\nTaylor\n"},{"id":"359269","messageId":"20180929060814.22781-1-pclouds@gmail.com","threadId":"49404","inReplyTo":"20180922174707.16498-1-pclouds@gmail.com","subject":"[PATCH v2] help -a: improve and make --verbose default","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2018-09-29T06:08:14Z","receivedAt":"2018-09-29T06:08:32Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"When you type \"git help\" (or just \"git\") you are greeted with a list\nwith commonly used commands and their short description and are\nsuggested to use \"git help -a\" or \"git help -g\" for more details.\n\n\"git help -av\" would be more friendly and inline with what is shown\nwith \"git help\" since it shows list of commands with description as\nwell, and commands are properly grouped.\n\n\"help -av\" does not show everything \"help -a\" shows though. Add\nexternal command section in \"help -av\" for this. While at there, add a\nsection for aliases as well (until now aliases have no UI, just \"git\nconfig\").\n\nSigned-off-by: Nguyễn Thái Ngọc Duy \n---\n v2 makes 'help -av' default and the user would need to type 'help -a\n --no-verbose' to get the old printout back. 'help -av' also has\n external commands and aliases.\n\n Documentation/git-help.txt | 8 +++---\n builtin/help.c | 2 +-\n help.c | 50 +++++++++++++++++++++++++++++++++++---\n t/t0012-help.sh | 4 +--\n 4 files changed, 54 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 83d25d825a..206e3aef64 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -8,7 +8,7 @@ git-help - Display help information about Git\n SYNOPSIS\n --------\n [verse]\n-'git help' [-a|--all [--verbose]] [-g|--guide]\n+'git help' [-a|--all [--[no-]verbose]] [-g|--guide]\n \t [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]\n \n DESCRIPTION\n@@ -42,8 +42,10 @@ OPTIONS\n --all::\n \tPrints all the available commands on the standard output. This\n \toption overrides any given command or guide name.\n-\tWhen used with `--verbose` print description for all recognized\n-\tcommands.\n+\n+--verbose::\n+\tWhen used with `--all` print description for all recognized\n+\tcommands. This is the default.\n \n -c::\n --config::\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 8d4f6dd301..d83dac2839 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -38,7 +38,7 @@ static const char *html_path;\n static int show_all = 0;\n static int show_guides = 0;\n static int show_config;\n-static int verbose;\n+static int verbose = 1;\n static unsigned int colopts;\n static enum help_format help_format = HELP_FORMAT_NONE;\n static int exclude_guides;\ndiff --git a/help.c b/help.c\nindex 96f6d221ed..4745b32299 100644\n--- a/help.c\n+++ b/help.c\n@@ -98,7 +98,8 @@ static int cmd_name_cmp(const void *elem1, const void *elem2)\n \treturn strcmp(e1->name, e2->name);\n }\n \n-static void print_cmd_by_category(const struct category_description *catdesc)\n+static void print_cmd_by_category(const struct category_description *catdesc,\n+\t\t\t\t int *longest_p)\n {\n \tstruct cmdname_help *cmds;\n \tint longest = 0;\n@@ -124,6 +125,8 @@ static void print_cmd_by_category(const struct category_description *catdesc)\n \t\tprint_command_list(cmds, mask, longest);\n \t}\n \tfree(cmds);\n+\tif (longest_p)\n+\t\t*longest_p = longest;\n }\n \n void add_cmdname(struct cmdnames *cmds, const char *name, int len)\n@@ -307,7 +310,7 @@ void list_commands(unsigned int colopts,\n void list_common_cmds_help(void)\n {\n \tputs(_(\"These are common Git commands used in various situations:\"));\n-\tprint_cmd_by_category(common_categories);\n+\tprint_cmd_by_category(common_categories, NULL);\n }\n \n void list_all_main_cmds(struct string_list *list)\n@@ -405,7 +408,7 @@ void list_common_guides_help(void)\n \t\t{ CAT_guide, N_(\"The common Git guides are:\") },\n \t\t{ 0, NULL }\n \t};\n-\tprint_cmd_by_category(catdesc);\n+\tprint_cmd_by_category(catdesc, NULL);\n \tputchar('\\n');\n }\n \n@@ -494,9 +497,48 @@ void list_config_help(int for_human)\n \tstring_list_clear(&keys, 0);\n }\n \n+static int get_alias(const char *var, const char *value, void *data)\n+{\n+\tstruct string_list *list = data;\n+\n+\tif (skip_prefix(var, \"alias.\", &var))\n+\t\tstring_list_append(list, var)->util = xstrdup(value);\n+\n+\treturn 0;\n+}\n+\n void list_all_cmds_help(void)\n {\n-\tprint_cmd_by_category(main_categories);\n+\tstruct string_list others = STRING_LIST_INIT_DUP;\n+\tstruct string_list alias_list = STRING_LIST_INIT_DUP;\n+\tstruct cmdname_help *aliases;\n+\tint i, longest;\n+\n+\tprintf_ln(_(\"See 'git help ' to read about a specific subcommand\"));\n+\tprint_cmd_by_category(main_categories, &longest);\n+\n+\tlist_all_other_cmds(&others);\n+\tif (others.nr)\n+\t\tprintf(\"\\n%s\\n\", _(\"External commands\"));\n+\tfor (i = 0; i < others.nr; i++)\n+\t\tprintf(\" %s\\n\", others.items[i].string);\n+\tstring_list_clear(&others, 0);\n+\n+\tgit_config(get_alias, &alias_list);\n+\tstring_list_sort(&alias_list);\n+\tif (alias_list.nr) {\n+\t\tprintf(\"\\n%s\\n\", _(\"Command aliases\"));\n+\t\tALLOC_ARRAY(aliases, alias_list.nr + 1);\n+\t\tfor (i = 0; i < alias_list.nr; i++) {\n+\t\t\taliases[i].name = alias_list.items[i].string;\n+\t\t\taliases[i].help = alias_list.items[i].util;\n+\t\t\taliases[i].category = 1;\n+\t\t}\n+\t\taliases[alias_list.nr].name = NULL;\n+\t\tprint_command_list(aliases, 1, longest);\n+\t\tfree(aliases);\n+\t}\n+\tstring_list_clear(&alias_list, 1);\n }\n \n int is_in_cmdlist(struct cmdnames *c, const char *s)\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex bc27df7f38..e8ef7300ec 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -29,9 +29,9 @@ test_expect_success \"setup\" '\n # to verify\n test_expect_success 'basic help commands' '\n \tgit help >/dev/null &&\n-\tgit help -a >/dev/null &&\n+\tgit help -a --no-verbose >/dev/null &&\n \tgit help -g >/dev/null &&\n-\tgit help -av >/dev/null\n+\tgit help -a >/dev/null\n '\n \n test_expect_success \"works for commands and guides by default\" '\n-- \n2.19.0.341.g3acb95d729\n\n"},{"id":"359379","messageId":"20181001181453.GA77583@syl","threadId":"49404","inReplyTo":"20180929060814.22781-1-pclouds@gmail.com","subject":"Re: [PATCH v2] help -a: improve and make --verbose default","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2018-10-01T18:14:53Z","receivedAt":"2018-10-01T18:14:58Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Sat, Sep 29, 2018 at 08:08:14AM +0200, Nguyễn Thái Ngọc Duy wrote:\n> When you type \"git help\" (or just \"git\") you are greeted with a list\n> with commonly used commands and their short description and are\n> suggested to use \"git help -a\" or \"git help -g\" for more details.\n>\n> \"git help -av\" would be more friendly and inline with what is shown\n> with \"git help\" since it shows list of commands with description as\n> well, and commands are properly grouped.\n>\n> \"help -av\" does not show everything \"help -a\" shows though. Add\n> external command section in \"help -av\" for this. While at there, add a\n> section for aliases as well (until now aliases have no UI, just \"git\n> config\").\n>\n> Signed-off-by: Nguyễn Thái Ngọc Duy \n> ---\n> v2 makes 'help -av' default and the user would need to type 'help -a\n> --no-verbose' to get the old printout back. 'help -av' also has\n> external commands and aliases.\n\nThanks. This looks like what I would have expected based on my\nrecollection of the discussion earlier on v1, so this has my:\n\n Reviewed-by: Taylor Blau \n\nThanks,\nTaylor\n"}]}