{"thread":{"id":"39347","subject":"[PATCH v7 0/5] git help: group common commands by theme","startedAt":"2015-05-15T18:34:59Z","lastAt":"2015-05-18T16:25:10Z","messageCount":23,"participants":["Sébastien Guimmara","Junio C Hamano","Eric Sunshine","Philip Oakley"],"isPatch":true,"patchVersion":7,"patchTotal":5},"messages":[{"id":"261361","messageId":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":null,"subject":"[PATCH v7 0/5] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:34:59Z","receivedAt":"2015-05-15T18:34:59Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"This v7 is very similar in content to the v5 [1], except minor formatting\nadjustments in 'git help' output and recommendations from Eric.\n\nrebased on 'next' (a2776d4)\n\nThe major change is in the patch series itself. Commits have been\nreordered and adjusted so that each 'apply' doesn't break the build, and\npreserve bisectability.\n\nSummary: make 'git help' outputs a more usable and friendlier\nlist of commands, grouped by theme according to the typical Git workflow:\n\n[...]\n\nThe typical Git workflow includes:\n\nstart 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 an existing one\n\nwork on the current change (see also: git help everyday):\n   add        Add file contents to the index\n   mv         Move or rename a file, a directory, or a symlink\n   reset      Reset current HEAD to the specified state\n   rm         Remove files from the working tree and from the index\n\n[...]\n\nMany thanks to Eric Sunshine for the detailed help and advice !\n\n[1]: http://thread.gmane.org/gmane.comp.version-control.git/268701\n\nEric Sunshine (1):\n  generate-cmdlist: parse common group commands\n\nSébastien Guimmara (4):\n  command-list.txt: prepare with [commands] header\n  command-list.txt: add a [common] block\n  command-list.txt: drop the common tag\n  help.c: output the typical Git workflow\n\n Documentation/cmd-list.perl         |  4 +++\n Documentation/howto/new-command.txt |  4 ++-\n Makefile                            |  7 ++---\n command-list.txt                    | 53 ++++++++++++++++++++++---------------\n generate-cmdlist.awk                | 39 +++++++++++++++++++++++++++\n generate-cmdlist.sh                 | 23 ----------------\n help.c                              | 24 ++++++++++++++++-\n 7 files changed, 105 insertions(+), 49 deletions(-)\n create mode 100644 generate-cmdlist.awk\n delete mode 100755 generate-cmdlist.sh\n\n-- \n2.4.0\n"},{"id":"261362","messageId":"1431714904-16599-2-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:35:00Z","receivedAt":"2015-05-15T18:35:00Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Add a [commands] header before the actual command list, then make the\nfollowing files ignore this header in their parsing:\n\n\t* cmd-list.perl\n\t* Makefile (check-docks target)\n\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n Documentation/cmd-list.perl         | 4 ++++\n Documentation/howto/new-command.txt | 4 +++-\n Makefile                            | 3 ++-\n command-list.txt                    | 1 +\n 4 files changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 04f9977..06a5fd6 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -38,6 +38,10 @@ sub format_one {\n \t}\n }\n \n+while (<>) {\n+\tlast if /^\\[commands\\]/;\n+}\n+\n my %cmds = ();\n for (sort <>) {\n \tnext if /^#/;\ndiff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\nindex d7de5a3..6d772bd 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 common enough to be mentioned in 'git help',\n+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\ndiff --git a/Makefile b/Makefile\nindex 25a453b..0cb2045 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n \t\tgrep -q \"^$$v[ \t]\" || \\\n \t\tcase \"$$v\" in \\\n \t\tgit) ;; \\\n@@ -2463,6 +2463,7 @@ check-docs::\n \tdone; \\\n \t( \\\n \t\tsed -e '/^#/d' \\\n+\t\t    -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 | \\\ndiff --git a/command-list.txt b/command-list.txt\nindex 54d8d21..caed872 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,5 +1,6 @@\n # List of known git commands.\n # command name                          category [deprecated] [common]\n+[commands]\n git-add                                 mainporcelain common\n git-am                                  mainporcelain\n git-annotate                            ancillaryinterrogators\n-- \n2.4.0\n"},{"id":"261363","messageId":"1431714904-16599-3-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v7 2/5] command-list.txt: add a [common] block","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:35:01Z","receivedAt":"2015-05-15T18:35:01Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Add a [common] block at the beginning of command-list.txt:\n\n    [common]\n    init         start a working area (see also: git help tutorial)\n    worktree     work on the current change (see also:[...]\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\nstoring information about common commands group, then map each common\ncommand to a group:\n\n    git-add          mainporcelain        common worktree\n\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\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 | 52 +++++++++++++++++++++++++++++++---------------------\n 1 file changed, 31 insertions(+), 21 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex caed872..c00b0b6 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,30 +1,40 @@\n+# common commands are grouped by themes\n+# this order is the same that output by 'git help'\n+# map each common command in the [commands] list to one of these groups.\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 common history\n+remote       collaborate (see also: git help workflows)\n+\n # List of known git commands.\n # command name                          category [deprecated] [common]\n [commands]\n-git-add                                 mainporcelain common\n+git-add                                 mainporcelain           common 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           common info\n git-blame                               ancillaryinterrogators\n-git-branch                              mainporcelain common\n+git-branch                              mainporcelain           common 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           common 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           common init\n git-column                              purehelpers\n-git-commit                              mainporcelain common\n+git-commit                              mainporcelain           common history\n git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n@@ -36,14 +46,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           common 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           common remote\n git-fetch-pack                          synchingrepositories\n git-filter-branch                       ancillarymanipulators\n git-fmt-merge-msg                       purehelpers\n@@ -52,7 +62,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           common info\n git-gui                                 mainporcelain\n git-hash-object                         plumbingmanipulators\n git-help                                ancillaryinterrogators\n@@ -61,17 +71,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           common init\n git-instaweb                            ancillaryinterrogators\n git-interpret-trailers                  purehelpers\n gitk                                    mainporcelain\n-git-log                                 mainporcelain common\n+git-log                                 mainporcelain           common 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           common history\n git-merge-base                          plumbinginterrogators\n git-merge-file                          plumbingmanipulators\n git-merge-index                         plumbingmanipulators\n@@ -80,7 +90,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           common worktree\n git-name-rev                            plumbinginterrogators\n git-notes                               mainporcelain\n git-p4                                  foreignscminterface\n@@ -91,11 +101,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           common remote\n+git-push                                mainporcelain           common remote\n git-quiltimport                         foreignscminterface\n git-read-tree                           plumbingmanipulators\n-git-rebase                              mainporcelain common\n+git-rebase                              mainporcelain           common history\n git-receive-pack                        synchelpers\n git-reflog                              ancillarymanipulators\n git-relink                              ancillarymanipulators\n@@ -104,28 +114,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           common worktree\n git-revert                              mainporcelain\n git-rev-list                            plumbinginterrogators\n git-rev-parse                           ancillaryinterrogators\n-git-rm                                  mainporcelain common\n+git-rm                                  mainporcelain           common 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           common 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           common 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           common history\n git-unpack-file                         plumbinginterrogators\n git-unpack-objects                      plumbingmanipulators\n git-update-index                        plumbingmanipulators\n-- \n2.4.0\n"},{"id":"261364","messageId":"1431714904-16599-4-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v7 3/5] generate-cmdlist: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:35:02Z","receivedAt":"2015-05-15T18:35:02Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"From: Eric Sunshine <sunshine@sunshineco.com>\n\nParse the [common] block to create the array of group descriptions:\n\nstatic char *common_cmd_groups[] = {\n    N_(\"starting a working area\"),\n    N_(\"working on the current change\"),\n    N_(\"working with others\"),\n    N_(\"examining the history and state\"),\n    N_(\"growing, marking and tweaking your history\"),\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>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n Makefile             |  4 ++--\n generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++\n generate-cmdlist.sh  | 23 -----------------------\n 3 files changed, 41 insertions(+), 25 deletions(-)\n create mode 100644 generate-cmdlist.awk\n delete mode 100755 generate-cmdlist.sh\n\ndiff --git a/Makefile b/Makefile\nindex 0cb2045..fdf9318 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1693,10 +1693,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):\\\ndiff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\nnew file mode 100644\nindex 0000000..b5cc789\n--- /dev/null\n+++ b/generate-cmdlist.awk\n@@ -0,0 +1,39 @@\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+\tnext\n+}\n+/\\[common\\]/ {\n+\tstate = 1\n+}\n+END { print \"};\" }\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\ndeleted file mode 100755\nindex 9a4c9b9..0000000\n--- a/generate-cmdlist.sh\n+++ /dev/null\n@@ -1,23 +0,0 @@\n-#!/bin/sh\n-\n-echo \"/* Automatically generated by $0 */\n-struct cmdname_help {\n-    char name[16];\n-    char help[80];\n-};\n-\n-static struct cmdname_help common_cmds[] = {\"\n-\n-sed -n -e 's/^git-\\([^ \t]*\\)[ \t].* common.*/\\1/p' command-list.txt |\n-sort |\n-while read cmd\n-do\n-     sed -n '\n-     /^NAME/,/git-'\"$cmd\"'/H\n-     ${\n-\t    x\n-\t    s/.*git-'\"$cmd\"' - \\(.*\\)/  {\"'\"$cmd\"'\", N_(\"\\1\")},/\n-\t    p\n-     }' \"Documentation/git-$cmd.txt\"\n-done\n-echo \"};\"\n-- \n2.4.0\n"},{"id":"261367","messageId":"1431714904-16599-5-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v7 4/5] command-list.txt: drop the common tag","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:35:03Z","receivedAt":"2015-05-15T18:35:03Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"The parser generate-cmdlist.awk gathers all group information without\nneeding the common tag.\n\nbefore:\n    git-add          mainporcelain        common worktree\n\nafter:\n    git-add          mainporcelain        worktree\n\nHelped-by: Eric Sunshine <sunshine@sunshineco.com>\nSigned-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n---\n command-list.txt | 42 +++++++++++++++++++++---------------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex c00b0b6..2203566 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -11,30 +11,30 @@ remote       collaborate (see also: git help workflows)\n # List of known git commands.\n # command name                          category [deprecated] [common]\n [commands]\n-git-add                                 mainporcelain           common worktree\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 info\n+git-bisect                              mainporcelain           info\n git-blame                               ancillaryinterrogators\n-git-branch                              mainporcelain           common history\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 history\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 init\n+git-clone                               mainporcelain           init\n git-column                              purehelpers\n-git-commit                              mainporcelain           common history\n+git-commit                              mainporcelain           history\n git-commit-tree                         plumbingmanipulators\n git-config                              ancillarymanipulators\n git-count-objects                       ancillaryinterrogators\n@@ -46,14 +46,14 @@ git-cvsimport                           foreignscminterface\n git-cvsserver                           foreignscminterface\n git-daemon                              synchingrepositories\n git-describe                            mainporcelain\n-git-diff                                mainporcelain           common history\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 remote\n+git-fetch                               mainporcelain           remote\n git-fetch-pack                          synchingrepositories\n git-filter-branch                       ancillarymanipulators\n git-fmt-merge-msg                       purehelpers\n@@ -62,7 +62,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 info\n+git-grep                                mainporcelain           info\n git-gui                                 mainporcelain\n git-hash-object                         plumbingmanipulators\n git-help                                ancillaryinterrogators\n@@ -71,17 +71,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 init\n+git-init                                mainporcelain           init\n git-instaweb                            ancillaryinterrogators\n git-interpret-trailers                  purehelpers\n gitk                                    mainporcelain\n-git-log                                 mainporcelain           common info\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 history\n+git-merge                               mainporcelain           history\n git-merge-base                          plumbinginterrogators\n git-merge-file                          plumbingmanipulators\n git-merge-index                         plumbingmanipulators\n@@ -90,7 +90,7 @@ git-mergetool                           ancillarymanipulators\n git-merge-tree                          ancillaryinterrogators\n git-mktag                               plumbingmanipulators\n git-mktree                              plumbingmanipulators\n-git-mv                                  mainporcelain           common worktree\n+git-mv                                  mainporcelain           worktree\n git-name-rev                            plumbinginterrogators\n git-notes                               mainporcelain\n git-p4                                  foreignscminterface\n@@ -101,11 +101,11 @@ git-parse-remote                        synchelpers\n git-patch-id                            purehelpers\n git-prune                               ancillarymanipulators\n git-prune-packed                        plumbingmanipulators\n-git-pull                                mainporcelain           common remote\n-git-push                                mainporcelain           common remote\n+git-pull                                mainporcelain           remote\n+git-push                                mainporcelain           remote\n git-quiltimport                         foreignscminterface\n git-read-tree                           plumbingmanipulators\n-git-rebase                              mainporcelain           common history\n+git-rebase                              mainporcelain           history\n git-receive-pack                        synchelpers\n git-reflog                              ancillarymanipulators\n git-relink                              ancillarymanipulators\n@@ -114,28 +114,28 @@ git-repack                              ancillarymanipulators\n git-replace                             ancillarymanipulators\n git-request-pull                        foreignscminterface\n git-rerere                              ancillaryinterrogators\n-git-reset                               mainporcelain           common worktree\n+git-reset                               mainporcelain           worktree\n git-revert                              mainporcelain\n git-rev-list                            plumbinginterrogators\n git-rev-parse                           ancillaryinterrogators\n-git-rm                                  mainporcelain           common worktree\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 info\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 info\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 history\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":"261365","messageId":"1431714904-16599-6-git-send-email-sebastien.guimmara@gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v7 5/5] help.c: output the typical Git workflow","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T18:35:04Z","receivedAt":"2015-05-15T18:35:04Z","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\nstart 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\nwork 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\nexamine 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 | 24 +++++++++++++++++++++++-\n 1 file changed, 23 insertions(+), 1 deletion(-)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..bdb69d1 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,17 +218,39 @@ 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+\tint current_grp = -1;\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 \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\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-- \n2.4.0\n"},{"id":"261371","messageId":"xmqqr3qhfuz3.fsf@gitster.dls.corp.google.com","threadId":"39347","inReplyTo":"1431714904-16599-2-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-15T20:26:24Z","receivedAt":"2015-05-15T20:26:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:\n\n> diff --git a/Makefile b/Makefile\n> index 25a453b..0cb2045 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n>  \t\tgrep -q \"^$$v[ \t]\" || \\\n>  \t\tcase \"$$v\" in \\\n>  \t\tgit) ;; \\\n> @@ -2463,6 +2463,7 @@ check-docs::\n>  \tdone; \\\n>  \t( \\\n>  \t\tsed -e '/^#/d' \\\n> +\t\t    -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> diff --git a/command-list.txt b/command-list.txt\n> index 54d8d21..caed872 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,5 +1,6 @@\n>  # List of known git commands.\n>  # command name                          category [deprecated] [common]\n> +[commands]\n>  git-add                                 mainporcelain common\n>  git-am                                  mainporcelain\n>  git-annotate                            ancillaryinterrogators\n\nThis is largely just a \"taste\" thing, but with all these backslashes\nin the supporting infrastructure you had to add in Makefiles and\nscripts, don't you think the choice of the way you designed the\nformat to use '[commands]' was a rather poor one?  After all, all\nyou need is a clear separator line for a block of commands and\nanother block of groups, and there wasn't a reason why you needed to\nuse square brackets for that, and the sed scripts are suffering from\nthat poor choice.\n\nYou could for example have used the existing \"# List of known git\ncommands\" as such a signal to tell that all the no comment lines\nbelow are commands.\n"},{"id":"261373","messageId":"5556582C.3010409@gmail.com","threadId":"39347","inReplyTo":"xmqqr3qhfuz3.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T20:33:48Z","receivedAt":"2015-05-15T20:33:48Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/15/2015 10:26 PM, Junio C Hamano wrote:\n> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:\n>\n>> diff --git a/Makefile b/Makefile\n>> index 25a453b..0cb2045 100644\n>> --- a/Makefile\n>> +++ b/Makefile\n>> @@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n>>   \t\tgrep -q \"^$$v[ \t]\" || \\\n>>   \t\tcase \"$$v\" in \\\n>>   \t\tgit) ;; \\\n>> @@ -2463,6 +2463,7 @@ check-docs::\n>>   \tdone; \\\n>>   \t( \\\n>>   \t\tsed -e '/^#/d' \\\n>> +\t\t    -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>> diff --git a/command-list.txt b/command-list.txt\n>> index 54d8d21..caed872 100644\n>> --- a/command-list.txt\n>> +++ b/command-list.txt\n>> @@ -1,5 +1,6 @@\n>>   # List of known git commands.\n>>   # command name                          category [deprecated] [common]\n>> +[commands]\n>>   git-add                                 mainporcelain common\n>>   git-am                                  mainporcelain\n>>   git-annotate                            ancillaryinterrogators\n>\n> This is largely just a \"taste\" thing, but with all these backslashes\n> in the supporting infrastructure you had to add in Makefiles and\n> scripts, don't you think the choice of the way you designed the\n> format to use '[commands]' was a rather poor one?  After all, all\n> you need is a clear separator line for a block of commands and\n> another block of groups, and there wasn't a reason why you needed to\n> use square brackets for that, and the sed scripts are suffering from\n> that poor choice.\n>\n> You could for example have used the existing \"# List of known git\n> commands\" as such a signal to tell that all the no comment lines\n> below are commands.\n>\n\nI tend to think that relying on comments as marks for parsers is brittle,\nbut indeed square brackets get in the way of sed regexes. I'll think of\nsomething better. Thanks.\n"},{"id":"261374","messageId":"CAPig+cTAMrQEfK81WWn3honj5yL5RjYvt13P63kZoZ+pQ1f98g@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-1-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 0/5] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T20:41:04Z","receivedAt":"2015-05-15T20:41:04Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:34 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> This v7 is very similar in content to the v5 [1], except minor formatting\n> adjustments in 'git help' output and recommendations from Eric.\n>\n> rebased on 'next' (a2776d4)\n\nSomething to keep in mind for the future: It's usually easier to\nmanage preparatory cleanup patches by incorporating them into the\nseries which needs/wants them rather than posting them as separate\ntopics. That way, your patch series isn't held hostage by those\nseparate topics. For instance, if your \"whitespace fix\" cleanup patch,\nbf990a2 (command-list.txt: fix whitespace inconsistency, 2015-05-08),\nwhich is already in 'next', had been an early patch in the current\nseries (say patch 1/6), then you wouldn't have had to base this series\non 'next'.\n\n> The major change is in the patch series itself. Commits have been\n> reordered and adjusted so that each 'apply' doesn't break the build, and\n> preserve bisectability.\n\nThanks, the patch organization of this version (v7) looks much better\nthan that of v5.\n\n> Summary: make 'git help' outputs a more usable and friendlier\n> list of commands, grouped by theme according to 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 an existing one\n>\n> work on the current change (see also: git help everyday):\n>    add        Add file contents to the index\n>    mv         Move or rename a file, a directory, or a symlink\n>    reset      Reset current HEAD to the specified state\n>    rm         Remove files from the working tree and from the index\n\nNice. This looks better with the extra indentation dropped[1], and it\nonce again fits my 80-column terminal window.\n\nOne minor bike-shedding observation: The colon \":\" at the end of the\ngroup headings seems unnecessary and a bit redundant with the colon at\nthe end of \"The typical Git workflow includes:\". I think the group\nheadings would read just as well (or a bit better) without the\ntrailing colon, but I don't care strongly.\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268759\n"},{"id":"261375","messageId":"xmqqmw15fu5m.fsf@gitster.dls.corp.google.com","threadId":"39347","inReplyTo":"5556582C.3010409@gmail.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-15T20:44:05Z","receivedAt":"2015-05-15T20:44:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:\n\n>> This is largely just a \"taste\" thing, but with all these backslashes\n>> in the supporting infrastructure you had to add in Makefiles and\n>> scripts, don't you think the choice of the way you designed the\n>> format to use '[commands]' was a rather poor one?  After all, all\n>> you need is a clear separator line for a block of commands and\n>> another block of groups, and there wasn't a reason why you needed to\n>> use square brackets for that, and the sed scripts are suffering from\n>> that poor choice.\n>>\n>> You could for example have used the existing \"# List of known git\n>> commands\" as such a signal to tell that all the no comment lines\n>> below are commands.\n>\n> I tend to think that relying on comments as marks for parsers is brittle,\n> but indeed square brackets get in the way of sed regexes. I'll think of\n> something better. Thanks.\n\nHeh, we, and more importantly our users, already rely on a marker in\ncomments when writing their commit log messages ;-)\n\nI would not be opposed to a new header that is outside comment, but\nI do not think the marker line that is also a comment is \"brittle\"\nand would not be opposed to that, either.\n\n    # do not molest the next line\n    ### command list\n    # name category\n    git-add mainporcelain\n    ...\n\nwould be perfectly acceptable.\n\nI was just pointing out that you did not even have to have patch\n1/5.\n\nThanks.\n"},{"id":"261376","messageId":"xmqqiobtftxk.fsf@gitster.dls.corp.google.com","threadId":"39347","inReplyTo":"CAPig+cTAMrQEfK81WWn3honj5yL5RjYvt13P63kZoZ+pQ1f98g@mail.gmail.com","subject":"Re: [PATCH v7 0/5] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-15T20:48:55Z","receivedAt":"2015-05-15T20:48:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine <sunshine@sunshineco.com> writes:\n\n>> rebased on 'next' (a2776d4)\n>\n> Something to keep in mind for the future: It's usually easier to\n> manage preparatory cleanup patches by incorporating them into the\n> series which needs/wants them rather than posting them as separate\n> topics. That way, your patch series isn't held hostage by those\n> separate topics.\n\nNot a big deal in this case, as I was very well aware that there was\na preparatory change sent, so no harm done to me personally; I even\nasked Sébastien to rebuild on top of that patch.\n\nFor people who are helping to review the series but haven't paid\nattention to everything that was said on the list (read: almost all\nthe people), it would have been better if it said \"depends on\nbf990a2\", instead of saying that it depends on the 'next' as a whole\n(which it doesn't).\n\nThanks.\n"},{"id":"261377","messageId":"55565C31.7060406@gmail.com","threadId":"39347","inReplyTo":"xmqqiobtftxk.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v7 0/5] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T20:50:57Z","receivedAt":"2015-05-15T20:50:57Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"\n\nOn 05/15/2015 10:48 PM, Junio C Hamano wrote:\n> Eric Sunshine <sunshine@sunshineco.com> writes:\n>\n>>> rebased on 'next' (a2776d4)\n>>\n>> Something to keep in mind for the future: It's usually easier to\n>> manage preparatory cleanup patches by incorporating them into the\n>> series which needs/wants them rather than posting them as separate\n>> topics. That way, your patch series isn't held hostage by those\n>> separate topics.\n>\n> Not a big deal in this case, as I was very well aware that there was\n> a preparatory change sent, so no harm done to me personally; I even\n> asked Sébastien to rebuild on top of that patch.\n>\n> For people who are helping to review the series but haven't paid\n> attention to everything that was said on the list (read: almost all\n> the people), it would have been better if it said \"depends on\n> bf990a2\", instead of saying that it depends on the 'next' as a whole\n> (which it doesn't).\n>\n> Thanks.\n>\n\nLesson learnt. I'll mention the commit itself instead of the branch\nfor the next series. Thanks :)\n"},{"id":"261378","messageId":"CAPig+cSjHyh5eO6KWYMo_OxUmDQWP9TnnuaBvnBGWVDh7pesOQ@mail.gmail.com","threadId":"39347","inReplyTo":"xmqqmw15fu5m.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T20:52:19Z","receivedAt":"2015-05-15T20:52:19Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:\n>>> You could for example have used the existing \"# List of known git\n>>> commands\" as such a signal to tell that all the no comment lines\n>>> below are commands.\n>>\n>> I tend to think that relying on comments as marks for parsers is brittle,\n>> but indeed square brackets get in the way of sed regexes. I'll think of\n>> something better. Thanks.\n>\n> Heh, we, and more importantly our users, already rely on a marker in\n> comments when writing their commit log messages ;-)\n>\n> I would not be opposed to a new header that is outside comment, but\n> I do not think the marker line that is also a comment is \"brittle\"\n> and would not be opposed to that, either.\n>\n>     # do not molest the next line\n>     ### command list\n>     # name category\n>     git-add mainporcelain\n>     ...\n>\n> would be perfectly acceptable.\n>\n> I was just pointing out that you did not even have to have patch\n> 1/5.\n\nIs that entirely accurate? The machinery (Makefiles, cmd-list.perl)\ndoes have to be updated at some point to skip the \"common\" block which\nget added in patch 2/5. That work could be done as part of patch 2/5,\nthough it seemed cleaner to me to make it separate (though I don't\ncare too strongly).\n"},{"id":"261379","messageId":"CAPig+cQ3mAAAVUZ=8mMb_siZ20Nw1J-LgkTkF_1FzttKk334NQ@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-2-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T21:15:42Z","receivedAt":"2015-05-15T21:15:42Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> command-list.txt: prepare with [commands] header\n>\n> Add a [commands] header before the actual command list, then make the\n> following files ignore this header in their parsing:\n>\n>         * cmd-list.perl\n>         * Makefile (check-docks target)\n\nWhen these patches are ultimately applied, they won't have the benefit\nof the cover letter to explain the purpose of this change and,\nunfortunately, this commit message is lacking in that respect. The\ncommit message should explain the reason you're making this change\n(\"prepare machinery to deal with upcoming new common group\nspecification\" or such). With a proper explanation, it's not necessary\nto state (as you do above) precisely which bits of machinery you are\nchanging. The patch itself already does that well enough.\n\nMore below.\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/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\n> index d7de5a3..6d772bd 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 common enough to be mentioned in 'git help',\n> +map this command to a common group in the column [common].\n\nI think you meant to fold this change into patch 2/5 where the\n[common] block is actually added. It doesn't make much sense to talk\nabout it here before exists.\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> diff --git a/Makefile b/Makefile\n> index 25a453b..0cb2045 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n\nThis is partly my fault since my original suggestion for how to skip\n[common] and [commands] sections[1] was typed on-the-spot when\ncomposing the mail message, without the context of looking at this\nMakefile, but changing this invocation to use redirection\n(<command-list.txt) rather than a simple argument (command-list.txt)\nseems unwarranted. Worse, it may confuse readers into thinking that\nthere is some important but obscure reason for the change which they\ncannot fathom. Also, the invocation in the hunk just below this one\ndoes not bother with redirection, so use of redirection here seems\ndoubly mysterious.\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268598\n\n>                 grep -q \"^$$v[  ]\" || \\\n>                 case \"$$v\" in \\\n>                 git) ;; \\\n> @@ -2463,6 +2463,7 @@ check-docs::\n>         done; \\\n>         ( \\\n>                 sed -e '/^#/d' \\\n> +                   -e '1,/^\\[commands\\]/d' \\\n\nThis won't work as expected. If you invoke 'check-docs', you'll see\nthis (undesired) output:\n\n    % make check-docs\n    removed but listed: [commands]\n    removed but listed: [common]\n    removed but listed: history\n    removed but listed: info\n    removed but listed: init\n    removed but listed: remote\n    removed but listed: worktree\n    %\n\nwhich is the two [headers] you added plus all the new common group\ntags. To fix, re-order the sed expressions so that 1,/^\\[commands\\]/d\ncomes first:\n\n    sed -e '1,/^\\[commands\\]/d' \\\n        -e '/^#/d' \\\n        ...\n\n>                     -e 's/[     ].*//' \\\n>                     -e 's/^/listed /' command-list.txt; \\\n>                 $(MAKE) -C Documentation print-man1 | \\\n> diff --git a/command-list.txt b/command-list.txt\n> index 54d8d21..caed872 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,5 +1,6 @@\n>  # List of known git commands.\n>  # command name                          category [deprecated] [common]\n> +[commands]\n>  git-add                                 mainporcelain common\n>  git-am                                  mainporcelain\n>  git-annotate                            ancillaryinterrogators\n> --\n> 2.4.0\n"},{"id":"261380","messageId":"CAPig+cSJJroxRF2He4ZvmgijZVw9ULOnUCEWyxGry=--L851YA@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-3-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 2/5] command-list.txt: add a [common] block","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T21:31:45Z","receivedAt":"2015-05-15T21:31:45Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> Add a [common] block at the beginning of command-list.txt:\n\nWithout benefit of the explanation in the cover letter, the reason for\nthis change is a bit mysterious. Even a single sentence preceding this\none could help clarify. Perhaps the above could be rewritten something\nlike this:\n\n    The ultimate goal is for \"git help\" to display common commands in\n    groups rather than alphabetically. As a first step, define the\n    groups in a new [common] block, and then assign a group to each\n    common command.\n\n>     [common]\n>     init         start a working area (see also: git help tutorial)\n>     worktree     work on the current change (see also:[...]\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> storing information about common commands group, then map each common\n> command to a group:\n>\n>     git-add          mainporcelain        common worktree\n\nWith the above rewritten explanation, the rest of the commit message\n(the above examples) becomes pretty much unnecessary and merely\nrepeats what the patch itself already says.\n\n> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\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"},{"id":"261381","messageId":"CAPig+cS+u18AvrFY2Xf+XH9Rma3A-F_bY4frYEx2DZ=MNeFQsQ@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-4-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 3/5] generate-cmdlist: parse common group commands","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T21:34:06Z","receivedAt":"2015-05-15T21:34:06Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> From: Eric Sunshine <sunshine@sunshineco.com>\n>\n> Parse the [common] block to create the array of group descriptions:\n> [...]\n> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\n> new file mode 100644\n> index 0000000..b5cc789\n> --- /dev/null\n> +++ b/generate-cmdlist.awk\n> @@ -0,0 +1,39 @@\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> +       next\n\nIt probably would be best to drop this unnecessary and potentially\nconfusing \"next\" line[1].\n\n[1]: http://thread.gmane.org/gmane.comp.version-control.git/268348/focus=268599\n\n> +}\n> +/\\[common\\]/ {\n> +       state = 1\n> +}\n> +END { print \"};\" }\n"},{"id":"261382","messageId":"CAPig+cRDq7VaBL-KHn4OcNaYW_KbYCH074GkbuCqm=grGadmvQ@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-5-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 4/5] command-list.txt: drop the common tag","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T21:41:05Z","receivedAt":"2015-05-15T21:41:05Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> The parser generate-cmdlist.awk gathers all group information without\n> needing the common tag.\n\nThis might leave the reader wondering why the \"common\" tag was there\nin the first place. I probably would have written it this way:\n\n    command-list.sh, retired in the previous patch, was the only\n    consumer of the \"common\" tag, so drop this now-unnecessary\n    attribute.\n\n> before:\n>     git-add          mainporcelain        common worktree\n>\n> after:\n>     git-add          mainporcelain        worktree\n\nwhich makes this example effectively unnecessary (plus, the patch\nitself already says the same thing).\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/command-list.txt b/command-list.txt\n> index c00b0b6..2203566 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -11,30 +11,30 @@ remote       collaborate (see also: git help workflows)\n>  # List of known git commands.\n>  # command name                          category [deprecated] [common]\n>  [commands]\n> -git-add                                 mainporcelain           common worktree\n> +git-add                                 mainporcelain           worktree\n"},{"id":"261383","messageId":"CAPig+cRpi=pQoEkqvnjn1KJqi7r_N4y-=o-ut4MJ_27CRiftOQ@mail.gmail.com","threadId":"39347","inReplyTo":"1431714904-16599-6-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 5/5] help.c: output the typical Git workflow","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T21:45:07Z","receivedAt":"2015-05-15T21:45:07Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 2:35 PM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> Subject: help.c: output the typical Git workflow\n\nA more meaningful summary might be:\n\n    help: respect new common command grouping\n\nor something.\n\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>\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\nThe remainder of the commit message makes sense, and the patch itself\nlooks good. Thanks.\n\n> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n>  help.c | 24 +++++++++++++++++++++++-\n>  1 file changed, 23 insertions(+), 1 deletion(-)\n>\n> diff --git a/help.c b/help.c\n> index 2072a87..bdb69d1 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -218,17 +218,39 @@ 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> +       int current_grp = -1;\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> +       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> +               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> 2.4.0\n"},{"id":"261384","messageId":"xmqqegmhfpeb.fsf@gitster.dls.corp.google.com","threadId":"39347","inReplyTo":"CAPig+cSjHyh5eO6KWYMo_OxUmDQWP9TnnuaBvnBGWVDh7pesOQ@mail.gmail.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-15T22:26:52Z","receivedAt":"2015-05-15T22:26:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine <sunshine@sunshineco.com> writes:\n\n> On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:\n>> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:\n>>>> You could for example have used the existing \"# List of known git\n>>>> commands\" as such a signal to tell that all the no comment lines\n>>>> below are commands.\n>>>\n>>> I tend to think that relying on comments as marks for parsers is brittle,\n>>> but indeed square brackets get in the way of sed regexes. I'll think of\n>>> something better. Thanks.\n>>\n>> Heh, we, and more importantly our users, already rely on a marker in\n>> comments when writing their commit log messages ;-)\n>>\n>> I would not be opposed to a new header that is outside comment, but\n>> I do not think the marker line that is also a comment is \"brittle\"\n>> and would not be opposed to that, either.\n>>\n>>     # do not molest the next line\n>>     ### command list\n>>     # name category\n>>     git-add mainporcelain\n>>     ...\n>>\n>> would be perfectly acceptable.\n>>\n>> I was just pointing out that you did not even have to have patch\n>> 1/5.\n>\n> Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)\n> does have to be updated at some point to skip the \"common\" block which\n> get added in patch 2/5.\n\nThat is true, but if \"# List of known git commands\" instead of\n[commands] were used as the separator line, 1/5 wouldn't have needed\nany change to the Makefile.\n\nOf course, if you need to add lines that would appear as junk to the\nold parser (e.g. the grouping info), at that point you would of\ncourse need to tell the parser to skip them.\n"},{"id":"261386","messageId":"20150515235534.GA31000@flurp.local","threadId":"39347","inReplyTo":"xmqqegmhfpeb.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-15T23:55:34Z","receivedAt":"2015-05-15T23:55:34Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 15, 2015 at 03:26:52PM -0700, Junio C Hamano wrote:\n> Eric Sunshine <sunshine@sunshineco.com> writes:\n> > On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> >> I was just pointing out that you did not even have to have patch\n> >> 1/5.\n> >\n> > Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)\n> > does have to be updated at some point to skip the \"common\" block which\n> > get added in patch 2/5.\n> \n> That is true, but if \"# List of known git commands\" instead of\n> [commands] were used as the separator line, 1/5 wouldn't have needed\n> any change to the Makefile.\n> \n> Of course, if you need to add lines that would appear as junk to the\n> old parser (e.g. the grouping info), at that point you would of\n> course need to tell the parser to skip them.\n\nRight. Preparing the machinery for the the upcoming \"common\" group\nwas actually the intent of patch 1/5 in the proposal[1]. Introducing\nthe [commands] header at that stage was merely a rather ugly\nimplementation detail of that goal, and I wasn't particularly happy\nabout suggesting it due to its ugliness. Unfortunately, the 1/5\ncommit message didn't clarify the matter. So, your observation of the\nseeming pointlessness of patch 1/5 (which adds the [commands] header\nfor apparently no good reason) is quite understandable.\n\nA more properly focused commit message (along with your suggestion to\nscan for a comment or other separator) might help to salvage 1/5.\nPerhaps something like this:\n\n--- >8 ---\nFrom: Eric Sunshine <sunshine@sunshineco.com>\nSubject: [PATCH 1/5] command-list: prepare machinery for upcoming \"common\n groups\" section\n\nThe ultimate goal is for \"git help\" to classify common commands by\ngroup. Toward this end, a subsequent patch will add a new \"common\ngroups\" section to command-list.txt preceding the actual command list.\nAs preparation, teach existing command-list.txt parsing machinery, which\ndoesn't care about grouping, to skip over this upcoming \"common groups\"\nsection.\n\nSigned-off-by: Eric Sunshine <sunshine@sunshineco.com>\n---\n Documentation/cmd-list.perl | 4 ++++\n Makefile                    | 5 +++--\n command-list.txt            | 3 ++-\n 3 files changed, 9 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 04f9977..5aa73cf 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -38,6 +38,10 @@ sub format_one {\n \t}\n }\n \n+while (<>) {\n+\tlast if /^### command list/;\n+}\n+\n my %cmds = ();\n for (sort <>) {\n \tnext if /^#/;\ndiff --git a/Makefile b/Makefile\nindex 25a453b..5ed0acf 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2454,7 +2454,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,/^### command list/d' -e '/^#/d' command-list.txt | \\\n \t\tgrep -q \"^$$v[ \t]\" || \\\n \t\tcase \"$$v\" in \\\n \t\tgit) ;; \\\n@@ -2462,7 +2462,8 @@ check-docs::\n \t\tesac ; \\\n \tdone; \\\n \t( \\\n-\t\tsed -e '/^#/d' \\\n+\t\tsed -e '1,/^### command list/d' \\\n+\t\t    -e '/^#/d' \\\n \t\t    -e 's/[ \t].*//' \\\n \t\t    -e 's/^/listed /' command-list.txt; \\\n \t\t$(MAKE) -C Documentation print-man1 | \\\ndiff --git a/command-list.txt b/command-list.txt\nindex 54d8d21..609b344 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,4 +1,5 @@\n-# List of known git commands.\n+# do not molest the next line\n+### command list\n # command name                          category [deprecated] [common]\n git-add                                 mainporcelain common\n git-am                                  mainporcelain\n-- \n2.4.1.260.ga2776d4\n\n--- >8 ---\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268756\n"},{"id":"261388","messageId":"55571162.2040803@gmail.com","threadId":"39347","inReplyTo":"CF195F7BDDED481EA064C0C30098017C@PhilipOakley","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-16T09:44:02Z","receivedAt":"2015-05-16T09:44:02Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"\n\nOn 05/16/2015 11:44 AM, Philip Oakley wrote:\n> From: \"Sébastien Guimmara\" <sebastien.guimmara@gmail.com>\n>> Add a [commands] header before the actual command list, then make the\n>> following files ignore this header in their parsing:\n>>\n>> * cmd-list.perl\n>> * Makefile (check-docks target)\n>\n> s/docks/docs/\n> or even fuller as \"(the check-docs target)\"?\n> I'd misunderstood this as (verb) check the doumentation targets within the Makefile, rather than the (definite article) 'check-docs' target within the Makefile ~#L2554.\n> --\n> Philip\n>\n\nThat's right, thanks for pointing that out.\n\n>>\n>> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n>> ---\n>> Documentation/cmd-list.perl         | 4 ++++\n>> Documentation/howto/new-command.txt | 4 +++-\n>> Makefile                            | 3 ++-\n>> command-list.txt                    | 1 +\n>> 4 files changed, 10 insertions(+), 2 deletions(-)\n>>\n>> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\n>> index 04f9977..06a5fd6 100755\n>> --- a/Documentation/cmd-list.perl\n>> +++ b/Documentation/cmd-list.perl\n>> @@ -38,6 +38,10 @@ sub format_one {\n>>  }\n>> }\n>>\n>> +while (<>) {\n>> + last if /^\\[commands\\]/;\n>> +}\n>> +\n>> my %cmds = ();\n>> for (sort <>) {\n>>  next if /^#/;\n>> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\n>> index d7de5a3..6d772bd 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 common enough to be mentioned in 'git help',\n>> +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>> diff --git a/Makefile b/Makefile\n>> index 25a453b..0cb2045 100644\n>> --- a/Makefile\n>> +++ b/Makefile\n>> @@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n>>  grep -q \"^$$v[ ]\" || \\\n>>  case \"$$v\" in \\\n>>  git) ;; \\\n>> @@ -2463,6 +2463,7 @@ check-docs::\n>>  done; \\\n>>  ( \\\n>>  sed -e '/^#/d' \\\n>> +     -e '1,/^\\[commands\\]/d' \\\n>>      -e 's/[ ].*//' \\\n>>      -e 's/^/listed /' command-list.txt; \\\n>>  $(MAKE) -C Documentation print-man1 | \\\n>> diff --git a/command-list.txt b/command-list.txt\n>> index 54d8d21..caed872 100644\n>> --- a/command-list.txt\n>> +++ b/command-list.txt\n>> @@ -1,5 +1,6 @@\n>> # List of known git commands.\n>> # command name                          category [deprecated] [common]\n>> +[commands]\n>> git-add                                 mainporcelain common\n>> git-am                                  mainporcelain\n>> git-annotate                            ancillaryinterrogators\n>> --\n>> 2.4.0\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n>\n"},{"id":"261387","messageId":"CF195F7BDDED481EA064C0C30098017C@PhilipOakley","threadId":"39347","inReplyTo":"1431714904-16599-2-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-16T09:44:04Z","receivedAt":"2015-05-16T09:44:04Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Sébastien Guimmara\" <sebastien.guimmara@gmail.com>\n> Add a [commands] header before the actual command list, then make the\n> following files ignore this header in their parsing:\n>\n> * cmd-list.perl\n> * Makefile (check-docks target)\n\ns/docks/docs/\nor even fuller as \"(the check-docs target)\"?\nI'd misunderstood this as (verb) check the doumentation targets within \nthe Makefile, rather than the (definite article) 'check-docs' target \nwithin the Makefile ~#L2554.\n--\nPhilip\n\n>\n> Helped-by: Eric Sunshine <sunshine@sunshineco.com>\n> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> Documentation/cmd-list.perl         | 4 ++++\n> Documentation/howto/new-command.txt | 4 +++-\n> Makefile                            | 3 ++-\n> command-list.txt                    | 1 +\n> 4 files changed, 10 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\n> index 04f9977..06a5fd6 100755\n> --- a/Documentation/cmd-list.perl\n> +++ b/Documentation/cmd-list.perl\n> @@ -38,6 +38,10 @@ sub format_one {\n>  }\n> }\n>\n> +while (<>) {\n> + last if /^\\[commands\\]/;\n> +}\n> +\n> my %cmds = ();\n> for (sort <>) {\n>  next if /^#/;\n> diff --git a/Documentation/howto/new-command.txt \n> b/Documentation/howto/new-command.txt\n> index d7de5a3..6d772bd 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 \n> 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 common enough to be mentioned in 'git \n> help',\n> +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> diff --git a/Makefile b/Makefile\n> index 25a453b..0cb2045 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -2454,7 +2454,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' -e '/^#/d' <command-list.txt | \\\n>  grep -q \"^$$v[ ]\" || \\\n>  case \"$$v\" in \\\n>  git) ;; \\\n> @@ -2463,6 +2463,7 @@ check-docs::\n>  done; \\\n>  ( \\\n>  sed -e '/^#/d' \\\n> +     -e '1,/^\\[commands\\]/d' \\\n>      -e 's/[ ].*//' \\\n>      -e 's/^/listed /' command-list.txt; \\\n>  $(MAKE) -C Documentation print-man1 | \\\n> diff --git a/command-list.txt b/command-list.txt\n> index 54d8d21..caed872 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,5 +1,6 @@\n> # List of known git commands.\n> # command name                          category [deprecated] [common]\n> +[commands]\n> git-add                                 mainporcelain common\n> git-am                                  mainporcelain\n> git-annotate                            ancillaryinterrogators\n> -- \n> 2.4.0\n"},{"id":"261475","messageId":"loom.20150518T182149-998@post.gmane.org","threadId":"39347","inReplyTo":"20150515235534.GA31000@flurp.local","subject":"Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-18T16:25:10Z","receivedAt":"2015-05-18T16:25:10Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Eric Sunshine <sunshine <at> sunshineco.com> writes:\n\n> \n> Perhaps something like this:\n> \n\n\nGreat, I'll look into this for the v8. Thanks :)\n"}]}