{"thread":{"id":"39394","subject":"[PATCH v10 0/5] group common commands by theme","startedAt":"2015-05-21T13:13:04Z","lastAt":"2015-05-21T17:15:26Z","messageCount":13,"participants":["Sébastien Guimmara","Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":10,"patchTotal":5},"messages":[{"id":"261777","messageId":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":null,"subject":"[PATCH v10 0/5] group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:04Z","receivedAt":"2015-05-21T13:13:04Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Same as v9 [1], with: \n\n* command-list.txt: reduce verbosity by squashing the two header lines\n  into one:\n\n    ### command list (do not change this line)\n\n* include a missing update to new-command.txt.\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/269496\n\nEric Sunshine (2):\n  command-list: prepare machinery for upcoming \"common groups\" section\n  generate-cmdlist: parse common group commands\n\nSébastien Guimmara (3):\n  command-list.txt: add the common groups block\n  command-list.txt: drop the \"common\" tag\n  help: respect new common command grouping\n\n Documentation/cmd-list.perl         |  4 +++\n Documentation/howto/new-command.txt |  4 ++-\n Makefile                            |  9 ++++---\n command-list.txt                    | 53 ++++++++++++++++++++++---------------\n generate-cmdlist.perl               | 50 ++++++++++++++++++++++++++++++++++\n generate-cmdlist.sh                 | 23 ----------------\n help.c                              | 24 ++++++++++++++++-\n 7 files changed, 117 insertions(+), 50 deletions(-)\n create mode 100755 generate-cmdlist.perl\n delete mode 100755 generate-cmdlist.sh\n\n-- \n2.4.0.GIT\n"},{"id":"261778","messageId":"1432213989-3932-2-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v10 1/5] command-list: prepare machinery for upcoming \"common groups\" section","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:05Z","receivedAt":"2015-05-21T13:13:05Z","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\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>\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                            | 5 +++--\n command-list.txt                    | 2 +-\n 4 files changed, 11 insertions(+), 4 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/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 323c401..655740d 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2455,7 +2455,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@@ -2463,7 +2463,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..181a9c2 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,4 +1,4 @@\n-# List of known git commands.\n+### command list (do not change this line)\n # command name                          category [deprecated] [common]\n git-add                                 mainporcelain common\n git-am                                  mainporcelain\n-- \n2.4.0.GIT\n"},{"id":"261779","messageId":"1432213989-3932-3-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v10 2/5] command-list.txt: add the common groups block","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:06Z","receivedAt":"2015-05-21T13:13:06Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"The ultimate goal is for \"git help\" to display common commands in\ngroups rather than alphabetically. As a first step, define the\ngroups in a new block, and then assign a group to each\ncommon command.\n\nAdd a block at the beginning of command-list.txt:\n\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 | 51 +++++++++++++++++++++++++++++++--------------------\n 1 file changed, 31 insertions(+), 20 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex 181a9c2..32ddab3 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,3 +1,14 @@\n+# common commands are grouped by themes\n+# these groups are output by 'git help' in the order declared here.\n+# map each common command in the command list to one of these groups.\n+### common groups (do not change this line)\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 list (do not change this line)\n # command name                          category [deprecated] [common]\n git-add                                 mainporcelain common\n@@ -6,24 +17,24 @@ 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@@ -35,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@@ -51,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@@ -60,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@@ -79,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@@ -90,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@@ -103,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.GIT\n"},{"id":"261780","messageId":"1432213989-3932-4-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v10 3/5] generate-cmdlist: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:07Z","receivedAt":"2015-05-21T13:13:07Z","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 group 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 the group block 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.perl | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++\n generate-cmdlist.sh   | 23 -----------------------\n 3 files changed, 52 insertions(+), 25 deletions(-)\n create mode 100755 generate-cmdlist.perl\n delete mode 100755 generate-cmdlist.sh\n\ndiff --git a/Makefile b/Makefile\nindex 655740d..54ec511 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1694,10 +1694,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.perl command-list.txt\n \n common-cmds.h: $(wildcard Documentation/git-*.txt)\n-\t$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n+\t$(QUIET_GEN)$(PERL_PATH) generate-cmdlist.perl 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.perl b/generate-cmdlist.perl\nnew file mode 100755\nindex 0000000..31516e3\n--- /dev/null\n+++ b/generate-cmdlist.perl\n@@ -0,0 +1,50 @@\n+#!/usr/bin/perl\n+use strict;\n+use warnings;\n+\n+print <<\"EOT\";\n+/* Automatically generated by $0 */\n+\n+struct cmdname_help {\n+\tchar name[16];\n+\tchar help[80];\n+\tunsigned char group;\n+};\n+\n+static char *common_cmd_groups[] = {\n+EOT\n+\n+my $n = 0;\n+my %grp;\n+while (<>) {\n+\tlast if /^### command list/;\n+\tnext if (1../^### common groups/) || /^#/ || /^\\s*$/;\n+\tchop;\n+\tmy ($k, $v) = split ' ', $_, 2;\n+\t$grp{$k} = $n++;\n+\tprint \"\\tN_(\\\"$v\\\"),\\n\";\n+}\n+\n+print \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\\n\";\n+\n+while (<>) {\n+\tnext if /^#/ || /^\\s*$/;\n+\tmy @tags = split;\n+\tmy $cmd = shift @tags;\n+\tfor my $t (@tags) {\n+\t\tif (exists $grp{$t}) {\n+\t\t\tmy $s;\n+\t\t\topen my $f, '<', \"Documentation/$cmd.txt\" or die;\n+\t\t\twhile (<$f>) {\n+\t\t\t\t($s) = /^$cmd - (.+)$/;\n+\t\t\t\tlast if $s;\n+\t\t\t}\n+\t\t\tclose $f;\n+\t\t\t$cmd =~ s/^git-//;\n+\t\t\tprint \"\\t{\\\"$cmd\\\", N_(\\\"$s\\\"), $grp{$t}},\\n\";\n+\t\t\tlast;\n+\t\t}\n+\t}\n+}\n+\n+print \"};\\n\";\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.GIT\n"},{"id":"261781","messageId":"1432213989-3932-5-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v10 4/5] command-list.txt: drop the \"common\" tag","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:08Z","receivedAt":"2015-05-21T13:13:08Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"command-list.sh, retired in the previous patch, was the only\nconsumer of the \"common\" tag, so drop this now-unnecessary\nattribute.\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 32ddab3..9a98752 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 list (do not change this line)\n # command name                          category [deprecated] [common]\n-git-add                                 mainporcelain common\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.GIT\n"},{"id":"261782","messageId":"1432213989-3932-6-git-send-email-sebastien.guimmara@gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH v10 5/5] help: respect new common command grouping","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:13:09Z","receivedAt":"2015-05-21T13:13:09Z","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\nThese are common Git commands used in various situations:\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>\nHelped-by: Ramsay Jones <ramsay@ramsay1.demon.co.uk>\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..8f72051 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+static 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(_(\"These are common Git commands used in various situations:\"));\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.GIT\n"},{"id":"261785","messageId":"CAPig+cTV2pm5+76H_jh0WBJ-NeOOP=aMOAwg7kmdp_dqO1LV+w@mail.gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-2-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming \"common groups\" section","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-21T13:48:49Z","receivedAt":"2015-05-21T13:48:49Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> From: Eric Sunshine <sunshine@sunshineco.com>\n>\n> The ultimate goal is for \"git help\" to classify common commands by\n> group. Toward this end, a subsequent patch will add a new \"common\n> groups\" section to command-list.txt preceding the actual command list.\n> As preparation, teach existing command-list.txt parsing machinery, which\n> doesn't care about grouping, to skip over this upcoming \"common groups\"\n> section.\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/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\n> index 04f9977..5aa73cf 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 /^### command list/;\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\nI think you meant to squash the documentation update into patch 2/5\nwhere the \"common groups\" block is actually introduced. It doesn't\nreally belong in this patch which is about updating machinery in\npreparation for the new block.\n\nAlso, it's now spelled \"### common groups\" rather than \"[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 323c401..655740d 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -2455,7 +2455,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,/^### command list/d' -e '/^#/d' command-list.txt | \\\n>                 grep -q \"^$$v[  ]\" || \\\n>                 case \"$$v\" in \\\n>                 git) ;; \\\n> @@ -2463,7 +2463,8 @@ check-docs::\n>                 esac ; \\\n>         done; \\\n>         ( \\\n> -               sed -e '/^#/d' \\\n> +               sed -e '1,/^### command list/d' \\\n> +                   -e '/^#/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..181a9c2 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,4 +1,4 @@\n> -# List of known git commands.\n> +### command list (do not change this line)\n>  # command name                          category [deprecated] [common]\n>  git-add                                 mainporcelain common\n>  git-am                                  mainporcelain\n> --\n> 2.4.0.GIT\n"},{"id":"261786","messageId":"555DE3DB.1000406@gmail.com","threadId":"39394","inReplyTo":"CAPig+cTV2pm5+76H_jh0WBJ-NeOOP=aMOAwg7kmdp_dqO1LV+w@mail.gmail.com","subject":"Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming \"common groups\" section","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-21T13:55:39Z","receivedAt":"2015-05-21T13:55:39Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"\n\nOn 05/21/2015 03:48 PM, Eric Sunshine wrote:\n> On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara\n> <sebastien.guimmara@gmail.com> wrote:\n>> From: Eric Sunshine <sunshine@sunshineco.com>\n>>\n>> The ultimate goal is for \"git help\" to classify common commands by\n>> group. Toward this end, a subsequent patch will add a new \"common\n>> groups\" section to command-list.txt preceding the actual command list.\n>> As preparation, teach existing command-list.txt parsing machinery, which\n>> doesn't care about grouping, to skip over this upcoming \"common groups\"\n>> section.\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/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\n>> index 04f9977..5aa73cf 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 /^### command list/;\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> I think you meant to squash the documentation update into patch 2/5\n> where the \"common groups\" block is actually introduced. It doesn't\n> really belong in this patch which is about updating machinery in\n> preparation for the new block.\n\nI don't mind squashing it with another commit, but in this case, wouldn't it\nmake more sense to squash it with 4/5, when the 'common' tag is removed and the\nfile is in its final form ?\n\n>\n> Also, it's now spelled \"### common groups\" rather than \"[common]\".\n>\n\nactually, this [common] is not the one I added in a previous series,\nbut the one that was already present:\n\n# command name      category [deprecated] [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 323c401..655740d 100644\n>> --- a/Makefile\n>> +++ b/Makefile\n>> @@ -2455,7 +2455,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,/^### command list/d' -e '/^#/d' command-list.txt | \\\n>>                  grep -q \"^$$v[  ]\" || \\\n>>                  case \"$$v\" in \\\n>>                  git) ;; \\\n>> @@ -2463,7 +2463,8 @@ check-docs::\n>>                  esac ; \\\n>>          done; \\\n>>          ( \\\n>> -               sed -e '/^#/d' \\\n>> +               sed -e '1,/^### command list/d' \\\n>> +                   -e '/^#/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..181a9c2 100644\n>> --- a/command-list.txt\n>> +++ b/command-list.txt\n>> @@ -1,4 +1,4 @@\n>> -# List of known git commands.\n>> +### command list (do not change this line)\n>>   # command name                          category [deprecated] [common]\n>>   git-add                                 mainporcelain common\n>>   git-am                                  mainporcelain\n>> --\n>> 2.4.0.GIT\n"},{"id":"261788","messageId":"CAPig+cSegd8P5vFAmmLNU_YDTuk6HXqoGtEi2qUTR+61vDv3ww@mail.gmail.com","threadId":"39394","inReplyTo":"555DE3DB.1000406@gmail.com","subject":"Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming \"common groups\" section","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-21T14:16:02Z","receivedAt":"2015-05-21T14:16:02Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 21, 2015 at 9:55 AM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> On 05/21/2015 03:48 PM, Eric Sunshine wrote:\n>> On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara\n>> <sebastien.guimmara@gmail.com> wrote:\n>>> The ultimate goal is for \"git help\" to classify common commands by\n>>> group. Toward this end, a subsequent patch will add a new \"common\n>>> groups\" section to command-list.txt preceding the actual command list.\n>>> As preparation, teach existing command-list.txt parsing machinery, which\n>>> doesn't care about grouping, to skip over this upcoming \"common groups\"\n>>> section.\n>>>\n>>> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>\n>>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n>>> ---\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>> I think you meant to squash the documentation update into patch 2/5\n>> where the \"common groups\" block is actually introduced. It doesn't\n>> really belong in this patch which is about updating machinery in\n>> preparation for the new block.\n>\n> I don't mind squashing it with another commit, but in this case, wouldn't it\n> make more sense to squash it with 4/5, when the 'common' tag is removed and\n> the file is in its final form ?\n\nIn my mind, the most logical point at which the documentation should\nstart talking about the new \"common coups\" is when \"common groups\"\nactually comes into existence since the new documentation is directly\nrelated to birth of that new section of the file. The documentation\nupdate is, at best, only very peripherally related to removal of the\nold 'common' tag, so it doesn't really seem logical to tie the\ndocumentation update to 'common' removal in 4/5. But that's just my\nopinion...\n\n>> Also, it's now spelled \"### common groups\" rather than \"[common]\".\n>\n> actually, this [common] is not the one I added in a previous series,\n> but the one that was already present:\n>\n> # command name      category [deprecated] [common]\n\nAh, right. Thanks for clarifying.\n"},{"id":"261789","messageId":"CAPig+cRX9_1h4W6sWxb22FF3Hwgqx2f=hK=tQkfTUdkTJiQo-w@mail.gmail.com","threadId":"39394","inReplyTo":"1432213989-3932-6-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH v10 5/5] help: respect new common command grouping","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-21T14:29:05Z","receivedAt":"2015-05-21T14:29:05Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara\n<sebastien.guimmara@gmail.com> wrote:\n> 'git help' shows common commands in alphabetical order:\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> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>\n> ---\n> diff --git a/help.c b/help.c\n> index 2072a87..8f72051 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,\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(_(\"These are common Git commands used in various situations:\"));\n\nThe clause \"in various situations\" is quite nebulous and thus adds no\nsubstance. If you remove it, then you're effectively left with the\noriginal\n\n    \"The most commonly used git commands are:\"\n\nwhich reads just as well or better and has the attribute of being more\nconcise. I'd opt to drop this change and just keep the original\nwording.\n\nOther than that minor observation, the patch looks fine.\n\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.GIT\n"},{"id":"261796","messageId":"xmqqiobllxdk.fsf@gitster.dls.corp.google.com","threadId":"39394","inReplyTo":"CAPig+cRX9_1h4W6sWxb22FF3Hwgqx2f=hK=tQkfTUdkTJiQo-w@mail.gmail.com","subject":"Re: [PATCH v10 5/5] help: respect new common command grouping","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-21T16:16:07Z","receivedAt":"2015-05-21T16:16:07Z","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>> +\n>> +       puts(_(\"These are common Git commands used in various situations:\"));\n>\n> The clause \"in various situations\" is quite nebulous and thus adds no\n> substance.\n\nFWIW I view the latter half of that sentence as explaining the group\nlabels which we did not have (so we did not have to mention in the\noriginal).  Perhaps swapping the order may clarify, as the list\nitself is a two-level, i.e. list of workflow elements, each of which\nhas list of commands?\n"},{"id":"261801","messageId":"CAPig+cT65MpPYaE4BxajMNU2N=rf6QQzsxDsc7fV-_GMPVcdhw@mail.gmail.com","threadId":"39394","inReplyTo":"xmqqiobllxdk.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v10 5/5] help: respect new common command grouping","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-21T16:46:53Z","receivedAt":"2015-05-21T16:46:53Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 21, 2015 at 12:16 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Eric Sunshine <sunshine@sunshineco.com> writes:\n>>> +       puts(_(\"These are common Git commands used in various situations:\"));\n>>\n>> The clause \"in various situations\" is quite nebulous and thus adds no\n>> substance.\n>\n> FWIW I view the latter half of that sentence as explaining the group\n> labels which we did not have (so we did not have to mention in the\n> original).\n\nHmm, but is it necessary to explain the group labels in the first\nplace? The help output (group labels and all) seems self-explanatory\nalready, and one would expect (hope) that readers are intelligent\nenough to understand implicitly that the group labels are a simple\norganizational aid. If that understanding is indeed implicit, then\nthere should be no need to declare it explicitly and \"in various\nsituations\" becomes mere noise.\n\n> Perhaps swapping the order may clarify, as the list\n> itself is a two-level, i.e. list of workflow elements, each of which\n> has list of commands?\n\nPerhaps, but I may not be the best judge of that since, to me, that\nlevel of hand-holding seems unnecessary.\n\nAnyhow, it's just a minor observation, and it's something people can\nargue later if they feel strongly about it, so I don't think it should\nhold up this patch series.\n"},{"id":"261808","messageId":"xmqqsiapkg29.fsf@gitster.dls.corp.google.com","threadId":"39394","inReplyTo":"CAPig+cT65MpPYaE4BxajMNU2N=rf6QQzsxDsc7fV-_GMPVcdhw@mail.gmail.com","subject":"Re: [PATCH v10 5/5] help: respect new common command grouping","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-21T17:15:26Z","receivedAt":"2015-05-21T17:15:26Z","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> Hmm, but is it necessary to explain the group labels in the first\n> place? The help output (group labels and all) seems self-explanatory\n> already, and one would expect (hope) that readers are intelligent\n> enough to understand implicitly that the group labels are a simple\n> organizational aid.\n\nI am not so sure about that.  For one thing, the groups are not\nexhaustive enumeration of all the workflow elements, but just a list\nof the more common ones.  I think the target audience of this round,\nwhich is different from the target audience of the \"alphabetical\nlist\", range from those who do not have a clue where to start and do\nnot know how their work that revolves around use of Git could be\nstructured.  And \"not yet being familiar with the way how things are\noften done with Git\" is certainly different from them being \"not\nintelligent enough\".\n\nMore experienced people can do without the explanation, or without\ngrouping for that matter.  We are not the target audiences.\n\n> Anyhow, it's just a minor observation, and it's something people can\n> argue later if they feel strongly about it, so I don't think it should\n> hold up this patch series.\n\nYeah, I agree with that.\n"}]}