{"thread":{"id":"39284","subject":"[PATCH v5 0/6] git help: group common commands by theme","startedAt":"2015-05-09T17:17:30Z","lastAt":"2015-05-11T06:59:21Z","messageCount":14,"participants":["Sébastien Guimmara","Eric Sunshine"],"isPatch":true,"patchVersion":5,"patchTotal":6},"messages":[{"id":"260896","messageId":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":null,"subject":"[PATCH v5 0/6] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:30Z","receivedAt":"2015-05-09T17:17:30Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"This v5 includes suggestions from Junio C Hamano, Eric Sunshine and \nEmma Jane Hogbin Westby, as well as a complete and much cleaner rewrite \nof the generate-cmdlist parser in awk by Eric Sunshine.\n\nThe main idea of this version is to go a little further in the idea of\nmaking 'git help' a warmer welcome to the unfamiliar user, by a gentle\nsummary of the typical Git workflow. Instead of simply telling what\nthe Git common commands are, we rather explain how they fit in the\ntypical workflow, ordered in (chrono)logical order:\n\n1. I setup my repo (init)\n2. I work on changes (worktree)\n3. I gather information on the history (info)\n4. I grow, tweak and clean my local history (history)\n5. To finally share my nice contribution with the world (remote)\n\nSébastien Guimmara (6):\n  generate-cmdlist: parse common group commands\n  help.c: output the typical Git workflow\n  command-list.txt: group common commands by theme\n  Makefile: update to new command-list.txt format\n  new-command.txt: mention the common command groups\n  cmd-list.perl: ignore all lines until [commands]\n\n Documentation/cmd-list.perl         |  8 +++++-\n Documentation/howto/new-command.txt |  4 ++-\n Makefile                            |  8 +++---\n command-list.txt                    | 56 ++++++++++++++++++++++---------------\n generate-cmdlist.awk                | 38 +++++++++++++++++++++++++\n help.c                              | 25 +++++++++++++++--\n 6 files changed, 109 insertions(+), 30 deletions(-)\n create mode 100644 generate-cmdlist.awk\n\n-- \n2.4.0\n"},{"id":"260897","messageId":"1431191856-10949-2-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 1/6] generate-cmdlist: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:31Z","receivedAt":"2015-05-09T17:17:31Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Parse the [common] block to create the array of group descriptions:\n\nstatic char *common_cmd_groups[] = {\n    N_(\"start a working area (see also: git help tutorial)\"),\n    N_(\"work on the current change (see also: git help everyday)\"),\n    N_(\"examine the history and state (see also: git help revisions)\"),\n    N_(\"grow, mark and tweak your history\"),\n    N_(\"collaborate (see also: git help workflows)\"),\n};\n\nthen map each element of common_cmds[] to a group via its index:\n\nstatic struct cmdname_help common_cmds[] = {\n    {\"add\", N_(\"Add file contents to the index\"), 1},\n    {\"branch\", N_(\"List, create, or delete branches\"), 4},\n    {\"checkout\", N_(\"Checkout a branch or paths to the ...\"), 4},\n    {\"clone\", N_(\"Clone a repository into a new directory\"), 0},\n    {\"commit\", N_(\"Record changes to the repository\"), 4},\n    ...\n};\n\nso that 'git help' can print those commands grouped by theme.\n\nOnly commands tagged with an attribute from [common] are emitted to\ncommon_cmds[].\n\n[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]\n\nSigned-off-by: Eric Sunshine <sunshine@sunshineco.com>\n---\n generate-cmdlist.awk | 38 ++++++++++++++++++++++++++++++++++++++\n 1 file changed, 38 insertions(+)\n create mode 100644 generate-cmdlist.awk\n\ndiff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\nnew file mode 100644\nindex 0000000..cbaac88\n--- /dev/null\n+++ b/generate-cmdlist.awk\n@@ -0,0 +1,38 @@\n+BEGIN {\n+\tprint \"/* Automatically generated by generate-cmdlist.awk */\\n\"\n+\tprint \"struct cmdname_help {\"\n+\tprint \"\\tchar name[16];\"\n+\tprint \"\\tchar help[80];\"\n+\tprint \"\\tunsigned char group;\"\n+\tprint \"};\\n\"\n+\tprint \"static char *common_cmd_groups[] = {\"\n+}\n+/^#/ || /^[ \t]*$/ { next }\n+state == 2 {\n+\tfor (i = 2; i <= NF; i++)\n+\t\tif (grp[$i]) {\n+\t\t\tf = \"Documentation/\"$1\".txt\"\n+\t\t\twhile (getline s <f > 0)\n+\t\t\t\tif (match(s, $1\" - \")) {\n+\t\t\t\t\tt = substr(s, length($1\" - \") + 1)\n+\t\t\t\t\tbreak\n+\t\t\t\t}\n+\t\t\tclose(f)\n+\t\t\tprintf \"\\t{\\\"%s\\\", N_(\\\"%s\\\"), %s},\\n\",\n+\t\t\t\tsubstr($1, length(\"git-\") + 1), t, grp[$i] - 1\n+\t\t\tbreak\n+\t\t}\n+}\n+/\\[commands\\]/ {\n+\tprint \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\"\n+\tstate = 2\n+}\n+state == 1 {\n+\tgrp[$1] = ++n\n+\tsub($1\"[ \t][ \t]*\", \"\")\n+\tprintf \"\\tN_(\\\"%s\\\"),\\n\", $0\n+}\n+/\\[common\\]/ {\n+\tstate = 1\n+}\n+END { print \"};\" }\n-- \n2.4.0\n"},{"id":"260898","messageId":"1431191856-10949-3-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 2/6] help.c: output the typical Git workflow","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:32Z","receivedAt":"2015-05-09T17:17:32Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"'git help' shows common commands in alphabetical order:\n\nThe most commonly used git commands are:\n   add        Add file contents to the index\n   bisect     Find by binary search the change that introduced a bug\n   branch     List, create, or delete branches\n   checkout   Checkout a branch or paths to the working tree\n   clone      Clone a repository into a new directory\n   commit     Record changes to the repository\n   [...]\n\nwithout any indication of how commands relate to high-level\nconcepts or each other. Revise the output to explain their relationship\nwith the typical Git workflow:\n\nThe typical Git workflow includes:\n\n   * start a working area (see also: git help tutorial):\n      clone      Clone a repository into a new directory\n      init       Create an empty Git repository or reinitialize [...]\n\n   * work on the current change (see also: git help everyday):\n      add        Add file contents to the index\n      reset      Reset current HEAD to the specified state\n\n   * examine the history and state (see also: git help revisions):\n      log        Show commit logs\n      status     Show the working tree status\n\n   [...]\n\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n help.c | 25 +++++++++++++++++++++++--\n 1 file changed, 23 insertions(+), 2 deletions(-)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..1df205f 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,6 +218,18 @@ void list_commands(unsigned int colopts,\n \t}\n }\n \n+int cmd_group_cmp(const void *elem1, const void *elem2)\n+{\n+\tconst struct cmdname_help *e1 = elem1;\n+\tconst struct cmdname_help *e2 = elem2;\n+\n+\tif (e1->group < e2->group)\n+\t\treturn -1;\n+\tif (e1->group > e2->group)\n+\t\treturn 1;\n+\treturn strcmp(e1->name, e2->name);\n+}\n+\n void list_common_cmds_help(void)\n {\n \tint i, longest = 0;\n@@ -227,9 +239,18 @@ void list_common_cmds_help(void)\n \t\t\tlongest = strlen(common_cmds[i].name);\n \t}\n \n-\tputs(_(\"The most commonly used git commands are:\"));\n+\tqsort(common_cmds, ARRAY_SIZE(common_cmds),\n+\t\tsizeof(common_cmds[0]), cmd_group_cmp);\n+\n+\tputs(_(\"The typical Git workflow includes:\"));\n+\n \tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-\t\tprintf(\"   %s   \", common_cmds[i].name);\n+\t\tif (common_cmds[i].group != current_grp) {\n+\t\t\tprintf(\"\\n   * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n+\t\t\tcurrent_grp = common_cmds[i].group;\n+\t\t}\n+\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 \t}\n-- \n2.4.0\n"},{"id":"260899","messageId":"1431191856-10949-4-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 3/6] command-list.txt: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:33Z","receivedAt":"2015-05-09T17:17:33Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Declare groups for common commands in the [common] block,\nfollowed by group names and descriptions:\n\n    [common]\n    init         start a working area (see also: git help tutorial)\n    worktree     work on the current change (see also: git [...]\n    info         examine the history and state (see also: git [...]\n    history      grow, mark and tweak your history\n    remote       collaborate (see also: git help workflows)\n\nSome descriptions include a 'see also' to redirect user to more\ndetailed documentation.\n\nThen, in the [commands] block, map all common commands with a group:\n\n    [commands]\n    git-add        mainporcelain     worktree\n    git-branch     mainporcelain     history\n    git-checkout   mainporcelain     history\n    [...]\n\nSo that 'git help' outputs those commands in headered groups.\n\nHelped-by: Junio C Hamano <gitster@pobox.com>\nHelped-by:  Emma Jane Hogbin Westby <emma.westby@gmail.com>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n command-list.txt | 56 ++++++++++++++++++++++++++++++++++----------------------\n 1 file changed, 34 insertions(+), 22 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex f1eae08..7e7ce53 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,29 +1,41 @@\n+# common commands are grouped by themes\n+# this order is the same that output by 'git help'\n+# map each common commands in the [commands] list to one of the groups.\n+# a command should not be marked both [deprecated] and [common]\n+[common]\n+init         start a working area (see also: git help tutorial)\n+worktree     work on the current change (see also: git help everyday)\n+info         examine the history and state (see also: git help revisions)\n+history      grow, mark and tweak your history\n+remote       collaborate (see also: git help workflows)\n+\n # List of known git commands.\n-# command name\t\t\t\tcategory [deprecated] [common]\n-git-add                                 mainporcelain common\n+# command name         [deprecated]     category                [common]\n+[commands]\n+git-add                                 mainporcelain           worktree\n git-am                                  mainporcelain\n git-annotate                            ancillaryinterrogators\n git-apply                               plumbingmanipulators\n git-archimport                          foreignscminterface\n git-archive                             mainporcelain\n-git-bisect                              mainporcelain common\n+git-bisect                              mainporcelain           info\n git-blame                               ancillaryinterrogators\n-git-branch                              mainporcelain common\n+git-branch                              mainporcelain           history\n git-bundle                              mainporcelain\n git-cat-file                            plumbinginterrogators\n git-check-attr                          purehelpers\n git-check-ignore                        purehelpers\n git-check-mailmap                       purehelpers\n-git-checkout                            mainporcelain common\n+git-checkout                            mainporcelain           history\n git-checkout-index                      plumbingmanipulators\n git-check-ref-format                    purehelpers\n git-cherry                              ancillaryinterrogators\n git-cherry-pick                         mainporcelain\n git-citool                              mainporcelain\n git-clean                               mainporcelain\n-git-clone                               mainporcelain common\n+git-clone                               mainporcelain           init\n git-column                              purehelpers\n-git-commit                              mainporcelain common\n+git-commit                              mainporcelain           history\n git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n@@ -35,14 +47,14 @@ git-cvsimport                           foreignscminterface\n git-cvsserver                           foreignscminterface\n git-daemon                              synchingrepositories\n git-describe                            mainporcelain\n-git-diff                                mainporcelain common\n+git-diff                                mainporcelain           history\n git-diff-files                          plumbinginterrogators\n git-diff-index                          plumbinginterrogators\n git-diff-tree                           plumbinginterrogators\n git-difftool                            ancillaryinterrogators\n git-fast-export\t\t\t\tancillarymanipulators\n git-fast-import\t\t\t\tancillarymanipulators\n-git-fetch                               mainporcelain common\n+git-fetch                               mainporcelain           remote\n git-fetch-pack                          synchingrepositories\n git-filter-branch                       ancillarymanipulators\n git-fmt-merge-msg                       purehelpers\n@@ -51,7 +63,7 @@ git-format-patch                        mainporcelain\n git-fsck\t                        ancillaryinterrogators\n git-gc                                  mainporcelain\n git-get-tar-commit-id                   ancillaryinterrogators\n-git-grep                                mainporcelain common\n+git-grep                                mainporcelain           info\n git-gui                                 mainporcelain\n git-hash-object                         plumbingmanipulators\n git-help\t\t\t\tancillaryinterrogators\n@@ -60,17 +72,17 @@ git-http-fetch                          synchelpers\n git-http-push                           synchelpers\n git-imap-send                           foreignscminterface\n git-index-pack                          plumbingmanipulators\n-git-init                                mainporcelain common\n+git-init                                mainporcelain           init\n git-instaweb                            ancillaryinterrogators\n git-interpret-trailers                  purehelpers\n gitk                                    mainporcelain\n-git-log                                 mainporcelain common\n+git-log                                 mainporcelain           info\n git-ls-files                            plumbinginterrogators\n git-ls-remote                           plumbinginterrogators\n git-ls-tree                             plumbinginterrogators\n git-mailinfo                            purehelpers\n git-mailsplit                           purehelpers\n-git-merge                               mainporcelain common\n+git-merge                               mainporcelain           history\n git-merge-base                          plumbinginterrogators\n git-merge-file                          plumbingmanipulators\n git-merge-index                         plumbingmanipulators\n@@ -79,7 +91,7 @@ git-mergetool                           ancillarymanipulators\n git-merge-tree                          ancillaryinterrogators\n git-mktag                               plumbingmanipulators\n git-mktree                              plumbingmanipulators\n-git-mv                                  mainporcelain common\n+git-mv                                  mainporcelain           worktree\n git-name-rev                            plumbinginterrogators\n git-notes                               mainporcelain\n git-p4                                  foreignscminterface\n@@ -90,11 +102,11 @@ git-parse-remote                        synchelpers\n git-patch-id                            purehelpers\n git-prune                               ancillarymanipulators\n git-prune-packed                        plumbingmanipulators\n-git-pull                                mainporcelain common\n-git-push                                mainporcelain common\n+git-pull                                mainporcelain           remote\n+git-push                                mainporcelain           remote\n git-quiltimport                         foreignscminterface\n git-read-tree                           plumbingmanipulators\n-git-rebase                              mainporcelain common\n+git-rebase                              mainporcelain           history\n git-receive-pack                        synchelpers\n git-reflog                              ancillarymanipulators\n git-relink                              ancillarymanipulators\n@@ -103,28 +115,28 @@ git-repack                              ancillarymanipulators\n git-replace                             ancillarymanipulators\n git-request-pull                        foreignscminterface\n git-rerere                              ancillaryinterrogators\n-git-reset                               mainporcelain common\n+git-reset                               mainporcelain           worktree\n git-revert                              mainporcelain\n git-rev-list                            plumbinginterrogators\n git-rev-parse                           ancillaryinterrogators\n-git-rm                                  mainporcelain common\n+git-rm                                  mainporcelain           worktree\n git-send-email                          foreignscminterface\n git-send-pack                           synchingrepositories\n git-shell                               synchelpers\n git-shortlog                            mainporcelain\n-git-show                                mainporcelain common\n+git-show                                mainporcelain           info\n git-show-branch                         ancillaryinterrogators\n git-show-index                          plumbinginterrogators\n git-show-ref                            plumbinginterrogators\n git-sh-i18n                             purehelpers\n git-sh-setup                            purehelpers\n git-stash                               mainporcelain\n-git-status                              mainporcelain common\n+git-status                              mainporcelain           info\n git-stripspace                          purehelpers\n git-submodule                           mainporcelain\n git-svn                                 foreignscminterface\n git-symbolic-ref                        plumbingmanipulators\n-git-tag                                 mainporcelain common\n+git-tag                                 mainporcelain           history\n git-unpack-file                         plumbinginterrogators\n git-unpack-objects                      plumbingmanipulators\n git-update-index                        plumbingmanipulators\n-- \n2.4.0\n"},{"id":"260900","messageId":"1431191856-10949-5-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 4/6] Makefile: update to new command-list.txt format","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:34Z","receivedAt":"2015-05-09T17:17:34Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"* In target common-cmds.h:\n  The AWK script 'generate-cmdlist.awk' replaces 'generate-cmdlist.sh'\n\n* In target check-docs:\n  command-list.txt now contains common commands group in\n  the header [common]. sed ignore all lines in command-list.txt\n  until the [commands] list to correctly checks for missing\n  documentation on Git commands.\n\nFor the target common-cmds.h part:\nSigned-off-by: Eric Sunshine <sunshine@sunshineco.com>\n\nFor the target check-docs part:\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n Makefile | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex 5f3987f..9f333e9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X\n \tln -s $< $@ 2>/dev/null || \\\n \tcp $< $@\n \n-common-cmds.h: ./generate-cmdlist.sh command-list.txt\n+common-cmds.h: generate-cmdlist.awk command-list.txt\n \n common-cmds.h: $(wildcard Documentation/git-*.txt)\n-\t$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n+\t$(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@\n \n SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\\\n \t$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\\\n@@ -2447,7 +2447,7 @@ check-docs::\n \t\tesac ; \\\n \t\ttest -f \"Documentation/$$v.txt\" || \\\n \t\techo \"no doc: $$v\"; \\\n-\t\tsed -e '/^#/d' command-list.txt | \\\n+\t\tsed -e '1,/^\\[commands\\]/d' <command-list.txt | \\\n \t\tgrep -q \"^$$v[ \t]\" || \\\n \t\tcase \"$$v\" in \\\n \t\tgit) ;; \\\n@@ -2455,7 +2455,7 @@ check-docs::\n \t\tesac ; \\\n \tdone; \\\n \t( \\\n-\t\tsed -e '/^#/d' \\\n+\t\tsed -e '1,/^\\[commands\\]/d' \\\n \t\t    -e 's/[ \t].*//' \\\n \t\t    -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\n-- \n2.4.0\n"},{"id":"260901","messageId":"1431191856-10949-6-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 5/6] new-command.txt: mention the common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:35Z","receivedAt":"2015-05-09T17:17:35Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"In the 6. step, add information about the common group commands\nfound in command-list.txt.\n\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n Documentation/howto/new-command.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\nindex d7de5a3..e7b0cc2 100644\n--- a/Documentation/howto/new-command.txt\n+++ b/Documentation/howto/new-command.txt\n@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.\n that categorizes commands by type, so they can be listed in appropriate\n subsections in the documentation's summary command list.  Add an entry\n for yours.  To understand the categories, look at git-commands.txt\n-in the main directory.\n+in the main directory. If the new command is part of the typical Git\n+workflow and you believe it's common enough to be mentioned in\n+'git help', map this command to a common group in the column [common]\n \n 7. Give the maintainer one paragraph to include in the RelNotes file\n to describe the new feature; a good place to do so is in the cover\n-- \n2.4.0\n"},{"id":"260902","messageId":"1431191856-10949-7-git-send-email-sebastien.guimmara@gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v5 6/6] cmd-list.perl: ignore all lines until [commands]","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-09T17:17:36Z","receivedAt":"2015-05-09T17:17:36Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"command-list.txt contains a [common] block that should be ignored\nby the Documentation checker cmd-list.perl.\n\nFilter out this block before the actual processing of the command list.\n\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n Documentation/cmd-list.perl | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 04f9977..d581378 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -38,8 +38,14 @@ sub format_one {\n \t}\n }\n \n+my @filtered = ();\n+while (<>)\n+{\n+\tpush (@filtered, $_) unless 1../^\\[commands\\]/;\n+}\n+\n my %cmds = ();\n-for (sort <>) {\n+for (sort @filtered) {\n \tnext if /^#/;\n \n \tchomp;\n-- \n2.4.0\n"},{"id":"260951","messageId":"CAPig+cQ7chw5eNCqv=HrrG1Zc4mGHUKyQssJuH1KAz-utt1h7g@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-1-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 0/6] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T05:52:50Z","receivedAt":"2015-05-11T05:52:50Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> Sébastien Guimmara (6):\n>   generate-cmdlist: parse common group commands\n>   help.c: output the typical Git workflow\n>   command-list.txt: group common commands by theme\n>   Makefile: update to new command-list.txt format\n>   new-command.txt: mention the common command groups\n>   cmd-list.perl: ignore all lines until [commands]\n\nWhen preparing a patch series, it's important to think not just about\nthe final result but also the state of the project at any point within\nthe series. The project should remain in a working state (not broken\nand not regressed) at all steps during the patch series[1]. As each\npatch is applied, you should be able to build git successfully, and\nrun \"git help\" and get expected results (for that point in the\nseries). If you can't do either, then there is a problem.\n\nUnfortunately, the organization of this series (v5) breaks the build\nand raw functionality from the get-go. Here is a proposed organization\nwhich will keep the project in a sane state as each patch is applied:\n\npatch 1: Add a [commands] header to command-list.txt and augment\ngenerate-cmdlist.sh, check-docs in Makefile, and either\nDocumentation/Makefile or cmd-list.perl to ignore everything up to and\nincluding [commands]. You're not actually doing any classification in\ncommand-list.txt at this point, but instead merely preparing the\nmachinery to deal with the [commands] header (and the [common] section\nwhich you will add in a subsequent patch).\n\npatch 2: Add the [common] block to command-list.txt and tag each of\nthe common commands with an attribute from [common]. Do *not*,\nhowever, remove the old \"common\" tag at this point since\ngenerate-cmdlist.sh still needs it.\n\npatch 3: Introduce generate-cmdlist.awk and retire\ngenerate-cmdlist.sh, along with the associated Makefile changes. This\npatch should be exactly the one I posted[2] (between the \"--- >8 ---\"\nlines), along with the minor fixup[3]. The changes in that patch are a\nlogical unit, so they shouldn't be split up (as you did in v5 between\npatches 1/6 and 4/6).\n\npatch 4: Drop the old \"common\" attribute from command-list.txt items\nsince it's no longer needed by any machinery.\n\npatch 5: Update help.c to group and sort the commands using the new\ncommon_cmd_groups[] array and common_commands[].group field.\n\npatch 6 [optional]: Update howto/new-command.txt. Alternately, and\nprobably preferably, fold this documentation update into patch 2 and\nomit this step.\n\n[1]: This is called \"preserving bisectability\". See \"git bisect\".\n[2]: http://article.gmane.org/gmane.comp.version-control.git/268598\n[3]: http://article.gmane.org/gmane.comp.version-control.git/268599\n"},{"id":"260952","messageId":"CAPig+cQfY+_4qYKR9vSeuwDe1Am3Csh1Q5M1CZbpvCCRHCdkKg@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-2-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 1/6] generate-cmdlist: parse common group commands","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:12:33Z","receivedAt":"2015-05-11T06:12:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> Parse the [common] block to create the array of group descriptions:\n\nSince you're resending a patch which I authored[1], the very first\nline of the email body should be:\n\n    From: Eric Sunshine <sunshine@sunshineco.com>\n\nwhich git-am will pick up automatically in order to assign proper\nattribution when the patch is applied.\n\nMore below.\n\n> static char *common_cmd_groups[] = {\n>     [...]\n> };\n>\n> then map each element of common_cmds[] to a group via its index:\n>\n> static struct cmdname_help common_cmds[] = {\n>     [...]\n> };\n>\n> so that 'git help' can print those commands grouped by theme.\n>\n> Only commands tagged with an attribute from [common] are emitted to\n> common_cmds[].\n>\n> [commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]\n>\n> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>\n\nLikewise, since you're resending[1] this patch you should add your own\nsign-off following the sign-off of the patch's author.\n\n> ---\n>  generate-cmdlist.awk | 38 ++++++++++++++++++++++++++++++++++++++\n>  1 file changed, 38 insertions(+)\n>  create mode 100644 generate-cmdlist.awk\n\nEach patch should be a self-contained logical unit, even if multiple\nfiles are touched.\n\nIn addition to introducing generate-cmdlist.awk, the original patch I\nwrote[1] also changed Makefile and removed generate-cmdlist.sh. Those\nchanges are a logical unit, and shouldn't be split up, as you did here\nwith v5 by moving the Makefile modifications to patch 4/6. Removal of\ngenerate-cmdlist.sh seems to have been lost entirely in v5.\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268598\n\n> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\n> new file mode 100644\n> index 0000000..cbaac88\n> --- /dev/null\n> +++ b/generate-cmdlist.awk\n> @@ -0,0 +1,38 @@\n> +BEGIN {\n> +       print \"/* Automatically generated by generate-cmdlist.awk */\\n\"\n> +       print \"struct cmdname_help {\"\n> +       print \"\\tchar name[16];\"\n> +       print \"\\tchar help[80];\"\n> +       print \"\\tunsigned char group;\"\n> +       print \"};\\n\"\n> +       print \"static char *common_cmd_groups[] = {\"\n> +}\n> +/^#/ || /^[    ]*$/ { next }\n> +state == 2 {\n> +       for (i = 2; i <= NF; i++)\n> +               if (grp[$i]) {\n> +                       f = \"Documentation/\"$1\".txt\"\n> +                       while (getline s <f > 0)\n> +                               if (match(s, $1\" - \")) {\n> +                                       t = substr(s, length($1\" - \") + 1)\n> +                                       break\n> +                               }\n> +                       close(f)\n> +                       printf \"\\t{\\\"%s\\\", N_(\\\"%s\\\"), %s},\\n\",\n> +                               substr($1, length(\"git-\") + 1), t, grp[$i] - 1\n> +                       break\n> +               }\n> +}\n> +/\\[commands\\]/ {\n> +       print \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\"\n> +       state = 2\n> +}\n> +state == 1 {\n> +       grp[$1] = ++n\n> +       sub($1\"[        ][      ]*\", \"\")\n> +       printf \"\\tN_(\\\"%s\\\"),\\n\", $0\n> +}\n> +/\\[common\\]/ {\n> +       state = 1\n> +}\n> +END { print \"};\" }\n> --\n> 2.4.0\n"},{"id":"260953","messageId":"CAPig+cSjdJ6Yhbvyw-m4E+Y9wEk71y0Cw2NO6c=f_cFy--YTGA@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-4-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 3/6] command-list.txt: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:20:19Z","receivedAt":"2015-05-11T06:20:19Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> Declare groups for common commands in the [common] block,\n> followed by group names and descriptions:\n>\n>     [common]\n>     init         start a working area (see also: git help tutorial)\n>     worktree     work on the current change (see also: git [...]\n>     info         examine the history and state (see also: git [...]\n>     history      grow, mark and tweak your history\n>     remote       collaborate (see also: git help workflows)\n>\n> Some descriptions include a 'see also' to redirect user to more\n> detailed documentation.\n\nThe example nicely shows the \"see also\", so this trailing sentence is\nsomewhat redundant.\n\nMore below.\n\n> Then, in the [commands] block, map all common commands with a group:\n>\n>     [commands]\n>     git-add        mainporcelain     worktree\n>     git-branch     mainporcelain     history\n>     git-checkout   mainporcelain     history\n>     [...]\n>\n> So that 'git help' outputs those commands in headered groups.\n>\n> Helped-by: Junio C Hamano <gitster@pobox.com>\n> Helped-by:  Emma Jane Hogbin Westby <emma.westby@gmail.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/command-list.txt b/command-list.txt\n> index f1eae08..7e7ce53 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,29 +1,41 @@\n> +# common commands are grouped by themes\n> +# this order is the same that output by 'git help'\n> +# map each common commands in the [commands] list to one of the groups.\n\nGrammar: \"map each common command\"\n\nMaybe also \"one of these groups\".\n\n> +# a command should not be marked both [deprecated] and [common]\n\nI wonder if it is really necessary to state this, as there is no\ntechnical reason for the restriction, and it should be common sense\n(one would hope).\n\n> +[common]\n> +init         start a working area (see also: git help tutorial)\n> +worktree     work on the current change (see also: git help everyday)\n> +info         examine the history and state (see also: git help revisions)\n> +history      grow, mark and tweak your history\n> +remote       collaborate (see also: git help workflows)\n> +\n>  # List of known git commands.\n> -# command name                         category [deprecated] [common]\n> -git-add                                 mainporcelain common\n> +# command name         [deprecated]     category                [common]\n\nWhy did [deprecated] move from following \"category\" to preceding it?\n\nAlso, I wonder if [common] should be spelled [<common>] or something\nto distinguish it from [deprecated] which is a literal token. (I don't\ncare strongly; I'm just wondering.)\n\n> +[commands]\n> +git-add                                 mainporcelain           worktree\n>  git-am                                  mainporcelain\n>  git-annotate                            ancillaryinterrogators\n>  git-apply                               plumbingmanipulators\n>  git-archimport                          foreignscminterface\n>  git-archive                             mainporcelain\n> -git-bisect                              mainporcelain common\n> +git-bisect                              mainporcelain           info\n>  git-blame                               ancillaryinterrogators\n> -git-branch                              mainporcelain common\n> +git-branch                              mainporcelain           history\n>  git-bundle                              mainporcelain\n>  git-cat-file                            plumbinginterrogators\n>  git-check-attr                          purehelpers\n>  git-check-ignore                        purehelpers\n>  git-check-mailmap                       purehelpers\n> -git-checkout                            mainporcelain common\n> +git-checkout                            mainporcelain           history\n>  git-checkout-index                      plumbingmanipulators\n>  git-check-ref-format                    purehelpers\n>  git-cherry                              ancillaryinterrogators\n>  git-cherry-pick                         mainporcelain\n>  git-citool                              mainporcelain\n>  git-clean                               mainporcelain\n> -git-clone                               mainporcelain common\n> +git-clone                               mainporcelain           init\n>  git-column                              purehelpers\n> -git-commit                              mainporcelain common\n> +git-commit                              mainporcelain           history\n>  git-commit-tree                         plumbingmanipulators\n>  git-config                              ancillarymanipulators\n>  git-count-objects                       ancillaryinterrogators\n> @@ -35,14 +47,14 @@ git-cvsimport                           foreignscminterface\n>  git-cvsserver                           foreignscminterface\n>  git-daemon                              synchingrepositories\n>  git-describe                            mainporcelain\n> -git-diff                                mainporcelain common\n> +git-diff                                mainporcelain           history\n>  git-diff-files                          plumbinginterrogators\n>  git-diff-index                          plumbinginterrogators\n>  git-diff-tree                           plumbinginterrogators\n>  git-difftool                            ancillaryinterrogators\n>  git-fast-export                                ancillarymanipulators\n>  git-fast-import                                ancillarymanipulators\n> -git-fetch                               mainporcelain common\n> +git-fetch                               mainporcelain           remote\n>  git-fetch-pack                          synchingrepositories\n>  git-filter-branch                       ancillarymanipulators\n>  git-fmt-merge-msg                       purehelpers\n> @@ -51,7 +63,7 @@ git-format-patch                        mainporcelain\n>  git-fsck                               ancillaryinterrogators\n>  git-gc                                  mainporcelain\n>  git-get-tar-commit-id                   ancillaryinterrogators\n> -git-grep                                mainporcelain common\n> +git-grep                                mainporcelain           info\n>  git-gui                                 mainporcelain\n>  git-hash-object                         plumbingmanipulators\n>  git-help                               ancillaryinterrogators\n> @@ -60,17 +72,17 @@ git-http-fetch                          synchelpers\n>  git-http-push                           synchelpers\n>  git-imap-send                           foreignscminterface\n>  git-index-pack                          plumbingmanipulators\n> -git-init                                mainporcelain common\n> +git-init                                mainporcelain           init\n>  git-instaweb                            ancillaryinterrogators\n>  git-interpret-trailers                  purehelpers\n>  gitk                                    mainporcelain\n> -git-log                                 mainporcelain common\n> +git-log                                 mainporcelain           info\n>  git-ls-files                            plumbinginterrogators\n>  git-ls-remote                           plumbinginterrogators\n>  git-ls-tree                             plumbinginterrogators\n>  git-mailinfo                            purehelpers\n>  git-mailsplit                           purehelpers\n> -git-merge                               mainporcelain common\n> +git-merge                               mainporcelain           history\n>  git-merge-base                          plumbinginterrogators\n>  git-merge-file                          plumbingmanipulators\n>  git-merge-index                         plumbingmanipulators\n> @@ -79,7 +91,7 @@ git-mergetool                           ancillarymanipulators\n>  git-merge-tree                          ancillaryinterrogators\n>  git-mktag                               plumbingmanipulators\n>  git-mktree                              plumbingmanipulators\n> -git-mv                                  mainporcelain common\n> +git-mv                                  mainporcelain           worktree\n>  git-name-rev                            plumbinginterrogators\n>  git-notes                               mainporcelain\n>  git-p4                                  foreignscminterface\n> @@ -90,11 +102,11 @@ git-parse-remote                        synchelpers\n>  git-patch-id                            purehelpers\n>  git-prune                               ancillarymanipulators\n>  git-prune-packed                        plumbingmanipulators\n> -git-pull                                mainporcelain common\n> -git-push                                mainporcelain common\n> +git-pull                                mainporcelain           remote\n> +git-push                                mainporcelain           remote\n>  git-quiltimport                         foreignscminterface\n>  git-read-tree                           plumbingmanipulators\n> -git-rebase                              mainporcelain common\n> +git-rebase                              mainporcelain           history\n>  git-receive-pack                        synchelpers\n>  git-reflog                              ancillarymanipulators\n>  git-relink                              ancillarymanipulators\n> @@ -103,28 +115,28 @@ git-repack                              ancillarymanipulators\n>  git-replace                             ancillarymanipulators\n>  git-request-pull                        foreignscminterface\n>  git-rerere                              ancillaryinterrogators\n> -git-reset                               mainporcelain common\n> +git-reset                               mainporcelain           worktree\n>  git-revert                              mainporcelain\n>  git-rev-list                            plumbinginterrogators\n>  git-rev-parse                           ancillaryinterrogators\n> -git-rm                                  mainporcelain common\n> +git-rm                                  mainporcelain           worktree\n>  git-send-email                          foreignscminterface\n>  git-send-pack                           synchingrepositories\n>  git-shell                               synchelpers\n>  git-shortlog                            mainporcelain\n> -git-show                                mainporcelain common\n> +git-show                                mainporcelain           info\n>  git-show-branch                         ancillaryinterrogators\n>  git-show-index                          plumbinginterrogators\n>  git-show-ref                            plumbinginterrogators\n>  git-sh-i18n                             purehelpers\n>  git-sh-setup                            purehelpers\n>  git-stash                               mainporcelain\n> -git-status                              mainporcelain common\n> +git-status                              mainporcelain           info\n>  git-stripspace                          purehelpers\n>  git-submodule                           mainporcelain\n>  git-svn                                 foreignscminterface\n>  git-symbolic-ref                        plumbingmanipulators\n> -git-tag                                 mainporcelain common\n> +git-tag                                 mainporcelain           history\n>  git-unpack-file                         plumbinginterrogators\n>  git-unpack-objects                      plumbingmanipulators\n>  git-update-index                        plumbingmanipulators\n> --\n> 2.4.0\n"},{"id":"260954","messageId":"CAPig+cR46K2h+hk4riwXcty=T+RBoT1Za9rqOwB9EgvUReUhmg@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-3-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 2/6] help.c: output the typical Git workflow","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:24:37Z","receivedAt":"2015-05-11T06:24:37Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> 'git help' shows common commands in alphabetical order:\n>\n> The most commonly used git commands are:\n>    add        Add file contents to the index\n>    bisect     Find by binary search the change that introduced a bug\n>    branch     List, create, or delete branches\n>    checkout   Checkout a branch or paths to the working tree\n>    clone      Clone a repository into a new directory\n>    commit     Record changes to the repository\n>    [...]\n>\n> without any indication of how commands relate to high-level\n> concepts or each other. Revise the output to explain their relationship\n> with the typical Git workflow:\n>\n> The typical Git workflow includes:\n>\n>    * start a working area (see also: git help tutorial):\n>       clone      Clone a repository into a new directory\n>       init       Create an empty Git repository or reinitialize [...]\n\nIn practice, I find the indented bulleted header items somewhat\nunsightly. More importantly, indenting them wastes precious horizontal\nscreen real-estate (for those of who use 80-column terminals). Since\nthe headers are already distinguished by being bulleted, you could\neasily drop the indentation; and then reduce the indentation of the\ncommands themselves.\n\n>    * work on the current change (see also: git help everyday):\n>       add        Add file contents to the index\n>       reset      Reset current HEAD to the specified state\n>\n>    * examine the history and state (see also: git help revisions):\n>       log        Show commit logs\n>       status     Show the working tree status\n>\n>    [...]\n>\n> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/help.c b/help.c\n> index 2072a87..1df205f 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -218,6 +218,18 @@ void list_commands(unsigned int colopts,\n>         }\n>  }\n>\n> +int cmd_group_cmp(const void *elem1, const void *elem2)\n> +{\n> +       const struct cmdname_help *e1 = elem1;\n> +       const struct cmdname_help *e2 = elem2;\n> +\n> +       if (e1->group < e2->group)\n> +               return -1;\n> +       if (e1->group > e2->group)\n> +               return 1;\n> +       return strcmp(e1->name, e2->name);\n> +}\n> +\n>  void list_common_cmds_help(void)\n>  {\n>         int i, longest = 0;\n> @@ -227,9 +239,18 @@ void list_common_cmds_help(void)\n>                         longest = strlen(common_cmds[i].name);\n>         }\n>\n> -       puts(_(\"The most commonly used git commands are:\"));\n> +       qsort(common_cmds, ARRAY_SIZE(common_cmds),\n> +               sizeof(common_cmds[0]), cmd_group_cmp);\n> +\n> +       puts(_(\"The typical Git workflow includes:\"));\n> +\n>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n> -               printf(\"   %s   \", common_cmds[i].name);\n> +               if (common_cmds[i].group != current_grp) {\n> +                       printf(\"\\n   * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n> +                       current_grp = common_cmds[i].group;\n> +               }\n> +\n> +               printf(\"      %s   \", common_cmds[i].name);\n>                 mput_char(' ', longest - strlen(common_cmds[i].name));\n>                 puts(_(common_cmds[i].help));\n>         }\n> --\n> 2.4.0\n"},{"id":"260955","messageId":"CAPig+cQBUiniQ_A2BZGx-R4kxabE5hPcrbcoPXbq0kJS6oP+uw@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-5-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 4/6] Makefile: update to new command-list.txt format","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:44:26Z","receivedAt":"2015-05-11T06:44:26Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> * In target common-cmds.h:\n>   The AWK script 'generate-cmdlist.awk' replaces 'generate-cmdlist.sh'\n>\n> * In target check-docs:\n>   command-list.txt now contains common commands group in\n>   the header [common]. sed ignore all lines in command-list.txt\n>   until the [commands] list to correctly checks for missing\n>   documentation on Git commands.\n>\n> For the target common-cmds.h part:\n> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>\n\nThe Makefile modification from my generate-cmdlist patch[1] is part of\nthe overall logical change of that patch. Its relation to the Makefile\nchanges in this patch is weak at best, or entirely non-existent.\nConsequently, it should not be mixed with them. See my reply[2] to the\nv5 cover letter for more information.\n\nMore below.\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268598\n[2]: http://article.gmane.org/gmane.comp.version-control.git/268756\n\n> For the target check-docs part:\n> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/Makefile b/Makefile\n> index 5f3987f..9f333e9 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X\n>         ln -s $< $@ 2>/dev/null || \\\n>         cp $< $@\n>\n> -common-cmds.h: ./generate-cmdlist.sh command-list.txt\n> +common-cmds.h: generate-cmdlist.awk command-list.txt\n>\n>  common-cmds.h: $(wildcard Documentation/git-*.txt)\n> -       $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n> +       $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@\n>\n>  SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\\\n>         $(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\\\n> @@ -2447,7 +2447,7 @@ check-docs::\n>                 esac ; \\\n>                 test -f \"Documentation/$$v.txt\" || \\\n>                 echo \"no doc: $$v\"; \\\n> -               sed -e '/^#/d' command-list.txt | \\\n> +               sed -e '1,/^\\[commands\\]/d' <command-list.txt | \\\n\nI'm not convinced that it's a good idea to drop comment-line\nprocessing from this sed invocation. Even though the current\ncommand-list.txt may not have any comments following the [commands]\nheader, there is no guarantee that someone won't some day add some\ncomments following the header.\n\nsed accepts multiple -e arguments, so retaining comment-line\nprocessing does not make the extraction any more expensive. For\ninstance:\n\n    sed -e '1,/^\\[commands\\]/d' -e '/^#/d' <command-list.txt | \\\n\n>                 grep -q \"^$$v[  ]\" || \\\n>                 case \"$$v\" in \\\n>                 git) ;; \\\n> @@ -2455,7 +2455,7 @@ check-docs::\n>                 esac ; \\\n>         done; \\\n>         ( \\\n> -               sed -e '/^#/d' \\\n> +               sed -e '1,/^\\[commands\\]/d' \\\n\nDitto. It would be more robust to retain comment-line processing.\n\n>                     -e 's/[     ].*//' \\\n>                     -e 's/^/listed /' command-list.txt; \\\n>                 $(MAKE) -C Documentation print-man1 | \\\n> --\n> 2.4.0\n"},{"id":"260956","messageId":"CAPig+cTwRawmrX2MHyUhC9Dm3CaCGANZdgOV=TKJ3Fqx2OWwXQ@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-6-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 5/6] new-command.txt: mention the common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:47:00Z","receivedAt":"2015-05-11T06:47:00Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> In the 6. step, add information about the common group commands\n> found in command-list.txt.\n\nI don't feel too strongly about it, but as this is such a minor\nchange, and as it is directly related to the addition of the [common]\nsecond in command-list.txt, it also would make sense just to fold this\nchange into the patch which introduces [common] (that is, v5 patch\n3/6).\n\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\n> index d7de5a3..e7b0cc2 100644\n> --- a/Documentation/howto/new-command.txt\n> +++ b/Documentation/howto/new-command.txt\n> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file.\n>  that categorizes commands by type, so they can be listed in appropriate\n>  subsections in the documentation's summary command list.  Add an entry\n>  for yours.  To understand the categories, look at git-commands.txt\n> -in the main directory.\n> +in the main directory. If the new command is part of the typical Git\n> +workflow and you believe it's common enough to be mentioned in\n> +'git help', map this command to a common group in the column [common]\n>\n>  7. Give the maintainer one paragraph to include in the RelNotes file\n>  to describe the new feature; a good place to do so is in the cover\n> --\n> 2.4.0\n"},{"id":"260958","messageId":"CAPig+cRSPENt8QamfSOSgVFf_nmRKnfYkiOpf09WR=6--fLaEw@mail.gmail.com","threadId":"39284","inReplyTo":"1431191856-10949-7-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v5 6/6] cmd-list.perl: ignore all lines until [commands]","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-11T06:59:21Z","receivedAt":"2015-05-11T06:59:21Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> command-list.txt contains a [common] block that should be ignored\n> by the Documentation checker cmd-list.perl.\n>\n> Filter out this block before the actual processing of the command list.\n>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\n> index 04f9977..d581378 100755\n> --- a/Documentation/cmd-list.perl\n> +++ b/Documentation/cmd-list.perl\n> @@ -38,8 +38,14 @@ sub format_one {\n>         }\n>  }\n>\n> +my @filtered = ();\n> +while (<>)\n> +{\n\nStyle: while (<>) {\n\n> +       push (@filtered, $_) unless 1../^\\[commands\\]/;\n> +}\n\nWhy collect the lines into @filtered when you could instead merely\nskip the unwanted ones outright?\n\n    while (<>) {\n        last if /^\\[commands\\]/;\n    }\n\nAnd, then you don't need to touch the following 'for' loop at all.\n\n>  my %cmds = ();\n> -for (sort <>) {\n> +for (sort @filtered) {\n>         next if /^#/;\n>\n>         chomp;\n> --\n> 2.4.0\n"}]}