{"thread":{"id":"23903","subject":"[PATCH] Group the default git help message by topic","startedAt":"2010-05-25T17:47:19Z","lastAt":"2010-06-02T23:39:39Z","messageCount":3,"participants":["Scott Chacon","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"142289","messageId":"AANLkTilWIRqnjjgGA3e9DDzw2MiHirjP2-W7PuPhonUs@mail.gmail.com","threadId":"23903","inReplyTo":"1274809430-36060-1-git-send-email-schacon@gmail.com","subject":"[PATCH] Group the default git help message by topic","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2010-05-25T17:47:19Z","receivedAt":"2010-05-25T17:47:19Z","isPatch":true,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"It's difficult to process 21 commands (which is what is output\nby default for git when no command is given).  They have been\nre-grouped into 4 groups of 5-6 commands each, which is clearer\nand easier for new users to process.  More advanced commands\nsuch as bisect and rebase have also been removed as this should\nbe output for beginners.\n\nAlso removes the common-cmd.h generation process, including\nparts of the Makefile and the generate-cmdlist.sh file.\n\nSigned-off-by: Scott Chacon <schacon@gmail.com>\n---\n\nI sent this over a year ago, during a GitTogether, but I let it drop.\nI've been thinking lately that it would be nice if the default Git\nhelp message was a bit clearer for beginners, so I'm going to resubmit\nthis.  Originally, the discussion descended into what would ultimately\nbe really nice for a sort of built-in Git tutorial mode, but I think\nthis should be a good first step to making the help UI a bit\nfriendlier.\n\n Makefile            |   13 +++----------\n builtin/help.c      |   40 ++++++++++++++++++++++++++--------------\n generate-cmdlist.sh |   24 ------------------------\n 3 files changed, 29 insertions(+), 48 deletions(-)\n delete mode 100755 generate-cmdlist.sh\n\ndiff --git a/Makefile b/Makefile\nindex 07cab8f..c888c77 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1506,7 +1506,6 @@ shell_compatibility_test:\nplease_set_SHELL_PATH_to_a_more_modern_shell\n strip: $(PROGRAMS) git$X\n       $(STRIP) $(STRIP_OPTS) $(PROGRAMS) git$X\n\n-git.o: common-cmds.h\n git.s git.o: EXTRA_CPPFLAGS = -DGIT_VERSION='\"$(GIT_VERSION)\"' \\\n       '-DGIT_HTML_PATH=\"$(htmldir_SQ)\"'\n\n@@ -1514,7 +1513,6 @@ git$X: git.o $(BUILTIN_OBJS) $(GITLIBS)\n       $(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ git.o \\\n               $(BUILTIN_OBJS) $(ALL_LDFLAGS) $(LIBS)\n\n-builtin/help.o: common-cmds.h\n builtin/help.s builtin/help.o: EXTRA_CPPFLAGS = \\\n       '-DGIT_HTML_PATH=\"$(htmldir_SQ)\"' \\\n       '-DGIT_MAN_PATH=\"$(mandir_SQ)\"' \\\n@@ -1526,11 +1524,6 @@ $(BUILT_INS): git$X\n       ln -s git$X $@ 2>/dev/null || \\\n       cp git$X $@\n\n-common-cmds.h: ./generate-cmdlist.sh command-list.txt\n-\n-common-cmds.h: $(wildcard Documentation/git-*.txt)\n-       $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n-\n define cmd_munge_script\n $(RM) $@ $@+ && \\\n sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \\\n@@ -1767,7 +1760,7 @@ else\n # Dependencies on header files, for platforms that do not support\n # the gcc -MMD option.\n #\n-# Dependencies on automatically generated headers such as common-cmds.h\n+# Dependencies on automatically generated headers\n # should _not_ be included here, since they are necessary even when\n # building an object for the first time.\n #\n@@ -1940,7 +1933,7 @@ test-%$X: test-%.o $(GITLIBS)\n check-sha1:: test-sha1$X\n       ./test-sha1.sh\n\n-check: common-cmds.h\n+check:\n       if sparse; \\\n       then \\\n               for i in *.c; \\\n@@ -2105,7 +2098,7 @@ clean:\n       $(RM) $(TEST_PROGRAMS)\n       $(RM) -r bin-wrappers\n       $(RM) -r $(dep_dirs)\n-       $(RM) *.spec *.pyc *.pyo */*.pyc */*.pyo common-cmds.h TAGS tags cscope*\n+       $(RM) *.spec *.pyc *.pyo */*.pyc */*.pyo TAGS tags cscope*\n       $(RM) -r autom4te.cache\n       $(RM) config.log config.mak.autogen config.mak.append\nconfig.status config.cache\n       $(RM) -r $(GIT_TARNAME) .doc-tmp-dir\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 3182a2b..5c25cdc 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -6,7 +6,6 @@\n #include \"cache.h\"\n #include \"builtin.h\"\n #include \"exec_cmd.h\"\n-#include \"common-cmds.h\"\n #include \"parse-options.h\"\n #include \"run-command.h\"\n #include \"help.h\"\n@@ -273,19 +272,32 @@ static struct cmdnames main_cmds, other_cmds;\n\n void list_common_cmds_help(void)\n {\n-       int i, longest = 0;\n-\n-       for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-               if (longest < strlen(common_cmds[i].name))\n-                       longest = strlen(common_cmds[i].name);\n-       }\n-\n-       puts(\"The most commonly used git commands are:\");\n-       for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-               printf(\"   %s   \", common_cmds[i].name);\n-               mput_char(' ', longest - strlen(common_cmds[i].name));\n-               puts(common_cmds[i].help);\n-       }\n+  puts(\"The most commonly used git commands are:\\n\\\n+\\n\\\n+Basic Commands\\n\\\n+  init       Initialize a directory of files to be a new Git repository\\n\\\n+  add        Add new or modified files to the staging area\\n\\\n+  status     Show the working directory and staging area status\\n\\\n+  commit     Record a snapshot of your staged changes to the repository\\n\\\n+\\n\\\n+Branch Commands\\n\\\n+  branch     List, create, and delete development branches\\n\\\n+  checkout   Switch the active branch you are working in\\n\\\n+  merge      Join two or more development histories together\\n\\\n+  tag        Tag a point in your history\\n\\\n+\\n\\\n+History Commands\\n\\\n+  log        Show commit history as a log of changes\\n\\\n+  diff       Show changes between commits, commit and working tree, etc\\n\\\n+  reset      Reset your staging area or working directory to a\nspecified state\\n\\\n+  show       Show various types of objects\\n\\\n+\\n\\\n+Remote Commands\\n\\\n+  clone      Clone a repository into a new directory\\n\\\n+  remote     List, add and delete aliases for remote repositories\\n\\\n+  fetch      Download new branches and data from a remote repository\\n\\\n+  pull       Fetch from a remote repo and try to merge into the\ncurrent branch\\n\\\n+  push       Push your new branches and data to a remote repository\");\n }\n\n static int is_git_command(const char *s)\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\ndeleted file mode 100755\nindex 75c68d9..0000000\n--- a/generate-cmdlist.sh\n+++ /dev/null\n@@ -1,24 +0,0 @@\n-#!/bin/sh\n-\n-echo \"/* Automatically generated by $0 */\n-struct cmdname_help\n-{\n-    char name[16];\n-    char help[80];\n-};\n-\n-static struct cmdname_help common_cmds[] = {\"\n-\n-sed -n -e 's/^git-\\([^         ]*\\)[   ].* common.*/\\1/p' command-list.txt |\n-sort |\n-while read cmd\n-do\n-     sed -n '\n-     /^NAME/,/git-'\"$cmd\"'/H\n-     ${\n-            x\n-            s/.*git-'\"$cmd\"' - \\(.*\\)/  {\"'\"$cmd\"'\", \"\\1\"},/\n-           p\n-     }' \"Documentation/git-$cmd.txt\"\n-done\n-echo \"};\"\n--\n1.7.0.1\n"},{"id":"142552","messageId":"20100530053646.GB19219@coredump.intra.peff.net","threadId":"23903","inReplyTo":"AANLkTilWIRqnjjgGA3e9DDzw2MiHirjP2-W7PuPhonUs@mail.gmail.com","subject":"Re: [PATCH] Group the default git help message by topic","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-30T05:36:46Z","receivedAt":"2010-05-30T05:36:46Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 25, 2010 at 10:47:19AM -0700, Scott Chacon wrote:\n\n> It's difficult to process 21 commands (which is what is output\n> by default for git when no command is given).  They have been\n> re-grouped into 4 groups of 5-6 commands each, which is clearer\n> and easier for new users to process.  More advanced commands\n> such as bisect and rebase have also been removed as this should\n> be output for beginners.\n\nI think this is an improvement, but your patch seems to be whitespace\ndamaged.\n\n> Also removes the common-cmd.h generation process, including\n> parts of the Makefile and the generate-cmdlist.sh file.\n\nWe could always mark the relevant commands in command-list.txt and\nauto-generate the structured list. But this list really should not\nchange much, so I don't know if the extra complexity to do it\nautomatically is worth it.\n\n-Peff\n"},{"id":"142852","messageId":"7vwruh80n8.fsf@alter.siamese.dyndns.org","threadId":"23903","inReplyTo":"AANLkTilWIRqnjjgGA3e9DDzw2MiHirjP2-W7PuPhonUs@mail.gmail.com","subject":"Re: [PATCH] Group the default git help message by topic","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-02T23:39:39Z","receivedAt":"2010-06-02T23:39:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Scott Chacon <schacon@gmail.com> writes:\n\n> Also removes the common-cmd.h generation process, including parts of the\n> Makefile and the generate-cmdlist.sh file.\n\nI think it is a good idea to change the presentation order from\nalphabetical to logical grouping.  However, the approach the patch takes\nencourages the command synopsis and its help message drift apart which is\nsomewhat worrysome.\n\nI also sense a hidden agenda of deprecating the word 'index' and replacing\nit with 'stage', but this is not a proper way to do so.  Please make it a\nseparate patch.  IOW, keep the current command description but change the\nselection of commands and presentation order in one patch, and create\nanother patch that does your s/index/stage/ thing.\n\nThanks.\n"}]}