[PATCH] Group the default git help message by topic

It's difficult to process 21 commands (which is what is output
by default for git when no command is given).  They have been
re-grouped into 4 groups of 5-6 commands each, which is clearer
and easier for new users to process.  More advanced commands
such as bisect and rebase have also been removed as this should
be output for beginners.

Also removes the common-cmd.h generation process, including
parts of the Makefile and the generate-cmdlist.sh file.

Signed-off-by: Scott Chacon <redacted>
---

I sent this over a year ago, during a GitTogether, but I let it drop.
I've been thinking lately that it would be nice if the default Git
help message was a bit clearer for beginners, so I'm going to resubmit
this.  Originally, the discussion descended into what would ultimately
be really nice for a sort of built-in Git tutorial mode, but I think
this should be a good first step to making the help UI a bit
friendlier.

 Makefile            |   13 +++----------
 builtin/help.c      |   40 ++++++++++++++++++++++++++--------------
 generate-cmdlist.sh |   24 ------------------------
 3 files changed, 29 insertions(+), 48 deletions(-)
 delete mode 100755 generate-cmdlist.sh

diff --git a/Makefile b/Makefile
index 07cab8f..c888c77 100644
--- a/Makefile
+++ b/Makefile

@@ -1506,7 +1506,6 @@ shell_compatibility_test:

please_set_SHELL_PATH_to_a_more_modern_shell
 strip: $(PROGRAMS) git$X
       $(STRIP) $(STRIP_OPTS) $(PROGRAMS) git$X

-git.o: common-cmds.h
 git.s git.o: EXTRA_CPPFLAGS = -DGIT_VERSION='"$(GIT_VERSION)"' \
       '-DGIT_HTML_PATH="$(htmldir_SQ)"'

@@ -1514,7 +1513,6 @@ git$X: git.o $(BUILTIN_OBJS) $(GITLIBS)

       $(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ git.o \
               $(BUILTIN_OBJS) $(ALL_LDFLAGS) $(LIBS)

-builtin/help.o: common-cmds.h
 builtin/help.s builtin/help.o: EXTRA_CPPFLAGS = \
       '-DGIT_HTML_PATH="$(htmldir_SQ)"' \
       '-DGIT_MAN_PATH="$(mandir_SQ)"' \

@@ -1526,11 +1524,6 @@ $(BUILT_INS): git$X

       ln -s git$X $@ 2>/dev/null || \
       cp git$X $@

-common-cmds.h: ./generate-cmdlist.sh command-list.txt
-
-common-cmds.h: $(wildcard Documentation/git-*.txt)
-       $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
-
 define cmd_munge_script
 $(RM) $@ $@+ && \
 sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \

@@ -1767,7 +1760,7 @@ else

 # Dependencies on header files, for platforms that do not support
 # the gcc -MMD option.
 #
-# Dependencies on automatically generated headers such as common-cmds.h
+# Dependencies on automatically generated headers
 # should _not_ be included here, since they are necessary even when
 # building an object for the first time.
 #

@@ -1940,7 +1933,7 @@ test-%$X: test-%.o $(GITLIBS)

 check-sha1:: test-sha1$X
       ./test-sha1.sh

-check: common-cmds.h
+check:
       if sparse; \
       then \
               for i in *.c; \

@@ -2105,7 +2098,7 @@ clean:

       $(RM) $(TEST_PROGRAMS)
       $(RM) -r bin-wrappers
       $(RM) -r $(dep_dirs)
-       $(RM) *.spec *.pyc *.pyo */*.pyc */*.pyo common-cmds.h TAGS tags cscope*
+       $(RM) *.spec *.pyc *.pyo */*.pyc */*.pyo TAGS tags cscope*
       $(RM) -r autom4te.cache
       $(RM) config.log config.mak.autogen config.mak.append
config.status config.cache
       $(RM) -r $(GIT_TARNAME) .doc-tmp-dir

diff --git a/builtin/help.c b/builtin/help.c
index 3182a2b..5c25cdc 100644
--- a/builtin/help.c
+++ b/builtin/help.c

@@ -6,7 +6,6 @@

 #include "cache.h"
 #include "builtin.h"
 #include "exec_cmd.h"
-#include "common-cmds.h"
 #include "parse-options.h"
 #include "run-command.h"
 #include "help.h"

@@ -273,19 +272,32 @@ static struct cmdnames main_cmds, other_cmds;

 void list_common_cmds_help(void)
 {
-       int i, longest = 0;
-
-       for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
-               if (longest < strlen(common_cmds[i].name))
-                       longest = strlen(common_cmds[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);
-       }
+  puts("The most commonly used git commands are:\n\
+\n\
+Basic Commands\n\
+  init       Initialize a directory of files to be a new Git repository\n\
+  add        Add new or modified files to the staging area\n\
+  status     Show the working directory and staging area status\n\
+  commit     Record a snapshot of your staged changes to the repository\n\
+\n\
+Branch Commands\n\
+  branch     List, create, and delete development branches\n\
+  checkout   Switch the active branch you are working in\n\
+  merge      Join two or more development histories together\n\
+  tag        Tag a point in your history\n\
+\n\
+History Commands\n\
+  log        Show commit history as a log of changes\n\
+  diff       Show changes between commits, commit and working tree, etc\n\
+  reset      Reset your staging area or working directory to a
specified state\n\
+  show       Show various types of objects\n\
+\n\
+Remote Commands\n\
+  clone      Clone a repository into a new directory\n\
+  remote     List, add and delete aliases for remote repositories\n\
+  fetch      Download new branches and data from a remote repository\n\
+  pull       Fetch from a remote repo and try to merge into the
current branch\n\
+  push       Push your new branches and data to a remote repository");
 }

 static int is_git_command(const char *s)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
deleted file mode 100755
index 75c68d9..0000000
--- a/generate-cmdlist.sh
+++ /dev/null

@@ -1,24 +0,0 @@
-#!/bin/sh
-
-echo "/* Automatically generated by $0 */
-struct cmdname_help
-{
-    char name[16];
-    char help[80];
-};
-
-static struct cmdname_help common_cmds[] = {"
-
-sed -n -e 's/^git-\([^         ]*\)[   ].* common.*/\1/p' command-list.txt |
-sort |
-while read cmd
-do
-     sed -n '
-     /^NAME/,/git-'"$cmd"'/H
-     ${
-            x
-            s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", "\1"},/
-           p
-     }' "Documentation/git-$cmd.txt"
-done
-echo "};"
--

1.7.0.1

On Tue, May 25, 2010 at 10:47:19AM -0700, Scott Chacon wrote:

It's difficult to process 21 commands (which is what is output
by default for git when no command is given).  They have been
re-grouped into 4 groups of 5-6 commands each, which is clearer
and easier for new users to process.  More advanced commands
such as bisect and rebase have also been removed as this should
be output for beginners.

I think this is an improvement, but your patch seems to be whitespace
damaged.

Also removes the common-cmd.h generation process, including
parts of the Makefile and the generate-cmdlist.sh file.

We could always mark the relevant commands in command-list.txt and
auto-generate the structured list. But this list really should not
change much, so I don't know if the extra complexity to do it
automatically is worth it.

-Peff

Scott Chacon [off-list ref] writes:

Also removes the common-cmd.h generation process, including parts of the
Makefile and the generate-cmdlist.sh file.

I think it is a good idea to change the presentation order from
alphabetical to logical grouping.  However, the approach the patch takes
encourages the command synopsis and its help message drift apart which is
somewhat worrysome.

I also sense a hidden agenda of deprecating the word 'index' and replacing
it with 'stage', but this is not a proper way to do so.  Please make it a
separate patch.  IOW, keep the current command description but change the
selection of commands and presentation order in one patch, and create
another patch that does your s/index/stage/ thing.

Thanks.