{"thread":{"id":"11228","subject":"git help -t <topic>: list the help of the commands in a given topic","startedAt":"2007-12-10T15:03:41Z","lastAt":"2007-12-11T09:04:35Z","messageCount":3,"participants":["Santi Béjar","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"62580","messageId":"1197299021-28463-1-git-send-email-sbejar@gmail.com","threadId":"11228","inReplyTo":null,"subject":"git help -t <topic>: list the help of the commands in a given topic","fromName":"Santi Béjar","fromEmail":"sbejar@gmail.com","sentAt":"2007-12-10T15:03:41Z","receivedAt":"2007-12-10T15:03:41Z","isPatch":false,"sender":{"key":"santi@agolina.net","avatar":null},"body":"With 'git help -t' lists the available topics.\n\nShow a hint to get a longer list when listing the common commands.\n\nSigned-off-by: Santi Béjar <sbejar@gmail.com>\n---\n To apply on top of cc/help\n\n Documentation/git-help.txt |   41 +++++++++++++++++++++++++++++-\n command-list.txt           |   12 +++++++++\n generate-cmdlist.sh        |   37 ++++++++++++++++++++++-----\n help.c                     |   59 +++++++++++++++++++++++++++++++++++++------\n 4 files changed, 132 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex ac9e15d..bb010f0 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -7,7 +7,7 @@ git-help - display help information about git\n \n SYNOPSIS\n --------\n-'git help' [-a|--all|-i|--info|-w|--web] [COMMAND]\n+'git help' [-a|--all|-i|--info|-w|--web|-t [topic]] [COMMAND]\n \n DESCRIPTION\n -----------\n@@ -16,6 +16,9 @@ With no options and no COMMAND given, the synopsis of the 'git'\n command and a list of the most commonly used git commands are printed\n on the standard output.\n \n+If the option '-t <topic>' is given, then all the commands on a given\n+topic are printed, and without a <topic> to get a list of topics.\n+\n If the option '--all' or '-a' is given, then all available commands are\n printed on the standard output.\n \n@@ -54,6 +57,42 @@ is available in PATH.\n Note that the script tries, as much as possible, to display the HTML\n page in a new tab on an already opened browser.\n \n+-t <topic>::\n+\tPrints all the commands on a given topic, or all the topics.\n+\n+TOPICS\n+------\n+\n+common::\n+\tThe most commonly used commands.\n+\n+main::\n+\tThe main commands.\n+\n+interrogators::\n+\tThe interrogators commands.\n+\n+manipulators::\n+\tThe manipulators commands.\n+\n+synching::\n+\tThe commands to synchronize repositories.\n+\n+foreignscm::\n+\tThe commands dealing with foreign SCM.\n+\n+plumbinginterrogators::\n+\tThe low-level interrogators commands.\n+\n+plumbingmanipulators::\n+\tThe low-level manipulators commands.\n+\n+purehelpers::\n+\tThe helpers commands.\n+\n+synchelpers::\n+\tThe helpers commands to synchronize repositories.\n+\n Author\n ------\n Written by Junio C Hamano <gitster@pobox.com> and the git-list\ndiff --git a/command-list.txt b/command-list.txt\nindex 28342da..cbfb3d2 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -128,3 +128,15 @@ git-verify-pack                         plumbinginterrogators\n git-verify-tag                          ancillaryinterrogators\n git-whatchanged                         ancillaryinterrogators\n git-write-tree                          plumbingmanipulators\n+# List of known git topics.\n+# topic name\t\t\t\tcategory [common]\n+topic-common                            mainporcelain common\n+topic-main                              mainporcelain\n+topic-interrogators                     ancillaryinterrogators\n+topic-manipulators                      ancillarymanipulators\n+topic-synching                          synchingrepositories\n+topic-foreignscm                        foreignscminterface\n+topic-plumbinginterrogators             plumbinginterrogators\n+topic-plumbingmanipulators              plumbingmanipulators\n+topic-purehelpers                       purehelpers\n+topic-synchelpers                       synchelpers\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\nindex a2913c2..9371e9d 100755\n--- a/generate-cmdlist.sh\n+++ b/generate-cmdlist.sh\n@@ -1,24 +1,47 @@\n #!/bin/sh\n \n echo \"/* Automatically generated by $0 */\n+#define COMMON\t(1<<1)\n+\n struct cmdname_help\n {\n-    char name[16];\n+    char name[23];\n     char help[80];\n+    char category[22];\n+    int option;\n };\n \n-static struct cmdname_help common_cmds[] = {\"\n+static struct cmdname_help cmd_list[] = {\"\n \n-sed -n -e 's/^git-\\([^ \t]*\\)[ \t].* common.*/\\1/p' command-list.txt |\n-sort |\n-while read cmd\n+sed -n -e 's/^git-\\([^ \t]*\\)\\(.*\\)$/\\1\\2/p' command-list.txt |\n+grep -v deprecated | sort |\n+while read cmd topic flag\n do\n+     flag=$(echo $flag | tr '[a-z]' '[A-Z]')\n+     [ -z \"$flag\" ] && flag=\"0\"\n      sed -n '\n-     /NAME/,/git-'\"$cmd\"'/H\n+     /^NAME$/,/git-'\"$cmd\"'/H\n      ${\n             x\n-            s/.*git-'\"$cmd\"' - \\(.*\\)/  {\"'\"$cmd\"'\", \"\\1\"},/\n+            s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", \"\\1\",/\n \t    p\n      }' \"Documentation/git-$cmd.txt\"\n+     echo  \"\\\"$topic\\\", $flag },\"\n+done\n+echo \"};\"\n+\n+echo \"static struct cmdname_help topic_list[] = {\"\n+sed -n -e 's/^topic-\\([^ \t]*\\)\\(.*\\)$/\\1\\2/p' command-list.txt |\n+while read topic category flag\n+do\n+     flag=$(echo $flag | tr '[a-z]' '[A-Z]')\n+     [ -z \"$flag\" ] && flag=\"0\"\n+     sed -n '\n+     /^'$topic'::$/{\n+\t\tn\n+\t\ts/^[ \t]*\\(.*\\)./  {\"'\"$topic\"'\", \"\\1\",/\n+\t\tp\n+     }' \"Documentation/git-help.txt\"\n+     echo  \"\\\"$category\\\", $flag },\"\n done\n echo \"};\"\ndiff --git a/help.c b/help.c\nindex c96b167..4249d2a 100644\n--- a/help.c\n+++ b/help.c\n@@ -222,20 +222,54 @@ static void list_commands(void)\n \t}\n }\n \n+void list_cmds_help(const char *topic)\n+{\n+\tint i, longest = 0, option = 0;\n+\tconst char *category = topic;\n+\n+\tfor (i = 0; i < ARRAY_SIZE(topic_list); i++) {\n+\t\tif (!strcmp(topic_list[i].name, topic)) {\n+\t\t\tcategory = topic_list[i].category;\n+\t\t\toption = topic_list[i].option;\n+\t\t\tprintf(\"%s:\\n\",topic_list[i].help);\n+\t\t}\n+\t}\n+\n+\tfor (i = 0; i < ARRAY_SIZE(cmd_list); i++) {\n+\t\tif (strcmp(cmd_list[i].category, category)) continue;\n+\t\tif (longest < strlen(cmd_list[i].name))\n+\t\t\tlongest = strlen(cmd_list[i].name);\n+\t}\n+\n+\tfor (i = 0; i < ARRAY_SIZE(cmd_list); i++) {\n+\t\tif (strcmp(cmd_list[i].category, category)) continue;\n+\t\tif ((option == 0) || (cmd_list[i].option & option)){\n+\t\t\tprintf(\"   %s   \", cmd_list[i].name);\n+\t\t\tmput_char(' ', longest - strlen(cmd_list[i].name));\n+\t\t\tputs(cmd_list[i].help);\n+\t\t}\n+\t}\n+}\n+\n void list_common_cmds_help(void)\n {\n-\tint i, longest = 0;\n+\tlist_cmds_help(\"common\");\n+\tputs(\"(use 'git help -t main' to get a longer list)\");\n+}\n \n-\tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-\t\tif (longest < strlen(common_cmds[i].name))\n-\t\t\tlongest = strlen(common_cmds[i].name);\n+void list_topics_help()\n+{\n+\tprintf(\"The topics:\\n\");\n+\tint i, longest = 0;\n+\tfor (i = 0; i < ARRAY_SIZE(topic_list); i++) {\n+\t\tif (longest < strlen(topic_list[i].name))\n+\t\t\tlongest = strlen(topic_list[i].name);\n \t}\n \n-\tputs(\"The most commonly used git commands are:\");\n-\tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-\t\tprintf(\"   %s   \", common_cmds[i].name);\n-\t\tmput_char(' ', longest - strlen(common_cmds[i].name));\n-\t\tputs(common_cmds[i].help);\n+\tfor (i = 0; i < ARRAY_SIZE(topic_list); i++) {\n+\t\tprintf(\"   %s   \", topic_list[i].name);\n+\t\tmput_char(' ', longest - strlen(topic_list[i].name));\n+\t\tputs(topic_list[i].help);\n \t}\n }\n \n@@ -331,6 +365,13 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\tshow_info_page(argc > 2 ? argv[2] : NULL);\n \t}\n \n+\telse if (!strcmp(help_cmd, \"-t\")) {\n+\t\tconst char *topic = NULL;\n+\t\ttopic = argc > 2 ? argv[2] : NULL;\n+\t\tif (!topic) list_topics_help();\n+\t\telse list_cmds_help(topic);\n+\t}\n+\n \telse\n \t\tshow_man_page(help_cmd);\n \n-- \n1.5.3.7.2094.gff6c\n"},{"id":"62634","messageId":"7v7ijmjayl.fsf@gitster.siamese.dyndns.org","threadId":"11228","inReplyTo":"1197299021-28463-1-git-send-email-sbejar@gmail.com","subject":"Re: git help -t <topic>: list the help of the commands in a given topic","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-12-11T01:07:14Z","receivedAt":"2007-12-11T01:07:14Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Santi Béjar <sbejar@gmail.com> writes:\n\n> With 'git help -t' lists the available topics.\n>\n> Show a hint to get a longer list when listing the common commands.\n\nI like the idea of making the categorized command list in git(7)\navailable, and agree with you that renaming common_cmds[] to cmd_list[]\nand place everything in there would be the way to go.\n\nHowever, I doubt about your presentation.  Who are the intended\naudience and what is the expected way this is used?\n\nI highly suspect that it would be much easier to use if you add a mode\nto \"git help\" that runs the pager over the categoized command list part\nof git(7) manual page, without taking \"show me list of topics\" nor \"show\ncommands only in this topic\" parameters.  It is highly unlikely that a\nuser knows which category an obscure command whose name he wants to\nrecall is in, or can guess which category it would be classified in\nafter seeing the \"category list\".  It would be much more likely that he\nfinds it easier to scan (perhaps with \"/<string>\") the command list with\none line description in the pager.\n"},{"id":"62688","messageId":"8aa486160712110104v6d12985dq45739ff2fc4cc39@mail.gmail.com","threadId":"11228","inReplyTo":"7v7ijmjayl.fsf@gitster.siamese.dyndns.org","subject":"Re: git help -t <topic>: list the help of the commands in a given topic","fromName":"Santi Béjar","fromEmail":"sbejar@gmail.com","sentAt":"2007-12-11T09:04:35Z","receivedAt":"2007-12-11T09:04:35Z","isPatch":false,"sender":{"key":"santi@agolina.net","avatar":null},"body":"On Dec 11, 2007 2:07 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> Santi Béjar <sbejar@gmail.com> writes:\n>\n> > With 'git help -t' lists the available topics.\n> >\n> > Show a hint to get a longer list when listing the common commands.\n>\n> I like the idea of making the categorized command list in git(7)\n> available, and agree with you that renaming common_cmds[] to cmd_list[]\n> and place everything in there would be the way to go.\n>\n> However, I doubt about your presentation.  Who are the intended\n> audience and what is the expected way this is used?\n\nThe main reason for this was to be able to show a longer list in git\nhelp. But at the end I did this topic thing. The intented audience was\nthe newbies looking at the \"git help\" output, for them to have a\nlonger list. Then the topic part was intended for intermidiate user\nlooking for even more powerfull commands.\n\n>\n> I highly suspect that it would be much easier to use if you add a mode\n> to \"git help\" that runs the pager over the categoized command list part\n> of git(7) manual page, without taking \"show me list of topics\" nor \"show\n> commands only in this topic\" parameters.  It is highly unlikely that a\n> user knows which category an obscure command whose name he wants to\n> recall is in, or can guess which category it would be classified in\n> after seeing the \"category list\".  It would be much more likely that he\n> finds it easier to scan (perhaps with \"/<string>\") the command list with\n> one line description in the pager.\n\nOK, this makes sense. But I still think that having a longer list in\n\"git help -l?\" with the main porcelain commands makes sense. I'll try\nto do it.\n\nBest regards,\n\nSanti\n>\n"}]}