{"thread":{"id":"39216","subject":"[PATCH v2 1/3] git help: group common commands by theme","startedAt":"2015-05-01T23:01:41Z","lastAt":"2015-05-03T22:32:35Z","messageCount":28,"participants":["Sébastien Guimmara","Luke Diamand","Andreas Schwab","Junio C Hamano","Eric Sunshine"],"isPatch":true,"patchVersion":2,"patchTotal":3},"messages":[{"id":"260396","messageId":"554405D5.9080702@gmail.com","threadId":"39216","inReplyTo":null,"subject":"[PATCH v2 1/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-01T23:01:41Z","receivedAt":"2015-05-01T23:01:41Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"This v2 contains exactly the same patches but this time they are \nproperly formatted using format-patch.\n\nGroup the common commands printed by 'git help' (or 'git' without any \noptions) a beginner's friendly themes. To achieve this, the file \ncommand-list.txt receives an additional information for all 'common' \ncommands, in the form of an indexed group suffix.\n\nGroup suffixes are in the form: 'x_group', where x is a number used to \norder (ascending) commands in the displayed help:\n\n[...]\n\ngit-add mainporcelain common-3_worktree\ngit-bisect mainporcelain common-7_search\ngit-branch mainporcelain common-6_branching\ngit-checkout mainporcelain common-6_branching\n\n[...]\n\nNote: the proposed layout comprises:\n\n1_init\n2_info\n3_worktree\n4_remote\n5_history\n6_branching\n7_search\n\nBut they can be easily modified by just changing command-list.txt\n\ncommand-list.txt is then parsed by generate-cmdlist.sh to generate \ncommon-cmds.h with the additional group name being a 'group' field in \nthe cmdname_help struct:\n\n[...]\n\n {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n {\"bisect\", N_(\"Find by binary search the change that introduced a \nbug\"), \"7_search\"},\n {\"branch\", N_(\"List, create, or delete branches\"), \"6_branching\"},\n {\"checkout\", N_(\"Checkout a branch or paths to the working tree\"), \n\"6_branching\"},\n\n[...]\n\nFinally, list_common_cmds_help() prints those common commands by groups, \nskipping a line between each group:\n\n[...]\n\nThe most commonly used git commands are:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an \nexisting one\n\n log Show commit logs\n show Show various types of objects\n status Show the working tree status\n\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 fetch Download objects and refs from another repository\n pull Fetch from and integrate with another repository or a \nlocal branch\n push Update remote refs along with associated objects\n\n commit Record changes to the repository\n diff Show changes between commits, commit and working tree, etc\n rebase Forward-port local commits to the updated upstream head\n tag Create, list, delete or verify a tag object signed with GPG\n\n[...]\n\n\nSigned-off-by: Sébastien Guimmara \n\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 f1eae08..b0730a2 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,29 +1,29 @@\n # List of known git commands.\n # command name category [deprecated] [common]\n-git-add mainporcelain common\n+git-add mainporcelain common-3_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-7_search\n git-blame ancillaryinterrogators\n-git-branch mainporcelain common\n+git-branch mainporcelain common-6_branching\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-6_branching\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-1_init\n git-column purehelpers\n-git-commit mainporcelain common\n+git-commit mainporcelain common-5_history\n git-commit-tree plumbingmanipulators\n git-config ancillarymanipulators\n git-count-objects ancillaryinterrogators\n@@ -35,14 +35,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-5_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-4_remote\n git-fetch-pack synchingrepositories\n git-filter-branch ancillarymanipulators\n git-fmt-merge-msg purehelpers\n@@ -51,7 +51,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-7_search\n git-gui mainporcelain\n git-hash-object plumbingmanipulators\n git-help ancillaryinterrogators\n@@ -60,17 +60,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-1_init\n git-instaweb ancillaryinterrogators\n git-interpret-trailers purehelpers\n gitk mainporcelain\n-git-log mainporcelain common\n+git-log mainporcelain common-2_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-6_branching\n git-merge-base plumbinginterrogators\n git-merge-file plumbingmanipulators\n git-merge-index plumbingmanipulators\n@@ -79,7 +79,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-3_worktree\n git-name-rev plumbinginterrogators\n git-notes mainporcelain\n git-p4 foreignscminterface\n@@ -90,11 +90,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-4_remote\n+git-push mainporcelain common-4_remote\n git-quiltimport foreignscminterface\n git-read-tree plumbingmanipulators\n-git-rebase mainporcelain common\n+git-rebase mainporcelain common-5_history\n git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n@@ -103,28 +103,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-3_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-3_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-2_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-2_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-5_history\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n-- \n2.4.0\n"},{"id":"260397","messageId":"554406FC.8010309@gmail.com","threadId":"39216","inReplyTo":"554405D5.9080702@gmail.com","subject":"[PATCH v2 2/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-01T23:06:36Z","receivedAt":"2015-05-01T23:06:36Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Extract the $grp shell variable from command-list.txt (eg: \n'common-3_worktree') and add\nthis value to the output:\n\nbefore/after:\n{\"add\", N_(\"Add file contents to the index\")}\n{\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"}\n\nSo that when 'git' is called, we can display common commands grouped by\ntheme instead of a less useful alphabetical order.\n\nSigned-off by Sébastien Guimmara \n---\n generate-cmdlist.sh | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\nindex 9a4c9b9..818b2f3 100755\n--- a/generate-cmdlist.sh\n+++ b/generate-cmdlist.sh\n@@ -4,19 +4,22 @@ echo \"/* Automatically generated by $0 */\n struct cmdname_help {\n char name[16];\n char help[80];\n+ char group[20];\n };\n\n static struct cmdname_help common_cmds[] = {\"\n\n-sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' command-list.txt |\n+sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p' \ncommand-list.txt |\n sort |\n-while read cmd\n+while read line\n do\n+ cmd=`echo $line | cut -d ':' -f 1`\n+ grp=`echo $line | cut -d ':' -f 2`\n sed -n '\n /^NAME/,/git-'\"$cmd\"'/H\n ${\n x\n- s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n+ s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\"), \"'\"$grp\"'\"},/\n p\n }' \"Documentation/git-$cmd.txt\"\n done\n-- \n2.4.0\n"},{"id":"260398","messageId":"55440852.4000500@gmail.com","threadId":"39216","inReplyTo":"554405D5.9080702@gmail.com","subject":"[PATCH v2 3/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-01T23:12:18Z","receivedAt":"2015-05-01T23:12:18Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"help.c - group common commands by theme\n\nUse qsort to sort the common_cmds array by group name,\nthen print those common commands, skipping a line between each group.\n\nSigned-off-by: Sébastien Guimmara \n\n---\n help.c | 21 +++++++++++++++++++++\n 1 file changed, 21 insertions(+)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..2169a59 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,\n }\n }\n\n+/* sort the command name struct by group name */\n+int cmd_group_cmp(const void *elem1, const void *elem2)\n+{\n+ struct cmdname_help *cmd1 = (struct cmdname_help*) elem1;\n+ struct cmdname_help *cmd2 = (struct cmdname_help*) elem2;\n+\n+ return strcmp(cmd1->group, cmd2->group);\n+}\n+\n void list_common_cmds_help(void)\n {\n int i, longest = 0;\n+ char *current_grp = NULL;\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+ /* sort common commands by group (i.e, beginner's relevance) */\n+ qsort(common_cmds, ARRAY_SIZE(common_cmds),\n+ sizeof(struct cmdname_help), cmd_group_cmp);\n+\n puts(_(\"The most commonly used git commands are:\"));\n for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n+\n+ /* skip a line each time we encounter a new command group */\n+ if (current_grp != NULL && strcmp(common_cmds[i].group, \ncurrent_grp))\n+ printf(\"\\n\");\n+\n+ current_grp = common_cmds[i].group;\n+\n printf(\" %s \", common_cmds[i].name);\n mput_char(' ', longest - strlen(common_cmds[i].name));\n puts(_(common_cmds[i].help));\n-- \n2.4.0\n"},{"id":"260417","messageId":"CAE5ih78xxHj-YZVnNB=kNw5ZOkT1t2dcc5yjiUWemEQpwFQfDw@mail.gmail.com","threadId":"39216","inReplyTo":"554406FC.8010309@gmail.com","subject":"Re: [PATCH v2 2/3] git help: group common commands by theme","fromName":"Luke Diamand","fromEmail":"luke@diamand.org","sentAt":"2015-05-02T06:32:51Z","receivedAt":"2015-05-02T06:32:51Z","isPatch":true,"sender":{"key":"luke@diamand.org","avatar":"https://avatars.githubusercontent.com/u/5330967?v=4"},"body":"Hi!\n\nOn 2 May 2015 at 00:06, Sébastien Guimmara wrote:\n> Extract the $grp shell variable from command-list.txt (eg:\n> 'common-3_worktree') and add\n> this value to the output:\n>\n> before/after:\n> {\"add\", N_(\"Add file contents to the index\")}\n> {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"}\n>\n> So that when 'git' is called, we can display common commands grouped by\n> theme instead of a less useful alphabetical order.\n\nSeems sensible to me but I'm no expert :-)\n\n>\n> Signed-off by Sébastien Guimmara \n> ---\n> generate-cmdlist.sh | 9 ++++++---\n> 1 file changed, 6 insertions(+), 3 deletions(-)\n>\n>\n> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n> index 9a4c9b9..818b2f3 100755\n> --- a/generate-cmdlist.sh\n> +++ b/generate-cmdlist.sh\n> @@ -4,19 +4,22 @@ echo \"/* Automatically generated by $0 */\n> struct cmdname_help {\n> char name[16];\n> char help[80];\n> + char group[20];\n\nIs 20 chars long enough? git-p4 shows up as \"foreignscminterface\"\nwhich is pretty close to that limit.\n\n> };\n>\n> static struct cmdname_help common_cmds[] = {\"\n>\n> -sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' command-list.txt |\n> +sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p'\n> command-list.txt |\n> sort |\n> -while read cmd\n> +while read line\n> do\n> + cmd=`echo $line | cut -d ':' -f 1`\n> + grp=`echo $line | cut -d ':' -f 2`\n\nShould this use $(...) rather than `...` ?\ni.e.\ncmd=$(echo $(line | cut -d : -f 1)\n\n(And I don't think you need the quotes around the ':'.\n\nLuke\n"},{"id":"260424","messageId":"5544B059.20901@gmail.com","threadId":"39216","inReplyTo":"CAE5ih78xxHj-YZVnNB=kNw5ZOkT1t2dcc5yjiUWemEQpwFQfDw@mail.gmail.com","subject":"Re: [PATCH v2 2/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-02T11:09:13Z","receivedAt":"2015-05-02T11:09:13Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Hello,\n\nOn 05/02/2015 08:32 AM, Luke Diamand wrote:\n>> Signed-off by Sébastien Guimmara \n>> ---\n>> generate-cmdlist.sh | 9 ++++++---\n>> 1 file changed, 6 insertions(+), 3 deletions(-)\n>>\n>>\n>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n>> index 9a4c9b9..818b2f3 100755\n>> --- a/generate-cmdlist.sh\n>> +++ b/generate-cmdlist.sh\n>> @@ -4,19 +4,22 @@ echo \"/* Automatically generated by $0 */\n>> struct cmdname_help {\n>> char name[16];\n>> char help[80];\n>> + char group[20];\n> Is 20 chars long enough? git-p4 shows up as \"foreignscminterface\"\n> which is pretty close to that limit.\n\nThis 'foreignscminterface' is actually a category in the 2nd column\nof the file (like 'porcelain'). It is unrelated to common command\ngroups (3rd column). Since those group names are not meant to be printed,\nI guess it is sufficient to keep them short.\n>> };\n>>\n>> static struct cmdname_help common_cmds[] = {\"\n>>\n>> -sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' command-list.txt |\n>> +sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p'\n>> command-list.txt |\n>> sort |\n>> -while read cmd\n>> +while read line\n>> do\n>> + cmd=`echo $line | cut -d ':' -f 1`\n>> + grp=`echo $line | cut -d ':' -f 2`\n> Should this use $(...) rather than `...` ?\n> i.e.\n> cmd=$(echo $(line | cut -d : -f 1)\n>\n> (And I don't think you need the quotes around the ':'.\n>\n> Luke\nIndeed, the quotes are unnecessary and $(...) seems to be more\nappropriate too.\nI'll update the patch.\n\nThank you,\n\nSébastien\n"},{"id":"260425","messageId":"87wq0rb3xk.fsf@igel.home","threadId":"39216","inReplyTo":"CAE5ih78xxHj-YZVnNB=kNw5ZOkT1t2dcc5yjiUWemEQpwFQfDw@mail.gmail.com","subject":"Re: [PATCH v2 2/3] git help: group common commands by theme","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2015-05-02T11:43:19Z","receivedAt":"2015-05-02T11:43:19Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Luke Diamand writes:\n\n>> };\n>>\n>> static struct cmdname_help common_cmds[] = {\"\n>>\n>> -sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' command-list.txt |\n>> +sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p'\n>> command-list.txt |\n>> sort |\n>> -while read cmd\n>> +while read line\n>> do\n>> + cmd=`echo $line | cut -d ':' -f 1`\n>> + grp=`echo $line | cut -d ':' -f 2`\n>\n> Should this use $(...) rather than `...` ?\n> i.e.\n> cmd=$(echo $(line | cut -d : -f 1)\n\nThere are various ways to do that without a command substitution, eg:\n\n cmd=${line%%:*}\n grp=${line#:*}\n\nor:\n\n IFS=:\n set $line\n cmd=$1 grp=$2\n\nor:\n\n sort |\n while IFS=: read cmd grp\n do\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"260426","messageId":"5544BA83.6000506@gmail.com","threadId":"39216","inReplyTo":"87wq0rb3xk.fsf@igel.home","subject":"Re: [PATCH v2 2/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-02T11:52:35Z","receivedAt":"2015-05-02T11:52:35Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/02/2015 01:43 PM, Andreas Schwab wrote:\n> or:\n>\n> sort |\n> while IFS=: read cmd grp\n> do\n>\n> Andreas.\n\nI believe this is the most legible form, the intention is much clearer.\n\nSébastien\n"},{"id":"260427","messageId":"5544DCA3.6000704@gmail.com","threadId":"39216","inReplyTo":"87wq0rb3xk.fsf@igel.home","subject":"Re: [PATCH v2 2/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-02T14:18:11Z","receivedAt":"2015-05-02T14:18:11Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"extract the $grp shell variable from command-list.txt (eg: \n'common-3_worktree') and add\nthis value to the output:\n\nbefore/after:\n{\"add\", N_(\"Add file contents to the index\")}\n{\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"}\n\nWhen 'git help' is called, the displayed commands can be grouped by theme\ninstead of a less useful alphabetical order.\n\nSigned-off by: Sébastien Guimmara \n---\n generate-cmdlist.sh | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\nindex 9a4c9b9..98f937b 100755\n--- a/generate-cmdlist.sh\n+++ b/generate-cmdlist.sh\n@@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n struct cmdname_help {\n char name[16];\n char help[80];\n+ char group[20];\n };\n\n static struct cmdname_help common_cmds[] = {\"\n\n-sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' command-list.txt |\n+sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p' \ncommand-list.txt |\n sort |\n-while read cmd\n+while IFS=: read cmd grp\n do\n sed -n '\n /^NAME/,/git-'\"$cmd\"'/H\n ${\n x\n- s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n+ s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\"), \"'\"$grp\"'\"},/\n p\n }' \"Documentation/git-$cmd.txt\"\n done\n-- \n2.4.0\n"},{"id":"260439","messageId":"55456990.6000509@gmail.com","threadId":"39216","inReplyTo":"554405D5.9080702@gmail.com","subject":"[PATCH v3 0/4] git help: group common commands by themes","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T00:19:28Z","receivedAt":"2015-05-03T00:19:28Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Group the common commands printed by 'git help' (or 'git' without any\noptions) into beginner friendly themes. To achieve this, the file\ncommand-list.txt receives an additional information for all 'common'\ncommands, in the form of an indexed group suffix.\n\nGroup suffixes are in the form: 'x_group', where x is a number used to\norder (ascending) commands in the displayed help:\n\n[...]\n\ngit-add mainporcelain common-3_worktree\ngit-bisect mainporcelain common-7_search\ngit-branch mainporcelain common-6_branching\ngit-checkout mainporcelain common-6_branching\n\n[...]\n\nNote: the proposed layout comprises:\n\n1_init\n2_info\n3_worktree\n4_remote\n5_history\n6_branching\n7_search\n\nThey can be easily modified by just changing command-list.txt\n\ncommand-list.txt is then parsed by generate-cmdlist.sh to generate\ncommon-cmds.h with the additional group name being a 'group' field in\nthe cmdname_help struct:\n\n[...]\n\n {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n {\"bisect\", N_(\"Find by binary search the change that introduced a\nbug\"), \"7_search\"},\n {\"branch\", N_(\"List, create, or delete branches\"), \"6_branching\"},\n {\"checkout\", N_(\"Checkout a branch or paths to the working tree\"),\n\"6_branching\"},\n\n[...]\n\nFinally, list_common_cmds_help() prints those common commands by groups,\nskipping a line between each group:\n\n[...]\n\nThe most commonly used git commands are:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an\nexisting one\n\n log Show commit logs\n show Show various types of objects\n status Show the working tree status\n\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 fetch Download objects and refs from another repository\n pull Fetch from and integrate with another repository or a\nlocal branch\n push Update remote refs along with associated objects\n\n commit Record changes to the repository\n diff Show changes between commits, commit and working tree, etc\n rebase Forward-port local commits to the updated upstream head\n tag Create, list, delete or verify a tag object signed with GPG\n\n[...]\n\nThe documentation api-builtin.txt is updated to reflect the change.\n"},{"id":"260440","messageId":"554569F1.4020108@gmail.com","threadId":"39216","inReplyTo":"55456990.6000509@gmail.com","subject":"[PATCH v3 1/4] command-list.txt: group common commands by themes","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T00:21:05Z","receivedAt":"2015-05-03T00:21:05Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Add a group identifier in the form {x}_{name}, where {x} is a digit\nidentifying the group, and {name} the group name. The digit is used\nto sort the common commands by groups instead of the less useful\nalphabetical order.\n\nbefore the patch:\ngit-add\t\t\tmainporcelain common\n\nafter:\ngit-add\t\t\tmainporcelain common-3_worktree\n\nSigned-off-by: Sébastien Guimmara \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 f1eae08..b0730a2 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,29 +1,29 @@\n # List of known git commands.\n # command name\t\t\t\tcategory [deprecated] [common]\n-git-add mainporcelain common\n+git-add mainporcelain common-3_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-7_search\n git-blame ancillaryinterrogators\n-git-branch mainporcelain common\n+git-branch mainporcelain common-6_branching\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-6_branching\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-1_init\n git-column purehelpers\n-git-commit mainporcelain common\n+git-commit mainporcelain common-5_history\n git-commit-tree plumbingmanipulators\n git-config ancillarymanipulators\n git-count-objects ancillaryinterrogators\n@@ -35,14 +35,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-5_history\n git-diff-files plumbinginterrogators\n git-diff-index plumbinginterrogators\n git-diff-tree plumbinginterrogators\n git-difftool ancillaryinterrogators\n git-fast-export\t\t\t\tancillarymanipulators\n git-fast-import\t\t\t\tancillarymanipulators\n-git-fetch mainporcelain common\n+git-fetch mainporcelain common-4_remote\n git-fetch-pack synchingrepositories\n git-filter-branch ancillarymanipulators\n git-fmt-merge-msg purehelpers\n@@ -51,7 +51,7 @@ git-format-patch mainporcelain\n git-fsck\t ancillaryinterrogators\n git-gc mainporcelain\n git-get-tar-commit-id ancillaryinterrogators\n-git-grep mainporcelain common\n+git-grep mainporcelain common-7_search\n git-gui mainporcelain\n git-hash-object plumbingmanipulators\n git-help\t\t\t\tancillaryinterrogators\n@@ -60,17 +60,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-1_init\n git-instaweb ancillaryinterrogators\n git-interpret-trailers purehelpers\n gitk mainporcelain\n-git-log mainporcelain common\n+git-log mainporcelain common-2_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-6_branching\n git-merge-base plumbinginterrogators\n git-merge-file plumbingmanipulators\n git-merge-index plumbingmanipulators\n@@ -79,7 +79,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-3_worktree\n git-name-rev plumbinginterrogators\n git-notes mainporcelain\n git-p4 foreignscminterface\n@@ -90,11 +90,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-4_remote\n+git-push mainporcelain common-4_remote\n git-quiltimport foreignscminterface\n git-read-tree plumbingmanipulators\n-git-rebase mainporcelain common\n+git-rebase mainporcelain common-5_history\n git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n@@ -103,28 +103,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-3_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-3_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-2_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-2_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-5_history\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n-- \n2.4.0\n"},{"id":"260441","messageId":"55456A40.80806@gmail.com","threadId":"39216","inReplyTo":"55456990.6000509@gmail.com","subject":"[PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T00:22:24Z","receivedAt":"2015-05-03T00:22:24Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Teach generate-cmdlist.sh to parse common command groups\nfound in command-list.txt in the form\n\ncommon-3_worktree ('3_worktree' being the group identifier)\n\nExtract the $grp variable, in addition to the previous $cmd,\nand inject it as a third field in the cmdname_help struct:\n\n{\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n\nSo that when 'git' is called, we can display common commands\ngrouped by theme instead of a less useful alphabetical order.\n\nReviewed by: Luke Diamand \nReviewed by: Andreas Schwab \nSigned-off-by: Sébastien Guimmara \n---\n generate-cmdlist.sh | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\nindex 9a4c9b9..98f937b 100755\n--- a/generate-cmdlist.sh\n+++ b/generate-cmdlist.sh\n@@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n struct cmdname_help {\n char name[16];\n char help[80];\n+ char group[20];\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+sed -n -e 's/^git-\\([^ \t]*\\)[ \t].* common-\\(.*\\)/\\1:\\2/p' command-list.txt |\n sort |\n-while read cmd\n+while IFS=: read cmd grp\n do\n sed -n '\n /^NAME/,/git-'\"$cmd\"'/H\n ${\n \t x\n-\t s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n+\t s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\"), \"'\"$grp\"'\"},/\n \t p\n }' \"Documentation/git-$cmd.txt\"\n done\n-- \n2.4.0\n"},{"id":"260442","messageId":"55456A91.3040408@gmail.com","threadId":"39216","inReplyTo":"55456990.6000509@gmail.com","subject":"[PATCH v3 3/4] help.c - group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T00:23:45Z","receivedAt":"2015-05-03T00:23:45Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"When 'git help' is called, a list of common commands are printed:\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\nInstead of a less than optimal alphabetical order, print those\ncommands in theme-related groups:\n\nThe most commonly used git commands are:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an existing one\n\n log Show commit logs\n show Show various types of objects\n status Show the working tree status\n\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\nTo achieve this, qsort the common_cmds array by group name,\nthen print those common commands, skipping a line between each group.\n\nSigned-off-by: Sébastien Guimmara \n---\n help.c | 21 +++++++++++++++++++++\n 1 file changed, 21 insertions(+)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..2169a59 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,\n \t}\n }\n \n+/* sort the command name struct by group name */\n+int cmd_group_cmp(const void *elem1, const void *elem2)\n+{\n+\tstruct cmdname_help *cmd1 = (struct cmdname_help*) elem1;\n+\tstruct cmdname_help *cmd2 = (struct cmdname_help*) elem2;\n+\n+\treturn strcmp(cmd1->group, cmd2->group);\n+}\n+\n void list_common_cmds_help(void)\n {\n \tint i, longest = 0;\n+\tchar *current_grp = NULL;\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+\t/* sort common commands by group (i.e, beginner's relevance) */\n+\tqsort(common_cmds, ARRAY_SIZE(common_cmds),\n+\t\tsizeof(struct cmdname_help), cmd_group_cmp);\n+\n \tputs(_(\"The most commonly used git commands are:\"));\n \tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n+\n+\t\t/* skip a line each time we encounter a new command group */\n+\t\tif (current_grp != NULL && strcmp(common_cmds[i].group, current_grp))\n+\t\t\tprintf(\"\\n\");\n+\n+\t\tcurrent_grp = common_cmds[i].group;\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":"260443","messageId":"55456AD3.7090908@gmail.com","threadId":"39216","inReplyTo":"55456990.6000509@gmail.com","subject":"[PATCH v3 4/4] api-builtin.txt: explain common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T00:24:51Z","receivedAt":"2015-05-03T00:24:51Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Update api-builtin.txt to explain how to add the group information\nfor common commands.\n\nSigned-off-by: Sébastien Guimmara \n---\n Documentation/technical/api-builtin.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt\nindex 22a39b9..76baba8 100644\n--- a/Documentation/technical/api-builtin.txt\n+++ b/Documentation/technical/api-builtin.txt\n@@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more things to do:\n \n . Write documentation in `Documentation/git-foo.txt`.\n \n-. Add an entry for `git-foo` to `command-list.txt`.\n+. Add an entry for `git-foo` to `command-list.txt`. If foo is considered\n+ a 'common' command, add 'common-x_group' as the third value,\n+ where x_group is one of the existing themes:\n+\n+\tgit-foo mainporcelain common-3_worktree\n \n . Add an entry for `/git-foo` to `.gitignore`.\n \n-- \n2.4.0\n"},{"id":"260449","messageId":"xmqqk2wqwg9f.fsf@gitster.dls.corp.google.com","threadId":"39216","inReplyTo":"554405D5.9080702@gmail.com","subject":"Re: [PATCH v2 1/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-03T02:23:40Z","receivedAt":"2015-05-03T02:23:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> Finally, list_common_cmds_help() prints those common commands by\n> groups, skipping a line between each group:\n>\n> [...]\n>\n> The most commonly used git commands are:\n> clone Clone a repository into a new directory\n> init Create an empty Git repository or reinitialize an existing one\n>\n> log Show commit logs\n> show Show various types of objects\n> status Show the working tree status\n>\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> fetch Download objects and refs from another repository\n> pull Fetch from and integrate with another repository or a local branch\n> push Update remote refs along with associated objects\n>\n> commit Record changes to the repository\n> diff Show changes between commits, commit and working tree, etc\n> rebase Forward-port local commits to the updated upstream head\n> tag Create, list, delete or verify a tag object signed with GPG\n\nWhat is the target audience? Are they expected to be familiar\nenough with Git that they can guess what the above grouping is based\non without a group header?\n\nI consider myself experienced enough with Git but cannot explain or\njustify the placement of \"diff\" in the above list myself, for\nexample. I'd say\n\n * starting a working area (clone, init)\n * examining the history and state (log, show, status, diff)\n * working on the current change (add, checkout, reset)\n * growing, marking and tweaking your history (commit, tag, rebase)\n * working with others (fetch, pull, push)\n\nmight be a more sensible presentation order (and classification).\n"},{"id":"260458","messageId":"55462895.8080108@gmail.com","threadId":"39216","inReplyTo":"xmqqk2wqwg9f.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 1/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T13:54:29Z","receivedAt":"2015-05-03T13:54:29Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/03/2015 05:30 AM, Junio C Hamano wrote:\n> What is the target audience? Are they expected to be familiar\n> enough with Git that they can guess what the above grouping is based\n> on without a group header?\n\nSince this help is not only displayed on '$ git help' but also on\n'$ git', we can assume it's directed at people not familiar with\ngit and/or the command line usage.\n\nWe could then display headers this way:\n\nThe most commonly used git commands are:\n * starting a working area:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an existing one\n \n * examining the history and state:\n diff Show changes between commits, commit and working tree, etc\n log Show commit logs\n show Show various types of objects\n status Show the working tree status\n bisect Find by binary search the change that introduced a bug\n grep Print lines matching a pattern\n\n * working on the current change:\n add Add file contents to the index\n checkout Checkout a branch or paths to the working tree\n reset Reset current HEAD to the specified state\n rm Remove files from the working tree and from the index\n mv Move or rename a file, a directory, or a symlink\n \n * growing, marking and tweaking your history:\n commit Record changes to the repository\n rebase Forward-port local commits to the updated upstream head\n tag Create, list, delete or verify a tag object signed with GPG\n \n * working with others:\n fetch Download objects and refs from another repository\n pull Fetch from and integrate with another repository or a local branch\n push Update remote refs along with associated objects\n \n * branching and merging histories:\n branch List, create, or delete branches\n merge Join two or more development histories together\n\nThis raises a few questions:\n\n1. Is 'bisect' really a common command (from the target audience standpoint)\n2. Does 'Forward-port local commits to the updated upstream head' really help\n to grok the idea of 'rebase' ? There are 3 words in this sentence that\n an unfamiliar git user may not be comfortable with : 'forward-port',\n 'upstream' and 'head'. I'm not familiar enough with 'rebase' to think of\n a clearer explanation, but what about:\n\t\n\t'Rewrite the history of a branch with commits from another branch'\n"},{"id":"260459","messageId":"55462966.1030408@gmail.com","threadId":"39216","inReplyTo":"55462895.8080108@gmail.com","subject":"Re: [PATCH v2 1/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T13:57:58Z","receivedAt":"2015-05-03T13:57:58Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"The formatting in the previous email was a bit off. Here is the proper one.\n\nThe most commonly used git commands are:\n * starting a working area:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an existing one\n\n * examining the history and state:\n diff Show changes between commits, commit and working tree, etc\n log Show commit logs\n show Show various types of objects\n status Show the working tree status\n bisect Find by binary search the change that introduced a bug\n grep Print lines matching a pattern\n\n * working on the current change:\n add Add file contents to the index\n checkout Checkout a branch or paths to the working tree\n reset Reset current HEAD to the specified state\n rm Remove files from the working tree and from the index\n mv Move or rename a file, a directory, or a symlink\n\n * growing, marking and tweaking your history:\n commit Record changes to the repository\n rebase Forward-port local commits to the updated upstream head\n tag Create, list, delete or verify a tag object signed with GPG\n\n * working with others:\n fetch Download objects and refs from another repository\n pull Fetch from and integrate with another repository or a local branch\n push Update remote refs along with associated objects\n\n * branching and merging histories:\n branch List, create, or delete branches\n merge Join two or more development histories together\n"},{"id":"260472","messageId":"xmqq7fspwpho.fsf@gitster.dls.corp.google.com","threadId":"39216","inReplyTo":"55462895.8080108@gmail.com","subject":"Re: [PATCH v2 1/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-03T17:16:35Z","receivedAt":"2015-05-03T17:16:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> We could then display headers this way:\n>\n> The most commonly used git commands are:\n> * starting a working area:\n> clone Clone a repository into a new directory\n> init Create an empty Git repository or reinitialize an existing one\n> * examining the history and state:\n> diff Show changes between commits, commit and working tree, etc\n> log Show commit logs\n> show Show various types of objects\n> status Show the working tree status\n> bisect Find by binary search the change that introduced a bug\n> grep Print lines matching a pattern\n>\n> * working on the current change:\n> add Add file contents to the index\n> checkout Checkout a branch or paths to the working tree\n> reset Reset current HEAD to the specified state\n> rm Remove files from the working tree and from the index\n> mv Move or rename a file, a directory, or a symlink\n> * growing, marking and tweaking your history:\n> commit Record changes to the repository\n> rebase Forward-port local commits to the updated upstream head\n> tag Create, list, delete or verify a tag object signed with GPG\n> * working with others:\n> fetch Download objects and refs from another repository\n> pull Fetch from and integrate with another repository or a local branch\n> push Update remote refs along with associated objects\n> * branching and merging histories:\n> branch List, create, or delete branches\n> merge Join two or more development histories together\n>\n> This raises a few questions:\n>\n> 1. Is 'bisect' really a common command (from the target audience standpoint)\n\nThat is a good question, but so are many other commands.\n\nI think that (1) it is a good idea to list commands in groups, (2)\nhaving group-head is necessary if we list commands in groups, but\n(3) because group-heads consume valuable vertical space in the\noutput, we may have to have fewer commands in the list.\n\nFor example, \"mv\" and \"rm\" are very questionable things to have in\nthe \"most commonly used\" list. All you need to start with Git is\n\"add\" and \"commit -a\".\n\n\"clone\" and \"init\" are \"once per working area for a project you deal\nwith\" kind of thing, and cannot be in the \"commonly used and you\nbenefit from a gentle nudge to read about it more in the manual to\nlearn Git\" category by definition.\n\n\"rebase\" should be with \"merge\" and \"branch\", but I wouldn't have\n\"branching and merging\" as a separate category---they are all part\nof \"growing and tweaking\". And \"branch\" itself may be questionable\nfor those who are starting with Git.\n\nDo we care about the ordering of the items within groups, by the way?\n\n> 2. Does 'Forward-port local commits to the updated upstream head' really help\n> to grok the idea of 'rebase' ? There are 3 words in this sentence that\n> an unfamiliar git user may not be comfortable with...\n\n\"Rebuild the history on a branch on top of a new commit\", perhaps?\n\nBut this brings us back to \"what the target audience?\" question.\n\nMy answer to the question has always been \"the list is a gentle\nnudge to guide the user to read about it more in the manual to\nlearn.\" The sooner users are guided to graduate from the \"not be\ncomfortable\" state, the more productive they will be.\n\nFor that to happen, we would need to (1) strongly suggest that the\nsubcommand is what the user wants to use, and (2) carefully avoid\ngiving an impression that the user learned everything there is to\nknow in order to use the command effectively from that single line.\n\nOf course, an argument can be made that the single-line should aim\nto teach everything there is to know in order to use the command\neffectively, but because I do not think that is feasible I would\naim for the second best, which is why we want to keep the last two\nlines about \"git help for a specific subcommand\".\n"},{"id":"260477","messageId":"xmqqpp6hv94x.fsf@gitster.dls.corp.google.com","threadId":"39216","inReplyTo":"55456A40.80806@gmail.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-03T17:55:10Z","receivedAt":"2015-05-03T17:55:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> Teach generate-cmdlist.sh to parse common command groups\n> found in command-list.txt in the form\n>\n> common-3_worktree ('3_worktree' being the group identifier)\n>\n> Extract the $grp variable, in addition to the previous $cmd,\n> and inject it as a third field in the cmdname_help struct:\n>\n> {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n>\n> So that when 'git' is called, we can display common commands\n> grouped by theme instead of a less useful alphabetical order.\n>\n> Reviewed by: Luke Diamand \n> Reviewed by: Andreas Schwab \n\nThese people may have helped you to polish your earlier round to\ncome up with this version, but I do not think they should be listed\nas reviewed-by (in the sense that they would say \"Yes, I read this\nversion and consider it very good--I endorse the change!\") yet.\n\n> Signed-off-by: Sébastien Guimmara \n> ---\n\n> generate-cmdlist.sh | 7 ++++---\n> 1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n> index 9a4c9b9..98f937b 100755\n> --- a/generate-cmdlist.sh\n> +++ b/generate-cmdlist.sh\n> @@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n> struct cmdname_help {\n> char name[16];\n> char help[80];\n> + char group[20];\n\nStoring group name in duplicated text for all commands and then\nusing string comparison at runtime is grossly wasteful, don't you\nthink, especially when the list is not manually maintained?\n\ncommand-list.txt is something manually maintained, i.e. the source,\nand it makes sense to use easy-to-see strings like \"3_worktree\"\nlabel there instead of cryptic number, but the whole point of this\nscript is to pre-process that text into .c file to a form that is\nmore suited for machine consumption. I think this script should:\n\n - read command list once to make the list of groups in a new\n separate array;\n\n - add the group as an \"unsigned char group_number\" (as we won't\n have more than 200 groups) field to this struct;\n\n - read command list again and for each command give the group\n number here.\n\nor something like that.\n"},{"id":"260483","messageId":"CAPig+cQNOEgZAn=2MXNjkUxnMA+OimTLfSmEMskZsvRv-Zh42w@mail.gmail.com","threadId":"39216","inReplyTo":"55456A40.80806@gmail.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T19:18:22Z","receivedAt":"2015-05-03T19:18:22Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 2, 2015 at 8:22 PM, Sébastien Guimmara\n wrote:\n> Teach generate-cmdlist.sh to parse common command groups\n> found in command-list.txt in the form\n>\n> common-3_worktree ('3_worktree' being the group identifier)\n>\n> Extract the $grp variable, in addition to the previous $cmd,\n> and inject it as a third field in the cmdname_help struct:\n>\n> {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n>\n> So that when 'git' is called, we can display common commands\n> grouped by theme instead of a less useful alphabetical order.\n>\n> Signed-off-by: Sébastien Guimmara \n> ---\n> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n> index 9a4c9b9..98f937b 100755\n> --- a/generate-cmdlist.sh\n> +++ b/generate-cmdlist.sh\n> @@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n> struct cmdname_help {\n> char name[16];\n> char help[80];\n> + char group[20];\n> };\n> static struct cmdname_help common_cmds[] = {\"\n> -sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' [...]\n> +sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p' [...]\n\nIsn't \\(.*\\) a bit too loose for grabbing $grp? What if someone some\nday adds another column to express some other sort of attribute? (Or,\nif someone perhaps uses the \"deprecated\" attribute but places it in\ncolumn 3 rather than 2 as documented.) It probably would be better to\ntighten this up by grabbing only non-whitespace characters, as is\nalready done for $cmd.\n\n(In fact, this sed invocation is already broken for \"deprecated\",\nisn't it? According to the command-list.txt header comments,\n\"deprecated\" should be placed before \"common\", yet the sed invocation\nexpects \"common\" to follow the command immediately. Perhaps a\npreparatory patch could fix this issue; or just do away with\n\"deprecated\" entirely since it's not used.)\n\n> sort |\n> -while read cmd\n> +while IFS=: read cmd grp\n\nSince both $cmd and $grp are simple tokens, neither of which contain\nwhitespace, this could be handled more simply by just having sed emit\nthem separated by a space rather than by ':'; in which case your\n'while read' loop wouldn't need to muck with IFS at all.\n\n> do\n> sed -n '\n> /^NAME/,/git-'\"$cmd\"'/H\n> ${\n> x\n> - s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n> + s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\"), \"'\"$grp\"'\"},/\n> p\n> }' \"Documentation/git-$cmd.txt\"\n> done\n> --\n> 2.4.0\n"},{"id":"260484","messageId":"CAPig+cS1K0uZy1-MxKCqyi7Vy5kXYN2Qm-AC4s0YyY5Oe948CA@mail.gmail.com","threadId":"39216","inReplyTo":"55456A91.3040408@gmail.com","subject":"Re: [PATCH v3 3/4] help.c - group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T19:44:33Z","receivedAt":"2015-05-03T19:44:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 2, 2015 at 8:23 PM, Sébastien Guimmara\n wrote:\n> When 'git help' is called, a list of common commands are printed:\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> Instead of a less than optimal alphabetical order, print those\n> commands in theme-related groups:\n>\n> The most commonly used git commands are:\n> clone Clone a repository into a new directory\n> init Create an empty Git repository or reinitialize an existing one\n>\n> log Show commit logs\n> show Show various types of objects\n> status Show the working tree status\n>\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> To achieve this, qsort the common_cmds array by group name,\n> then print those common commands, skipping a line between each group.\n\nJust a minor observation regarding the final paragraph (feel free to ignore):\n\nThis level of detail is probably overkill. The overall intent of the\nchange has already been spelled out nicely via the examples, so\nmentioning qsort() is unnecessary since it's a mere implementation\ndetail; one which a reader can easily discover by reading the patch\nproper. Likewise, the example \"new output\" already shows clearly the\nblank line between groups, so there is no need to mention it in prose.\n\nIf I was composing the commit message, I'd probably drop the final\nparagraph altogether and rephrase something like this:\n\n 'git help' shows common commands in alphabetical order like this:\n\n \n\n without any indication of how commands relate to high-level\n concepts or each other. Revise the output to group commands by\n concept, like this:\n\n \n\nMore below.\n\n> Signed-off-by: Sébastien Guimmara \n> ---\n> diff --git a/help.c b/help.c\n> index 2072a87..2169a59 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,\n> }\n> }\n> +/* sort the command name struct by group name */\n> +int cmd_group_cmp(const void *elem1, const void *elem2)\n> +{\n> + struct cmdname_help *cmd1 = (struct cmdname_help*) elem1;\n> + struct cmdname_help *cmd2 = (struct cmdname_help*) elem2;\n\nAs this is C rather than C++, you can drop the cast.\n\nAlso, if you were to keep the cast, the prevailing style in git code\nis to insert a space before the '*' and to drop the space after the\n')'.\n\n> + return strcmp(cmd1->group, cmd2->group);\n> +}\n> +\n> void list_common_cmds_help(void)\n> {\n> int i, longest = 0;\n> + char *current_grp = NULL;\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> + /* sort common commands by group (i.e, beginner's relevance) */\n> + qsort(common_cmds, ARRAY_SIZE(common_cmds),\n> + sizeof(struct cmdname_help), cmd_group_cmp);\n\nSlightly more maintenance free would be sizeof(common_cmds[0]) instead\nof sizeof(struct cmdname_help).\n\n> puts(_(\"The most commonly used git commands are:\"));\n> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n> +\n\nStyle: Drop this blank line.\n\n> + /* skip a line each time we encounter a new command group */\n> + if (current_grp != NULL && strcmp(common_cmds[i].group,\n> current_grp))\n> + printf(\"\\n\");\n\nThis chunk of code is pretty well self-explanatory, so the comment\nisn't really adding anything. A comment which merely repeat what the\ncode itself already says is typically considered distracting rather\nthan illuminating, thus it could (and probably should) be dropped. The\nsame observation probably applies to the comment preceding the qsort()\ninvocation, as well.\n\nFinally, elsewhere in this source file, a blank line is emitted with\nthe more idiomatic putchar('\\n') rather than printf(\"\\n\").\n\n> +\n> + current_grp = common_cmds[i].group;\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":"260486","messageId":"CAPig+cT0aurG9gS2CrwMPG2B4xrAbhvwNJtAjYz7UYc4x1TiEA@mail.gmail.com","threadId":"39216","inReplyTo":"55456AD3.7090908@gmail.com","subject":"Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T20:02:07Z","receivedAt":"2015-05-03T20:02:07Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, May 2, 2015 at 8:24 PM, Sébastien Guimmara\n wrote:\n> Update api-builtin.txt to explain how to add the group information\n> for common commands.\n>\n> Signed-off-by: Sébastien Guimmara \n> ---\n> diff --git a/Documentation/technical/api-builtin.txt\n> b/Documentation/technical/api-builtin.txt\n> index 22a39b9..76baba8 100644\n> --- a/Documentation/technical/api-builtin.txt\n> +++ b/Documentation/technical/api-builtin.txt\n> @@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more\n> things to do:\n> . Write documentation in `Documentation/git-foo.txt`.\n> -. Add an entry for `git-foo` to `command-list.txt`.\n> +. Add an entry for `git-foo` to `command-list.txt`. If foo is considered\n> + a 'common' command, add 'common-x_group' as the third value,\n> + where x_group is one of the existing themes:\n> +\n> + git-foo mainporcelain common-3_worktree\n> . Add an entry for `/git-foo` to `.gitignore`.\n\nUnfortunately, this change breaks Asciidoc formatting by making the\nfollowing \".Add an entry...\" item get glued to the new \"git-foo...\"\nexample. Fix by inserting a blank line after the \"git-foo...\". (And\ntry formatting it yourself to ensure that it is working as expected.)\n\nFinally, all of your patches are whitespace-damaged and fail to apply\nto the code-base. Did you paste them into your email client or some\nsuch? If possible, try to send patches via git-send-email since it\ndoes a good job of protecting against whitespace and other types of\ndamage.\n"},{"id":"260487","messageId":"CAPig+cTNzOYjKqM4R9ajAAH6jn1xoDpr=GUz1Guyo3kNjrEviw@mail.gmail.com","threadId":"39216","inReplyTo":"CAPig+cQNOEgZAn=2MXNjkUxnMA+OimTLfSmEMskZsvRv-Zh42w@mail.gmail.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T20:10:55Z","receivedAt":"2015-05-03T20:10:55Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, May 3, 2015 at 3:18 PM, Eric Sunshine wrote:\n> On Sat, May 2, 2015 at 8:22 PM, Sébastien Guimmara\n> wrote:\n>> ---\n>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n>> index 9a4c9b9..98f937b 100755\n>> --- a/generate-cmdlist.sh\n>> +++ b/generate-cmdlist.sh\n>> @@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n>> };\n>> static struct cmdname_help common_cmds[] = {\"\n>> -sed -n -e 's/^git-\\([^ ]*\\)[ ].* common.*/\\1/p' [...]\n>> +sed -n -e 's/^git-\\([^ ]*\\)[ ].* common-\\(.*\\)/\\1:\\2/p' [...]\n>\n> Isn't \\(.*\\) a bit too loose for grabbing $grp? What if someone some\n> day adds another column to express some other sort of attribute? (Or,\n> if someone perhaps uses the \"deprecated\" attribute but places it in\n> column 3 rather than 2 as documented.) It probably would be better to\n> tighten this up by grabbing only non-whitespace characters, as is\n> already done for $cmd.\n>\n> (In fact, this sed invocation is already broken for \"deprecated\",\n> isn't it? According to the command-list.txt header comments,\n> \"deprecated\" should be placed before \"common\", yet the sed invocation\n> expects \"common\" to follow the command immediately. Perhaps a\n> preparatory patch could fix this issue; or just do away with\n> \"deprecated\" entirely since it's not used.)\n\nAh, I misread the original sed invocation slightly. It's not broken,\nso scratch the second paragraph.\n\n(Though, it does expect at least one whitespace character and then one\nspace before \"common\", which is a bit odd, but not a problem with the\ncurrent content of command-list.txt.)\n"},{"id":"260489","messageId":"CAPig+cSRiw7QeAzuxAJF8mikeK1YiNoNATKzMz71L8E29LLp4Q@mail.gmail.com","threadId":"39216","inReplyTo":"xmqqpp6hv94x.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T20:40:53Z","receivedAt":"2015-05-03T20:40:53Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, May 3, 2015 at 1:55 PM, Junio C Hamano wrote:\n> Sébastien Guimmara writes:\n>\n>> Teach generate-cmdlist.sh to parse common command groups\n>> found in command-list.txt in the form\n>>\n>> common-3_worktree ('3_worktree' being the group identifier)\n>>\n>> Extract the $grp variable, in addition to the previous $cmd,\n>> and inject it as a third field in the cmdname_help struct:\n>>\n>> {\"add\", N_(\"Add file contents to the index\"), \"3_worktree\"},\n>>\n>> So that when 'git' is called, we can display common commands\n>> grouped by theme instead of a less useful alphabetical order.\n>>\n>> Reviewed by: Luke Diamand \n>> Reviewed by: Andreas Schwab \n>\n> These people may have helped you to polish your earlier round to\n> come up with this version, but I do not think they should be listed\n> as reviewed-by (in the sense that they would say \"Yes, I read this\n> version and consider it very good--I endorse the change!\") yet.\n\nMinor addendum: If you'd like to acknowledge Luke for $(...) and\nAndreas for IFS munging, then Helped-by: would be appropriate (and\ndoesn't require their consent).\n\nMore below.\n\n>> Signed-off-by: Sébastien Guimmara \n>> ---\n>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n>> index 9a4c9b9..98f937b 100755\n>> --- a/generate-cmdlist.sh\n>> +++ b/generate-cmdlist.sh\n>> @@ -4,19 +4,20 @@ echo \"/* Automatically generated by $0 */\n>> struct cmdname_help {\n>> char name[16];\n>> char help[80];\n>> + char group[20];\n>\n> Storing group name in duplicated text for all commands and then\n> using string comparison at runtime is grossly wasteful, don't you\n> think, especially when the list is not manually maintained?\n>\n> command-list.txt is something manually maintained, i.e. the source,\n> and it makes sense to use easy-to-see strings like \"3_worktree\"\n> label there instead of cryptic number, but the whole point of this\n> script is to pre-process that text into .c file to a form that is\n> more suited for machine consumption. I think this script should:\n>\n> - read command list once to make the list of groups in a new\n> separate array;\n>\n> - add the group as an \"unsigned char group_number\" (as we won't\n> have more than 200 groups) field to this struct;\n>\n> - read command list again and for each command give the group\n> number here.\n>\n> or something like that.\n\nSome additional observations:\n\nThe \"common-N_group\" form seems both redundant and unsightly.\nRedundant because you could just as easily pluck out 'common' lines by\nsearching for \"N_group\", thus making the \"common-\" prefix unnecessary.\nUnsightly because the mix of \"-\" and \"_\" is hard to read. (In general,\n\"-\" is easier to read, thus probably a better choice.)\n\nThinking out loud, without regard to implementation complexity...\n\nI might expect to see the table of groups to be declared first, in the\norder that they should be displayed by \"git help\". Having the groups\nin their own table also allows you to give them human-readable\ndescriptions. For actual use, you'd tag each command with the bare\ngroup name.\n\nSo, something like this, perhaps:\n\n [groups]\n init starting a working area\n info examining history and state\n ...\n branching branching and merging histories\n\n [commands]\n git-branch mainporcelain branching\n ...\n git-clone mainporcelain init\n ...\n\nThis way, the 'N' in \"N_group\" is unnecessary since presentation order\nis implied by the [groups] table, and you don't need the \"common-\"\nprefix anymore since any command having an attribute from the [groups]\ntable is automatically considered common.\n"},{"id":"260490","messageId":"55468ABB.8050504@gmail.com","threadId":"39216","inReplyTo":"CAPig+cSRiw7QeAzuxAJF8mikeK1YiNoNATKzMz71L8E29LLp4Q@mail.gmail.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T20:53:15Z","receivedAt":"2015-05-03T20:53:15Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/03/2015 10:40 PM, Eric Sunshine wrote:\n>> These people may have helped you to polish your earlier round to\n>> come up with this version, but I do not think they should be listed\n>> as reviewed-by (in the sense that they would say \"Yes, I read this\n>> version and consider it very good--I endorse the change!\") yet.\n>\n> Minor addendum: If you'd like to acknowledge Luke for $(...) and\n> Andreas for IFS munging, then Helped-by: would be appropriate (and\n> doesn't require their consent).\n\nThanks for the precision, I got confused with this one.\n\n> So, something like this, perhaps:\n>\n> [groups]\n> init starting a working area\n> info examining history and state\n> ...\n> branching branching and merging histories\n>\n> [commands]\n> git-branch mainporcelain branching\n> ...\n> git-clone mainporcelain init\n> ...\n>\n> This way, the 'N' in \"N_group\" is unnecessary since presentation order\n> is implied by the [groups] table, and you don't need the \"common-\"\n> prefix anymore since any command having an attribute from the [groups]\n> table is automatically considered common.\n>\n\nIt's a good idea. I'll look into it.\n"},{"id":"260491","messageId":"55468C23.70306@gmail.com","threadId":"39216","inReplyTo":"CAPig+cT0aurG9gS2CrwMPG2B4xrAbhvwNJtAjYz7UYc4x1TiEA@mail.gmail.com","subject":"Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T20:59:15Z","receivedAt":"2015-05-03T20:59:15Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/03/2015 10:02 PM, Eric Sunshine wrote:\n> On Sat, May 2, 2015 at 8:24 PM, Sébastien Guimmara\n> wrote:\n>> Update api-builtin.txt to explain how to add the group information\n>> for common commands.\n>>\n>> Signed-off-by: Sébastien Guimmara \n>> ---\n>> diff --git a/Documentation/technical/api-builtin.txt\n>> b/Documentation/technical/api-builtin.txt\n>> index 22a39b9..76baba8 100644\n>> --- a/Documentation/technical/api-builtin.txt\n>> +++ b/Documentation/technical/api-builtin.txt\n>> @@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more\n>> things to do:\n>> . Write documentation in `Documentation/git-foo.txt`.\n>> -. Add an entry for `git-foo` to `command-list.txt`.\n>> +. Add an entry for `git-foo` to `command-list.txt`. If foo is considered\n>> + a 'common' command, add 'common-x_group' as the third value,\n>> + where x_group is one of the existing themes:\n>> +\n>> + git-foo mainporcelain common-3_worktree\n>> . Add an entry for `/git-foo` to `.gitignore`.\n>\n> Unfortunately, this change breaks Asciidoc formatting by making the\n> following \".Add an entry...\" item get glued to the new \"git-foo...\"\n> example. Fix by inserting a blank line after the \"git-foo...\". (And\n> try formatting it yourself to ensure that it is working as expected.)\n>\n\nI'll look into that.\n\n> Finally, all of your patches are whitespace-damaged and fail to apply\n> to the code-base. Did you paste them into your email client or some\n> such? If possible, try to send patches via git-send-email since it\n> does a good job of protecting against whitespace and other types of\n> damage.\n>\n\nI'm having a hard time configuring send-email through gmail,\nso those patches were indeed pasted into plain text. I'll look into\nmaking send-email work.\n\nThank you for the help,\n\nSébastien\n"},{"id":"260492","messageId":"CAPig+cRqvd=_n9huD_txEr6EXVrWZx0onReL5bh_mCKy3M3LOg@mail.gmail.com","threadId":"39216","inReplyTo":"55468ABB.8050504@gmail.com","subject":"Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T21:10:52Z","receivedAt":"2015-05-03T21:10:52Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, May 3, 2015 at 4:53 PM, Sébastien Guimmara\n wrote:\n> On 05/03/2015 10:40 PM, Eric Sunshine wrote:\n>>> These people may have helped you to polish your earlier round to\n>>> come up with this version, but I do not think they should be listed\n>>> as reviewed-by (in the sense that they would say \"Yes, I read this\n>>> version and consider it very good--I endorse the change!\") yet.\n>>\n>> Minor addendum: If you'd like to acknowledge Luke for $(...) and\n>> Andreas for IFS munging, then Helped-by: would be appropriate (and\n>> doesn't require their consent).\n>\n> Thanks for the precision, I got confused with this one.\n\nWhat Junio meant was that Reviewed-by: is something that reviewers\n\"give\" explicitly when they are confident that they understand and\nbelieve your patches are correct. You may incorporate a \"given\"\nReviewed-by: into a patch when re-rolling if the patch hasn't changed\nsince the previous round (or has changed in very minor ways which\ndon't affect the Reviewed-by:). Someone merely reading your patch and\ncommenting on it (and possibly making suggestions) does not warrant a\nReviewed-by: since comments and suggestions alone don't necessarily\nmean that they agree that a patch is acceptable or correct, thus don't\nadd Reviewed-by: without it being \"given\".\n\nHelped-by: is for acknowledging someone's assistance.\n\nMore below.\n\n>> So, something like this, perhaps:\n>>\n>> [groups]\n>> init starting a working area\n>> info examining history and state\n>> ...\n>> branching branching and merging histories\n>>\n>> [commands]\n>> git-branch mainporcelain branching\n>> ...\n>> git-clone mainporcelain init\n>> ...\n>>\n>> This way, the 'N' in \"N_group\" is unnecessary since presentation order\n>> is implied by the [groups] table, and you don't need the \"common-\"\n>> prefix anymore since any command having an attribute from the [groups]\n>> table is automatically considered common.\n>\n> It's a good idea. I'll look into it.\n\n'awk' might be helpful to implement this sort of scheme, as well as\nJunio's suggestion of emitting only a group number in the generated\ntable rather than a string. If so, try to stick to POSIX (and avoid\nGNU or other extensions).\n"},{"id":"260493","messageId":"CAPig+cTB3JOoqw3pcSBBdC_btwDP2uzKDH119nVYVZ=4U=PFJQ@mail.gmail.com","threadId":"39216","inReplyTo":"55468C23.70306@gmail.com","subject":"Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-03T21:13:51Z","receivedAt":"2015-05-03T21:13:51Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, May 3, 2015 at 4:59 PM, Sébastien Guimmara\n wrote:\n> On 05/03/2015 10:02 PM, Eric Sunshine wrote:\n>> Finally, all of your patches are whitespace-damaged and fail to apply\n>> to the code-base. Did you paste them into your email client or some\n>> such? If possible, try to send patches via git-send-email since it\n>> does a good job of protecting against whitespace and other types of\n>> damage.\n>\n> I'm having a hard time configuring send-email through gmail,\n> so those patches were indeed pasted into plain text. I'll look into\n> making send-email work.\n\nThe Gmail example in the \"git send-email\" manual should be sufficient.\nHowever, perhaps other prerequisites are unmet in your case? (For\ninstance, I had to manually install the Perl Net::SMTP::SSL module on\nmy machine to get git-send-email working.)\n"},{"id":"260496","messageId":"5546A203.6090305@gmail.com","threadId":"39216","inReplyTo":"CAHYJk3S3s4RjFMUaomP2wUVBbcTLRGYrAOa-uDjrfsKqUuWPog@mail.gmail.com","subject":"Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-03T22:32:35Z","receivedAt":"2015-05-03T22:32:35Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/03/2015 11:07 PM, Mikael Magnusson wrote:\n> [sendemail]\n> smtpencryption = tls\n> smtpserver = smtp.gmail.com\n> smtpuser = sebastien.guimmara@gmail.com\n> smtpserverport = 587\n> assume8bitEncoding = UTF-8\n>\n> Should be all that's needed. (in ~/.gitconfig)\n\nThanks a lot, I was also missing packages. Now it works fine.\n"}]}