git help -t <topic>: list the help of the commands in a given topic

git help -t <topic>: list the help of the commands in a given topic

[Santi Béjar]

With 'git help -t' lists the available topics.

Show a hint to get a longer list when listing the common commands.

Signed-off-by: Santi Béjar <sbejar@gmail.com>
---
 To apply on top of cc/help

 Documentation/git-help.txt |   41 +++++++++++++++++++++++++++++-
 command-list.txt           |   12 +++++++++
 generate-cmdlist.sh        |   37 ++++++++++++++++++++++-----
 help.c                     |   59 +++++++++++++++++++++++++++++++++++++------
 4 files changed, 132 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index ac9e15d..bb010f0 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -7,7 +7,7 @@ git-help - display help information about git
 
 SYNOPSIS
 --------
-'git help' [-a|--all|-i|--info|-w|--web] [COMMAND]
+'git help' [-a|--all|-i|--info|-w|--web|-t [topic]] [COMMAND]
 
 DESCRIPTION
 -----------
@@ -16,6 +16,9 @@ With no options and no COMMAND given, the synopsis of the 'git'
 command and a list of the most commonly used git commands are printed
 on the standard output.
 
+If the option '-t <topic>' is given, then all the commands on a given
+topic are printed, and without a <topic> to get a list of topics.
+
 If the option '--all' or '-a' is given, then all available commands are
 printed on the standard output.
 
@@ -54,6 +57,42 @@ is available in PATH.
 Note that the script tries, as much as possible, to display the HTML
 page in a new tab on an already opened browser.
 
+-t <topic>::
+	Prints all the commands on a given topic, or all the topics.
+
+TOPICS
+------
+
+common::
+	The most commonly used commands.
+
+main::
+	The main commands.
+
+interrogators::
+	The interrogators commands.
+
+manipulators::
+	The manipulators commands.
+
+synching::
+	The commands to synchronize repositories.
+
+foreignscm::
+	The commands dealing with foreign SCM.
+
+plumbinginterrogators::
+	The low-level interrogators commands.
+
+plumbingmanipulators::
+	The low-level manipulators commands.
+
+purehelpers::
+	The helpers commands.
+
+synchelpers::
+	The helpers commands to synchronize repositories.
+
 Author
 ------
 Written by Junio C Hamano <gitster@pobox.com> and the git-list
diff --git a/command-list.txt b/command-list.txt
index 28342da..cbfb3d2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -128,3 +128,15 @@ git-verify-pack                         plumbinginterrogators
 git-verify-tag                          ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators
 git-write-tree                          plumbingmanipulators
+# List of known git topics.
+# topic name				category [common]
+topic-common                            mainporcelain common
+topic-main                              mainporcelain
+topic-interrogators                     ancillaryinterrogators
+topic-manipulators                      ancillarymanipulators
+topic-synching                          synchingrepositories
+topic-foreignscm                        foreignscminterface
+topic-plumbinginterrogators             plumbinginterrogators
+topic-plumbingmanipulators              plumbingmanipulators
+topic-purehelpers                       purehelpers
+topic-synchelpers                       synchelpers
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index a2913c2..9371e9d 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -1,24 +1,47 @@
 #!/bin/sh
 
 echo "/* Automatically generated by $0 */
+#define COMMON	(1<<1)
+
 struct cmdname_help
 {
-    char name[16];
+    char name[23];
     char help[80];
+    char category[22];
+    int option;
 };
 
-static struct cmdname_help common_cmds[] = {"
+static struct cmdname_help cmd_list[] = {"
 
-sed -n -e 's/^git-\([^ 	]*\)[ 	].* common.*/\1/p' command-list.txt |
-sort |
-while read cmd
+sed -n -e 's/^git-\([^ 	]*\)\(.*\)$/\1\2/p' command-list.txt |
+grep -v deprecated | sort |
+while read cmd topic flag
 do
+     flag=$(echo $flag | tr '[a-z]' '[A-Z]')
+     [ -z "$flag" ] && flag="0"
      sed -n '
-     /NAME/,/git-'"$cmd"'/H
+     /^NAME$/,/git-'"$cmd"'/H
      ${
             x
-            s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", "\1"},/
+            s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", "\1",/
 	    p
      }' "Documentation/git-$cmd.txt"
+     echo  "\"$topic\", $flag },"
+done
+echo "};"
+
+echo "static struct cmdname_help topic_list[] = {"
+sed -n -e 's/^topic-\([^ 	]*\)\(.*\)$/\1\2/p' command-list.txt |
+while read topic category flag
+do
+     flag=$(echo $flag | tr '[a-z]' '[A-Z]')
+     [ -z "$flag" ] && flag="0"
+     sed -n '
+     /^'$topic'::$/{
+		n
+		s/^[ 	]*\(.*\)./  {"'"$topic"'", "\1",/
+		p
+     }' "Documentation/git-help.txt"
+     echo  "\"$category\", $flag },"
 done
 echo "};"
diff --git a/help.c b/help.c
index c96b167..4249d2a 100644
--- a/help.c
+++ b/help.c
@@ -222,20 +222,54 @@ static void list_commands(void)
 	}
 }
 
+void list_cmds_help(const char *topic)
+{
+	int i, longest = 0, option = 0;
+	const char *category = topic;
+
+	for (i = 0; i < ARRAY_SIZE(topic_list); i++) {
+		if (!strcmp(topic_list[i].name, topic)) {
+			category = topic_list[i].category;
+			option = topic_list[i].option;
+			printf("%s:\n",topic_list[i].help);
+		}
+	}
+
+	for (i = 0; i < ARRAY_SIZE(cmd_list); i++) {
+		if (strcmp(cmd_list[i].category, category)) continue;
+		if (longest < strlen(cmd_list[i].name))
+			longest = strlen(cmd_list[i].name);
+	}
+
+	for (i = 0; i < ARRAY_SIZE(cmd_list); i++) {
+		if (strcmp(cmd_list[i].category, category)) continue;
+		if ((option == 0) || (cmd_list[i].option & option)){
+			printf("   %s   ", cmd_list[i].name);
+			mput_char(' ', longest - strlen(cmd_list[i].name));
+			puts(cmd_list[i].help);
+		}
+	}
+}
+
 void list_common_cmds_help(void)
 {
-	int i, longest = 0;
+	list_cmds_help("common");
+	puts("(use 'git help -t main' to get a longer list)");
+}
 
-	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
-		if (longest < strlen(common_cmds[i].name))
-			longest = strlen(common_cmds[i].name);
+void list_topics_help()
+{
+	printf("The topics:\n");
+	int i, longest = 0;
+	for (i = 0; i < ARRAY_SIZE(topic_list); i++) {
+		if (longest < strlen(topic_list[i].name))
+			longest = strlen(topic_list[i].name);
 	}
 
-	puts("The most commonly used git commands are:");
-	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
-		printf("   %s   ", common_cmds[i].name);
-		mput_char(' ', longest - strlen(common_cmds[i].name));
-		puts(common_cmds[i].help);
+	for (i = 0; i < ARRAY_SIZE(topic_list); i++) {
+		printf("   %s   ", topic_list[i].name);
+		mput_char(' ', longest - strlen(topic_list[i].name));
+		puts(topic_list[i].help);
 	}
 }
 
@@ -331,6 +365,13 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		show_info_page(argc > 2 ? argv[2] : NULL);
 	}
 
+	else if (!strcmp(help_cmd, "-t")) {
+		const char *topic = NULL;
+		topic = argc > 2 ? argv[2] : NULL;
+		if (!topic) list_topics_help();
+		else list_cmds_help(topic);
+	}
+
 	else
 		show_man_page(help_cmd);
 
-- 
1.5.3.7.2094.gff6c

Re: git help -t <topic>: list the help of the commands in a given topic

[Junio C Hamano]

Santi Béjar <sbejar@gmail.com> writes:

> With 'git help -t' lists the available topics.
>
> Show a hint to get a longer list when listing the common commands.

I like the idea of making the categorized command list in git(7)
available, and agree with you that renaming common_cmds[] to cmd_list[]
and place everything in there would be the way to go.

However, I doubt about your presentation.  Who are the intended
audience and what is the expected way this is used?

I highly suspect that it would be much easier to use if you add a mode
to "git help" that runs the pager over the categoized command list part
of git(7) manual page, without taking "show me list of topics" nor "show
commands only in this topic" parameters.  It is highly unlikely that a
user knows which category an obscure command whose name he wants to
recall is in, or can guess which category it would be classified in
after seeing the "category list".  It would be much more likely that he
finds it easier to scan (perhaps with "/<string>") the command list with
one line description in the pager.

Re: git help -t <topic>: list the help of the commands in a given topic

[Santi Béjar]

On Dec 11, 2007 2:07 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Santi Béjar <sbejar@gmail.com> writes:
>
> > With 'git help -t' lists the available topics.
> >
> > Show a hint to get a longer list when listing the common commands.
>
> I like the idea of making the categorized command list in git(7)
> available, and agree with you that renaming common_cmds[] to cmd_list[]
> and place everything in there would be the way to go.
>
> However, I doubt about your presentation.  Who are the intended
> audience and what is the expected way this is used?

The main reason for this was to be able to show a longer list in git
help. But at the end I did this topic thing. The intented audience was
the newbies looking at the "git help" output, for them to have a
longer list. Then the topic part was intended for intermidiate user
looking for even more powerfull commands.

>
> I highly suspect that it would be much easier to use if you add a mode
> to "git help" that runs the pager over the categoized command list part
> of git(7) manual page, without taking "show me list of topics" nor "show
> commands only in this topic" parameters.  It is highly unlikely that a
> user knows which category an obscure command whose name he wants to
> recall is in, or can guess which category it would be classified in
> after seeing the "category list".  It would be much more likely that he
> finds it easier to scan (perhaps with "/<string>") the command list with
> one line description in the pager.

OK, this makes sense. But I still think that having a longer list in
"git help -l?" with the main porcelain commands makes sense. I'll try
to do it.

Best regards,

Santi
>