{"thread":{"id":"39246","subject":"[PATCH 1/3] command-list.txt: group common commands by theme","startedAt":"2015-05-04T20:28:07Z","lastAt":"2015-05-08T21:20:04Z","messageCount":38,"participants":["Sébastien Guimmara","Eric Sunshine","Junio C Hamano","Matthieu Moy","Emma Jane Hogbin Westby","Johannes Sixt","Johannes Schindelin","Andreas Schwab","Stefan Beller"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"260546","messageId":"cover.1430770308.git.sebastien.guimmara@gmail.com","threadId":"39246","inReplyTo":null,"subject":"[PATCH 0/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-04T20:28:07Z","receivedAt":"2015-05-04T20:28:07Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"This v4 includes the following suggestions:\n\nIn command-list.txt:\n- Add a [groups] block containing names and description for groups:\n\n [groups]\n init starting a working area\n worktree working on the current change\n remote working with others\n info examining the history and state\n history growing, marking and tweaking your history\n\n- Add a [commands] header on top of the known command list, and\n group names as a third column.\n\n [commands]\n git-add mainporcelain common-worktree\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n git-apply plumbingmanipulators\n git-archimport foreignscminterface\n git-archive mainporcelain\n git-bisect mainporcelain\n git-blame ancillaryinterrogators\n git-branch mainporcelain common-history\n\nThis produces the following output of $ git help:\n\n[...]\nThe most commonly used git commands are:\n\n * starting a working area:\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize [...]\n\n * working on the current change:\n add Add file contents to the index\n reset Reset current HEAD to the specified state\n\n * working with others:\n fetch Download objects and refs from another repository\n pull Fetch from and integrate with another repository [...]\n push Update remote refs along with associated objects\n\n * examining the history and state:\n log Show commit logs\n status Show the working tree status\n\n * growing, marking and tweaking your history:\n branch List, create, or delete branches\n checkout Checkout a branch or paths to the working tree\n commit Record changes to the repository\n diff Show changes between commits, commit and working [...]\n merge Join two or more development histories together\n[...]\n\nI removed from the list of common commands: rebase, rm, mv, bisect \nbecause [1] they are not really common to an unfamiliar user, [2] to\nsave vertical space occupied by group headers.\n\nThanks to Junio and Eric for their suggestions.\n\nSébastien Guimmara (3):\n command-list.txt: group common commands by theme\n generate-cmdlist.sh: parse common group commands\n git help: group common commands by theme\n\n command-list.txt | 64 +++++++++++++++++++++++++++++++----------------------\n generate-cmdlist.sh | 43 +++++++++++++++++++++++++----------\n help.c | 28 ++++++++++++++++++++++-\n 3 files changed, 95 insertions(+), 40 deletions(-)\n\n-- \n2.4.0\n"},{"id":"260545","messageId":"b89d3fec640cb6fb01aa32ad50bae4e064528220.1430770308.git.sebastien.guimmara@gmail.com","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"[PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-04T20:28:08Z","receivedAt":"2015-05-04T20:28:08Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Declare groups for common commands in the [groups] block,\nfollowed by group names and descriptions:\n\n [groups]\n init starting a working area\n worktree working on the current change\n remote working with others\n info examining the history and state\n history growing, marking and tweaking your history\n\nThen, in the [commands] block, map all common commands with a group:\n\n [commands]\n git-add mainporcelain common-worktree\n git-branch mainporcelain common-history\n git-checkout mainporcelain common-history\n [...]\n\ncommand names and groups are then parsed with generate-cmdlist.sh to\ngenerate common-commands.h.\n\nThose commands are displayed in groups in the output of 'git help'.\n\nSigned-off-by: Sébastien Guimmara \n---\n command-list.txt | 64 ++++++++++++++++++++++++++++++++------------------------\n 1 file changed, 37 insertions(+), 27 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex f1eae08..64394ca 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,29 +1,39 @@\n # List of known git commands.\n-# command name\t\t\t\tcategory [deprecated] [common]\n-git-add mainporcelain common\n+# only add group information for common commands\n+\n+[groups]\n+init starting a working area\n+worktree working on the current change\n+remote working with others\n+info examining the history and state\n+history growing, marking and tweaking your history\n+\n+# command name [deprecated] category [group]\n+[commands]\n+git-add mainporcelain common-worktree\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n git-apply plumbingmanipulators\n git-archimport foreignscminterface\n git-archive mainporcelain\n-git-bisect mainporcelain common\n+git-bisect mainporcelain\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,42 +45,42 @@ 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\t\t\t\tancillarymanipulators\n-git-fast-import\t\t\t\tancillarymanipulators\n-git-fetch mainporcelain common\n+git-fast-export ancillarymanipulators\n+git-fast-import ancillarymanipulators\n+git-fetch mainporcelain common-remote\n git-fetch-pack synchingrepositories\n git-filter-branch ancillarymanipulators\n git-fmt-merge-msg purehelpers\n git-for-each-ref plumbinginterrogators\n git-format-patch mainporcelain\n-git-fsck\t ancillaryinterrogators\n+git-fsck ancillaryinterrogators\n git-gc mainporcelain\n git-get-tar-commit-id ancillaryinterrogators\n-git-grep mainporcelain common\n+git-grep mainporcelain\n git-gui mainporcelain\n git-hash-object plumbingmanipulators\n-git-help\t\t\t\tancillaryinterrogators\n+git-help ancillaryinterrogators\n git-http-backend synchingrepositories\n 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 +89,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\n git-name-rev plumbinginterrogators\n git-notes mainporcelain\n git-p4 foreignscminterface\n@@ -90,11 +100,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\n git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n@@ -103,28 +113,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\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\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\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n@@ -138,4 +148,4 @@ git-verify-pack plumbinginterrogators\n git-verify-tag ancillaryinterrogators\n gitweb ancillaryinterrogators\n git-whatchanged ancillaryinterrogators\n-git-write-tree plumbingmanipulators\n+git-write-tree plumbingmanipulators\n\\ No newline at end of file\n-- \n2.4.0\n"},{"id":"260548","messageId":"a787babf25481c99edea6dca5e5f7814601395fe.1430770308.git.sebastien.guimmara@gmail.com","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"[PATCH 2/3] generate-cmdlist.sh: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-04T20:28:09Z","receivedAt":"2015-05-04T20:28:09Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"parse the [groups] block to create the array of group descriptions\n\n static 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\n static 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 working tree\"), 4},\n {\"clone\", N_(\"Clone a repository into a new directory\"), 0},\n {\"commit\", N_(\"Record changes to the repository\"), 4},\n [...]\n\nSo that 'git help' can print those command grouped by theme.\n\nHelped-by: Junio C Hamano \nHelped-by: Eric Sunshine \nSigned-off-by: Sébastien Guimmara \n---\n generate-cmdlist.sh | 43 +++++++++++++++++++++++++++++++------------\n 1 file changed, 31 insertions(+), 12 deletions(-)\n\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\nindex 9a4c9b9..724bb8d 100755\n--- a/generate-cmdlist.sh\n+++ b/generate-cmdlist.sh\n@@ -1,23 +1,42 @@\n #!/bin/sh\n+content=$(cat command-list.txt)\n+\n+group_line_no=$(expr $(echo \"$content\" | grep -n '^\\[groups\\]' | cut -f1 -d:) + 1)\n+command_line_no=$(expr $(echo \"$content\" | grep -n '^\\[commands\\]' | cut -f1 -d:) + 1)\n+groups=$(echo \"$content\" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')\n \n echo \"/* Automatically generated by $0 */\n+\n struct cmdname_help {\n char name[16];\n char help[80];\n+ unsigned char group;\n };\n \n+static char *common_cmd_groups[] = {\"\n+echo \"$groups\" |\n+while read group description; do\n+ if [ -z $group ]; then\n+ break\n+ fi\n+ echo ' N_(\"'$description'\"),'\n+done\n+echo \"};\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+echo \"$content\" | grep 'common-' |\n+awk '{ print $1, \"\\t\", $3 }' |\n+while read cmd grp; do\n+ cmd_name=$(echo $cmd | cut -d - -f 2)\n+ group_name=$(echo $grp | cut -d - -f 2)\n+ group_idx=$(expr $(echo \"$groups\" | grep -n \"^$group_name\" | cut -c 1) - 1)\n+ sed -n '\n+ /^NAME/,/git-'\"$cmd_name\"'/H\n+ ${\n+ x\n+ s/.*git-'\"$cmd_name\"' - \\(.*\\)/ {\"'\"$cmd_name\"'\", N_(\"\\1\"), '\"$group_idx\"'},/\n+ p\n+ }' \"Documentation/$cmd.txt\"\n done\n-echo \"};\"\n+echo \"};\"\n\\ No newline at end of file\n-- \n2.4.0\n"},{"id":"260547","messageId":"13c3dcbd2c5c9dfc0453381b5da53b5d68af7afe.1430770308.git.sebastien.guimmara@gmail.com","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"[PATCH 3/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-04T20:28:10Z","receivedAt":"2015-05-04T20:28:10Z","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 group commands by\nconcept, like this:\n\nThe most commonly used git commands are:\n\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 * working on the current change:\n add Add file contents to the index\n reset Reset current HEAD to the specified state\n [...]\n\nHelped-by: Junio C Hamano \nHelped-by: Eric Sunshine \nSigned-off-by: Sébastien Guimmara \n---\n help.c | 28 +++++++++++++++++++++++++++-\n 1 file changed, 27 insertions(+), 1 deletion(-)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..c8b0bb6 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,\n \t}\n }\n \n+int cmd_group_cmp(const void *elem1, const void *elem2)\n+{\n+\tint group1, group2;\n+\n+\tgroup1 = ((struct cmdname_help *) elem1)->group;\n+\tgroup2 = ((struct cmdname_help *) elem2)->group;\n+\n+\tif (group1 == group2)\n+\t\treturn 0;\n+\tif (group1 > group2)\n+\t\treturn 1;\n+\telse\n+\t\treturn -1;\n+}\n+\n void list_common_cmds_help(void)\n {\n \tint i, longest = 0;\n+\tunsigned char 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+\tqsort(common_cmds, ARRAY_SIZE(common_cmds),\n+\t\tsizeof(common_cmds[0]), cmd_group_cmp);\n+\n \tputs(_(\"The most commonly used git commands are:\"));\n+\n \tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n-\t\tprintf(\" %s \", common_cmds[i].name);\n+\t\tif (common_cmds[i].group != current_grp) {\n+\t\t\tprintf(\"\\n * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n+\t\t}\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 \t}\n-- \n2.4.0\n"},{"id":"260638","messageId":"CAPig+cT9X-nXhQyjDtzLzm-A2LWLaCDThR9_xh=G049SqKHccw@mail.gmail.com","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-06T03:08:28Z","receivedAt":"2015-05-06T03:08:28Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n wrote:\n> This v4 includes the following suggestions:\n>\n> In command-list.txt:\n> - Add a [groups] block containing names and description for groups:\n>\n> [groups]\n> init starting a working area\n> worktree working on the current change\n> remote working with others\n> info examining the history and state\n> history growing, marking and tweaking your history\n>\n> - Add a [commands] header on top of the known command list, and\n> group names as a third column.\n>\n> [commands]\n> git-add mainporcelain common-worktree\n> git-am mainporcelain\n> git-annotate ancillaryinterrogators\n> git-apply plumbingmanipulators\n> git-archimport foreignscminterface\n> git-archive mainporcelain\n> git-bisect mainporcelain\n> git-blame ancillaryinterrogators\n> git-branch mainporcelain common-history\n\nThanks, this version is looking better. I, personally, still find the\nredundant \"command-\" prefix ugly and would just as soon see it go\naway. I'll make some suggestions about that when reviewing patch 2/3.\n\nMore below.\n\n> This produces the following output of $ git help:\n>\n> [...]\n> The most commonly used git commands are:\n>\n> * starting a working area:\n> clone Clone a repository into a new directory\n> init Create an empty Git repository or reinitialize [...]\n>\n> * working on the current change:\n> add Add file contents to the index\n> reset Reset current HEAD to the specified state\n>\n> * working with others:\n> fetch Download objects and refs from another repository\n> pull Fetch from and integrate with another repository [...]\n> push Update remote refs along with associated objects\n>\n> * examining the history and state:\n> log Show commit logs\n> status Show the working tree status\n>\n> * growing, marking and tweaking your history:\n> branch List, create, or delete branches\n> checkout Checkout a branch or paths to the working tree\n> commit Record changes to the repository\n> diff Show changes between commits, commit and working [...]\n> merge Join two or more development histories together\n> [...]\n>\n> I removed from the list of common commands: rebase, rm, mv, bisect\n> because [1] they are not really common to an unfamiliar user, [2] to\n> save vertical space occupied by group headers.\n\nPlease perform the removals in a separate (preparatory) patch. Not\nonly is it difficult to spot the removals mixed in with the primary\nchanges of 1/3, but they are not even mentioned in the commit message\nof that patch. More generally, the removals are a logically distinct\nchange from assigning groupings to the common commands, thus deserve\ntheir own patch.\n"},{"id":"260639","messageId":"CAPig+cS=u-HK1qNicWiLOQC6RPkR7QueX+kOu8fQwpHekgs1yg@mail.gmail.com","threadId":"39246","inReplyTo":"13c3dcbd2c5c9dfc0453381b5da53b5d68af7afe.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-06T03:16:37Z","receivedAt":"2015-05-06T03:16:37Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n wrote:\n> 'git help' shows common commands in alphabetical order:\n>\n> The most commonly used git commands are:\n> add Add file contents to the index\n> bisect Find by binary search the change that introduced a bug\n> branch List, create, or delete branches\n> checkout Checkout a branch or paths to the working tree\n> clone Clone a repository into a new directory\n> commit Record changes to the repository\n> [...]\n>\n> without any indication of how commands relate to high-level\n> concepts or each other. Revise the output to group commands by\n> concept, like this:\n>\n> The most commonly used git commands are:\n>\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> * working on the current change:\n> add Add file contents to the index\n> reset Reset current HEAD to the specified state\n> [...]\n\nThis looks better. A couple minor style nits and a question below...\n\n> ---\n> diff --git a/help.c b/help.c\n> index 2072a87..c8b0bb6 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,\n> }\n> }\n>\n> +int cmd_group_cmp(const void *elem1, const void *elem2)\n> +{\n> + int group1, group2;\n> +\n> + group1 = ((struct cmdname_help *) elem1)->group;\n> + group2 = ((struct cmdname_help *) elem2)->group;\n\nStyle: Drop space after the cast: (type *)var\n\n> +\n> + if (group1 == group2)\n> + return 0;\n> + if (group1 > group2)\n> + return 1;\n> + else\n> + return -1;\n\nDo you also want to sort the commands alphabetically within group?\nThat is, something like this?\n\n struct cmdname_help *e1 = elem1;\n struct cmdname_help *e2 = elem2;\n\n if (e1->group < e2->group)\n return -1;\n if (e1->group > e2->group)\n return 1;\n return strcmp(e1->name, e2->name);\n\n> +}\n> +\n> void list_common_cmds_help(void)\n> {\n> int i, longest = 0;\n> + unsigned char 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> + qsort(common_cmds, ARRAY_SIZE(common_cmds),\n> + sizeof(common_cmds[0]), cmd_group_cmp);\n> +\n> puts(_(\"The most commonly used git commands are:\"));\n> +\n> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n> - printf(\" %s \", common_cmds[i].name);\n> + if (common_cmds[i].group != current_grp) {\n> + printf(\"\\n * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n> + }\n\nStyle: Drop unnecessary braces.\n\n> + current_grp = common_cmds[i].group;\n\nAlternately, move this assignment inside the braces.\n\n> + printf(\" %s \", common_cmds[i].name);\n> mput_char(' ', longest - strlen(common_cmds[i].name));\n> puts(_(common_cmds[i].help));\n> }\n> --\n> 2.4.0\n"},{"id":"260640","messageId":"xmqqegmucqyh.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-06T03:41:58Z","receivedAt":"2015-05-06T03:41:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> command-list.txt | 64 +++++++++++++++++++++++++++++++----------------------\n> generate-cmdlist.sh | 43 +++++++++++++++++++++++++----------\n> help.c | 28 ++++++++++++++++++++++-\n\nI did not apply any of these patches to my tree, but\n\n $ git grep command-list.txt\n\nshows that Documentation/Makefile and Makefile reads from\ncommand-list.txt to do their own useful tasks. A patch series that\ndoes not touch either of them makes me suspect that it may be\nbreaking a lot of things.\n"},{"id":"260650","messageId":"CAPig+cTHQikgOvPrjxikUNjQoWCv2hdubJ55OG0SqpGUs_3Pow@mail.gmail.com","threadId":"39246","inReplyTo":"b89d3fec640cb6fb01aa32ad50bae4e064528220.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-06T06:57:43Z","receivedAt":"2015-05-06T06:57:43Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n wrote:\n> Declare groups for common commands in the [groups] block,\n> followed by group names and descriptions:\n>\n> [groups]\n> init starting a working area\n> worktree working on the current change\n> remote working with others\n> info examining the history and state\n> history growing, marking and tweaking your history\n>\n> Then, in the [commands] block, map all common commands with a group:\n>\n> [commands]\n> git-add mainporcelain common-worktree\n> git-branch mainporcelain common-history\n> git-checkout mainporcelain common-history\n> [...]\n>\n> command names and groups are then parsed with generate-cmdlist.sh to\n> generate common-commands.h.\n>\n> Those commands are displayed in groups in the output of 'git help'.\n\nIt probably also is important to mention that the order of the items\nin [groups] is the order in which groups are output by 'git help'\n\nMore below.\n\n> Signed-off-by: Sébastien Guimmara \n> ---\n> diff --git a/command-list.txt b/command-list.txt\n> index f1eae08..64394ca 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -1,29 +1,39 @@\n> # List of known git commands.\n> -# command name category [deprecated] [common]\n> -git-add mainporcelain common\n> +# only add group information for common commands\n\nPerhaps mention also that the order of groups here is the order in\nwhich they are output by 'git help'?\n\n> +[groups]\n\nThinking on this a bit more, perhaps [groups] is too generic. Maybe\n[common] or [commongroups] would be more descriptive?\n\n> +init starting a working area\n> +worktree working on the current change\n> +remote working with others\n\n\"collaborating with others\" perhaps?\n\nMore below.\n\n> +info examining the history and state\n> +history growing, marking and tweaking your history\n> +\n> +# command name [deprecated] category [group]\n> +[commands]\n> +git-add mainporcelain common-worktree\n> [...]\n> -git-bisect mainporcelain common\n> +git-bisect mainporcelain\n> [...]\n> -git-branch mainporcelain common\n> +git-branch mainporcelain common-history\n> [...]\n> -git-checkout mainporcelain common\n> +git-checkout mainporcelain common-history\n> [...]\n> -git-clone mainporcelain common\n> +git-clone mainporcelain common-init\n> [...]\n> -git-commit mainporcelain common\n> +git-commit mainporcelain common-history\n> [...]\n> -git-diff mainporcelain common\n> +git-diff mainporcelain common-history\n> [...]\n> -git-fast-export ancillarymanipulators\n> -git-fast-import ancillarymanipulators\n> -git-fetch mainporcelain common\n> +git-fast-export ancillarymanipulators\n> +git-fast-import ancillarymanipulators\n\nUnintended whitespace changes for fast-export and fast-import lines? I\nwouldn't have expected to see these lines change in this patch.\n\n> +git-fetch mainporcelain common-remote\n> [...]\n> -git-fsck ancillaryinterrogators\n> +git-fsck ancillaryinterrogators\n\nUnintended whitespace change?\n\n> [...]\n> -git-grep mainporcelain common\n> +git-grep mainporcelain\n\nThis change isn't mentioned anywhere, not even in the cover letter.\nDid you intend to drop 'grep' from the common command list?\n\n> [...]\n> -git-help ancillaryinterrogators\n> +git-help ancillaryinterrogators\n\nWhitespace change?\n\nMore below.\n\n> [...]\n> -git-init mainporcelain common\n> +git-init mainporcelain common-init\n> [...]\n> -git-log mainporcelain common\n> +git-log mainporcelain common-info\n> [...]\n> -git-merge mainporcelain common\n> +git-merge mainporcelain common-history\n> [...]\n> -git-mv mainporcelain common\n> +git-mv mainporcelain\n> [...]\n> -git-pull mainporcelain common\n> -git-push mainporcelain common\n> +git-pull mainporcelain common-remote\n> +git-push mainporcelain common-remote\n> [...]\n> -git-rebase mainporcelain common\n> +git-rebase mainporcelain\n> [...]\n> -git-reset mainporcelain common\n> +git-reset mainporcelain common-worktree\n> [...]\n> -git-rm mainporcelain common\n> +git-rm mainporcelain\n> [...]\n> -git-show mainporcelain common\n> +git-show mainporcelain\n> [...]\n> -git-status mainporcelain common\n> +git-status mainporcelain common-info\n> [...]\n> -git-tag mainporcelain common\n> +git-tag mainporcelain\n\nThis change also is not mentioned anywhere.\n\n> [...]\n> -git-write-tree plumbingmanipulators\n> +git-write-tree plumbingmanipulators\n> \\ No newline at end of file\n\nYour editor is perhaps dropping the final newline in the file? This is\nan undesirable change. Patch 2/3 exhibits the same problem.\n\n> --\n> 2.4.0\n"},{"id":"260652","messageId":"vpqfv7ap25j.fsf@anie.imag.fr","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-05-06T07:59:20Z","receivedAt":"2015-05-06T07:59:20Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Sébastien Guimmara writes:\n\n> * examining the history and state:\n> log Show commit logs\n> status Show the working tree status\n>\n> * growing, marking and tweaking your history:\n> branch List, create, or delete branches\n> checkout Checkout a branch or paths to the working tree\n> commit Record changes to the repository\n> diff Show changes between commits, commit and working [...]\n> merge Join two or more development histories together\n\nI would have put \"diff\" next to \"status\" in the \"examining the history\nand state\" section. It's neither growing, marking nor tweaking the\nhistory.\n\n> I removed from the list of common commands: rebase, rm, mv, bisect \n> because [1] they are not really common to an unfamiliar user,\n\nI tend to agree for rebase and bisect (even though showing them to\nbeginners may give them a hint on why Git can be good for them).\n\nBut removing rm and mv seems weird. It seems to me that the obvious\nquestion of someone who just learnt \"add\" would be \"and how do I do the\nopposite?\".\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"260670","messageId":"xmqqoalxbo0w.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"vpqfv7ap25j.fsf@anie.imag.fr","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-06T17:42:55Z","receivedAt":"2015-05-06T17:42:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Sébastien Guimmara writes:\n>\n>> * examining the history and state:\n>> log Show commit logs\n>> status Show the working tree status\n>>\n>> * growing, marking and tweaking your history:\n>> branch List, create, or delete branches\n>> checkout Checkout a branch or paths to the working tree\n>> commit Record changes to the repository\n>> diff Show changes between commits, commit and working [...]\n>> merge Join two or more development histories together\n>\n> I would have put \"diff\" next to \"status\" in the \"examining the history\n> and state\" section. It's neither growing, marking nor tweaking the\n> history.\n\nI am somewhat torn on this.\n\nYour suggestion is about \"what does this command do?\" Which is a\nperfectly acceptable way to categorize commands once you nailed your\nworkflow down.\n\nThere is another school of thought to organize them according to \"in\nwhich phase in your development cycle do you use this command?\",\ni.e. more workflow oriented categorization. From this point of\nview, \"diff\" and \"status\" are important tools you use while \"growing\nyour own history\".\n\n> But removing rm and mv seems weird. It seems to me that the obvious\n> question of someone who just learnt \"add\" would be \"and how do I do the\n> opposite?\".\n\nAnd the answer may confuse that someone even further (it is not\nnecessarily \"rm\", but is often \"reset\"). As a list of simple\ncommand set to help the dip-your-toes-in-water process, a new user\nmay be better off starting with \"add\", \"add .\" and \"commit -a\", and\nlearn from the last part of \"git add --help\" that there are \"rm\" and\n\"mv\" (both of which happen a lot less often than \"add\").\n"},{"id":"260690","messageId":"554A78EE.1040002@gmail.com","threadId":"39246","inReplyTo":"CAPig+cT9X-nXhQyjDtzLzm-A2LWLaCDThR9_xh=G049SqKHccw@mail.gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-06T20:26:22Z","receivedAt":"2015-05-06T20:26:22Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/06/2015 05:08 AM, Eric Sunshine wrote:\n> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n> wrote:\n>> This v4 includes the following suggestions:\n>>\n>> In command-list.txt:\n>> - Add a [groups] block containing names and description for groups:\n>>\n>> [groups]\n>> init starting a working area\n>> worktree working on the current change\n>> remote working with others\n>> info examining the history and state\n>> history growing, marking and tweaking your history\n>>\n>> - Add a [commands] header on top of the known command list, and\n>> group names as a third column.\n>>\n>> [commands]\n>> git-add mainporcelain common-worktree\n>> git-am mainporcelain\n>> git-annotate ancillaryinterrogators\n>> git-apply plumbingmanipulators\n>> git-archimport foreignscminterface\n>> git-archive mainporcelain\n>> git-bisect mainporcelain\n>> git-blame ancillaryinterrogators\n>> git-branch mainporcelain common-history\n>\n> Thanks, this version is looking better. I, personally, still find the\n> redundant \"command-\" prefix ugly and would just as soon see it go\n> away. I'll make some suggestions about that when reviewing patch 2/3.\n\nIndeed, I'm a bit annoyed by this prefix. We could do two things:\n- either drop the [deprecated] options, since it's never used.\n- or keep it, but make it exclusive with [common]. It makes sense after\n all that if a command is deprecated, we don't want to consider it\n common anymore.\n\nIn both cases, we end up with only three columns, the third being\noptional.\n\nThe common- prefix can then be removed in favor of the group ID alone.\n\n>> I removed from the list of common commands: rebase, rm, mv, bisect\n>> because [1] they are not really common to an unfamiliar user, [2] to\n>> save vertical space occupied by group headers.\n>\n> Please perform the removals in a separate (preparatory) patch. Not\n> only is it difficult to spot the removals mixed in with the primary\n> changes of 1/3, but they are not even mentioned in the commit message\n> of that patch. More generally, the removals are a logically distinct\n> change from assigning groupings to the common commands, thus deserve\n> their own patch.\n>\n\nThanks. I will separate both patches.\n"},{"id":"260692","messageId":"554A7A31.1080604@gmail.com","threadId":"39246","inReplyTo":"CAPig+cS=u-HK1qNicWiLOQC6RPkR7QueX+kOu8fQwpHekgs1yg@mail.gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-06T20:31:45Z","receivedAt":"2015-05-06T20:31:45Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/06/2015 05:16 AM, Eric Sunshine wrote:\n> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n> wrote:\n>> 'git help' shows common commands in alphabetical order:\n>>\n>> The most commonly used git commands are:\n>> add Add file contents to the index\n>> bisect Find by binary search the change that introduced a bug\n>> branch List, create, or delete branches\n>> checkout Checkout a branch or paths to the working tree\n>> clone Clone a repository into a new directory\n>> commit Record changes to the repository\n>> [...]\n>>\n>> without any indication of how commands relate to high-level\n>> concepts or each other. Revise the output to group commands by\n>> concept, like this:\n>>\n>> The most commonly used git commands are:\n>>\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>> * working on the current change:\n>> add Add file contents to the index\n>> reset Reset current HEAD to the specified state\n>> [...]\n>\n> This looks better. A couple minor style nits and a question below...\n>\n>> ---\n>> diff --git a/help.c b/help.c\n>> index 2072a87..c8b0bb6 100644\n>> --- a/help.c\n>> +++ b/help.c\n>> @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts,\n>> }\n>> }\n>>\n>> +int cmd_group_cmp(const void *elem1, const void *elem2)\n>> +{\n>> + int group1, group2;\n>> +\n>> + group1 = ((struct cmdname_help *) elem1)->group;\n>> + group2 = ((struct cmdname_help *) elem2)->group;\n>\n> Style: Drop space after the cast: (type *)var\n>\n>> +\n>> + if (group1 == group2)\n>> + return 0;\n>> + if (group1 > group2)\n>> + return 1;\n>> + else\n>> + return -1;\n>\n> Do you also want to sort the commands alphabetically within group?\n> That is, something like this?\n>\n> struct cmdname_help *e1 = elem1;\n> struct cmdname_help *e2 = elem2;\n>\n> if (e1->group < e2->group)\n> return -1;\n> if (e1->group > e2->group)\n> return 1;\n> return strcmp(e1->name, e2->name);\n>\n\nHmmm yes. Good idea.\n\n>> +}\n>> +\n>> void list_common_cmds_help(void)\n>> {\n>> int i, longest = 0;\n>> + unsigned char 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>> + qsort(common_cmds, ARRAY_SIZE(common_cmds),\n>> + sizeof(common_cmds[0]), cmd_group_cmp);\n>> +\n>> puts(_(\"The most commonly used git commands are:\"));\n>> +\n>> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n>> - printf(\" %s \", common_cmds[i].name);\n>> + if (common_cmds[i].group != current_grp) {\n>> + printf(\"\\n * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n>> + }\n>\n> Style: Drop unnecessary braces.\n\nUnderstood.\n"},{"id":"260693","messageId":"CAPig+cTztwF-pYGjEpjDzxTJSXQBJFcp_F924htx5fHT01mcKQ@mail.gmail.com","threadId":"39246","inReplyTo":"554A78EE.1040002@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-06T20:49:59Z","receivedAt":"2015-05-06T20:49:59Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, May 6, 2015 at 4:26 PM, Sébastien Guimmara\n wrote:\n> On 05/06/2015 05:08 AM, Eric Sunshine wrote:\n>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>> wrote:\n>>> - Add a [groups] block containing names and description for groups:\n>>>\n>>> [groups]\n>>> init starting a working area\n>>>\n>>> - Add a [commands] header on top of the known command list, and\n>>> group names as a third column.\n>>>\n>>> [commands]\n>>> git-add mainporcelain common-worktree\n>>\n>> Thanks, this version is looking better. I, personally, still find the\n>> redundant \"command-\" prefix ugly and would just as soon see it go\n>> away. I'll make some suggestions about that when reviewing patch 2/3.\n>\n> Indeed, I'm a bit annoyed by this prefix. We could do two things:\n> - either drop the [deprecated] options, since it's never used.\n> - or keep it, but make it exclusive with [common]. It makes sense after\n> all that if a command is deprecated, we don't want to consider it\n> common anymore.\n>\n> In both cases, we end up with only three columns, the third being\n> optional.\n>\n> The common- prefix can then be removed in favor of the group ID alone.\n\nSorry for not yet reviewing patch 2/3. I'm trying to find time to\nreview it and make the promised suggestions, however, Real Life keeps\ngetting in the way. If 'deprecated' has never been used and if it is\nnot likely to be used in the future, then dropping that column may\nindeed be an easy way forward toward the goal of eliminating the\n\"common-\" prefix. A possible shortcoming of this columnar approach,\nhowever, is that if someone someday comes up with some new type of\nattribute to assign in a new column, then you still end up in the same\nboat where not all entries use all columns, and you have difficulty\nfiguring out to which column an attribute belongs.\n\nInstead, as mentioned originally, I had envisioned a solution in which\nany command tagged with an attribute mentioned in [groups] would be\nconsidered common, without having to resort to a prefix or fixed\ncolumns. This should be more flexible in the long run, but may be\noverkill for present day. I think that awk should be able to handle\nthis easily, but haven't had the time to actually sit down and flesh\nit out (which I wanted to do while reviewing 2/3).\n\nAnd, any solution is likely going to have to take into account the two\nMakefiles Junio mentioned.\n"},{"id":"260694","messageId":"554A8084.10506@gmail.com","threadId":"39246","inReplyTo":"CAPig+cTHQikgOvPrjxikUNjQoWCv2hdubJ55OG0SqpGUs_3Pow@mail.gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-06T20:58:44Z","receivedAt":"2015-05-06T20:58:44Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/06/2015 08:57 AM, Eric Sunshine wrote:\n> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n> wrote:\n>> Declare groups for common commands in the [groups] block,\n>> followed by group names and descriptions:\n>>\n>> [groups]\n>> init starting a working area\n>> worktree working on the current change\n>> remote working with others\n>> info examining the history and state\n>> history growing, marking and tweaking your history\n>>\n>> Then, in the [commands] block, map all common commands with a group:\n>>\n>> [commands]\n>> git-add mainporcelain common-worktree\n>> git-branch mainporcelain common-history\n>> git-checkout mainporcelain common-history\n>> [...]\n>>\n>> command names and groups are then parsed with generate-cmdlist.sh to\n>> generate common-commands.h.\n>>\n>> Those commands are displayed in groups in the output of 'git help'.\n>\n> It probably also is important to mention that the order of the items\n> in [groups] is the order in which groups are output by 'git help'\n\nYes. I'll add a comment in the file as well as in the commit.\n\n>\n> More below.\n>\n>> Signed-off-by: Sébastien Guimmara \n>> ---\n>> diff --git a/command-list.txt b/command-list.txt\n>> index f1eae08..64394ca 100644\n>> --- a/command-list.txt\n>> +++ b/command-list.txt\n>> @@ -1,29 +1,39 @@\n>> # List of known git commands.\n>> -# command name category [deprecated] [common]\n>> -git-add mainporcelain common\n>> +# only add group information for common commands\n>\n> Perhaps mention also that the order of groups here is the order in\n> which they are output by 'git help'?\n\nIt wouldn't be necessary if we reorder alphabetically the content of\neach group, no ?\n\n>\n>> +[groups]\n>\n> Thinking on this a bit more, perhaps [groups] is too generic. Maybe\n> [common] or [commongroups] would be more descriptive?\n>\n>> +init starting a working area\n>> +worktree working on the current change\n>> +remote working with others\n>\n> \"collaborating with others\" perhaps?\n\nYes, \"groups\" has been itching a bit. I thought about \"theme\", but\ncommon just does the job too. \"collaborating with others\" sounds\nredundant to me (but I'm being a grammar nazi here).\n\n>> -git-fast-export ancillarymanipulators\n>> -git-fast-import ancillarymanipulators\n>> -git-fetch mainporcelain common\n>> +git-fast-export ancillarymanipulators\n>> +git-fast-import ancillarymanipulators\n>\n> Unintended whitespace changes for fast-export and fast-import lines? I\n> wouldn't have expected to see these lines change in this patch.\n>\n\nAll whitespace changes were intended to align the commands on the same\ncolumn. I realize this should be the object of a separate patch.\n\n>> -git-grep mainporcelain common\n>> +git-grep mainporcelain\n>\n> This change isn't mentioned anywhere, not even in the cover letter.\n> Did you intend to drop 'grep' from the common command list?\n\nIt's a mistake in the cover letter. I indeed intended to propose to\nremove grep and tag from the common commands.\n\n>> [...]\n>> -git-write-tree plumbingmanipulators\n>> +git-write-tree plumbingmanipulators\n>> \\ No newline at end of file\n>\n> Your editor is perhaps dropping the final newline in the file? This is\n> an undesirable change. Patch 2/3 exhibits the same problem.\n\nAs for the final newline, it was deliberately removed. I was not aware it\nwas necessary in text files. I'll correct this.\n\nThank you for the help,\n\nSébastien\n"},{"id":"260704","messageId":"vpqbnhw4w3r.fsf@anie.imag.fr","threadId":"39246","inReplyTo":"xmqqoalxbo0w.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-05-07T08:42:32Z","receivedAt":"2015-05-07T08:42:32Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> And the answer may confuse that someone even further (it is not\n> necessarily \"rm\", but is often \"reset\"). As a list of simple\n> command set to help the dip-your-toes-in-water process, a new user\n> may be better off starting with \"add\", \"add .\" and \"commit -a\", and\n> learn from the last part of \"git add --help\" that there are \"rm\" and\n> \"mv\" (both of which happen a lot less often than \"add\").\n\nIf one wonders how to remove a file from Git, expecting that user to\nlook at the doc for \"git add\" to find out seems really backwards to me.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"260720","messageId":"554B30D5.3050909@emmajane.net","threadId":"39246","inReplyTo":"cover.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Emma Jane Hogbin Westby","fromEmail":"emma.westby@gmail.com","sentAt":"2015-05-07T09:31:01Z","receivedAt":"2015-05-07T09:31:01Z","isPatch":true,"sender":{"key":"emma.westby@gmail.com","avatar":null},"body":"Sébastien !\n\nThis is fantastic! My apologies for jumping in late. Hopefully I'm not \ntoo late.\n\n\nSébastien Guimmara wrote:\n> This v4 includes the following suggestions:\n>\n> In command-list.txt:\n> - Add a [groups] block containing names and description for groups:\n>\n> [groups]\n> init starting a working area\n> worktree working on the current change\n> remote working with others\n> info examining the history and state\n> history growing, marking and tweaking your history\nI like these headings / separation.\n\nAs you've already \"lost\" a line to the header, would it make sense to \nadd a \"see also\" into the Guides from here? For example:\n\nstarting a working area (see also: git help tutorial)\nworking on the current change (see also: git help everyday)\nworking with others (see also: git help workflows)\nexamining the history and state (see also: git help revisions)\n\n[...]\n> This produces the following output of $ git help:\n>\n> [...]\n> The most commonly used git commands are:\n>\n> * starting a working area:\n> clone Clone a repository into a new directory\n> init Create an empty Git repository or reinitialize [...]\n>\n> * working on the current change:\n> add Add file contents to the index\n> reset Reset current HEAD to the specified state\nI could not live without status at this stage, and status always tells \nme what I should do next. I'm tempted to see it up here instead...\n\n> * working with others:\n> fetch Download objects and refs from another repository\n> pull Fetch from and integrate with another repository [...]\n> push Update remote refs along with associated objects\n>\n> * examining the history and state:\n> log Show commit logs\n> status Show the working tree status\nFor this grouping, instead of also having \"state\", I'd like to see log \nand diff. Perhaps the header is simply \"examining the history\". This \nnarrowing would make more sense to then move status up to \"working on \nthe current change\".\n\n> * growing, marking and tweaking your history:\n> branch List, create, or delete branches\n> checkout Checkout a branch or paths to the working tree\n> commit Record changes to the repository\n> diff Show changes between commits, commit and working [...]\n> merge Join two or more development histories together\nBy the definition of \"tweaking\" I would include rebase. Hiding rebase \nfrom the \"common\" list will increase its mystique and make people even \nmore hesitant to use it. Best to shine some light on it and help to make \nit less scary. I would remove diff from this group as it is a \nnon-destructive command.\n\nWhat a wonderful thing to have started, Sébastien ! Thank you. :)\n"},{"id":"260744","messageId":"CAPig+cQ2e4c5hYsRbZhgyvLcMPsqshqRUZGNLwhJd57YP9JEFA@mail.gmail.com","threadId":"39246","inReplyTo":"554A8084.10506@gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-07T16:50:29Z","receivedAt":"2015-05-07T16:50:29Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara\n wrote:\n> On 05/06/2015 08:57 AM, Eric Sunshine wrote:\n>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>> wrote:\n>>> Signed-off-by: Sébastien Guimmara \n>>> ---\n>>> diff --git a/command-list.txt b/command-list.txt\n>>> index f1eae08..64394ca 100644\n>>> --- a/command-list.txt\n>>> +++ b/command-list.txt\n>>> @@ -1,29 +1,39 @@\n>>> # List of known git commands.\n>>> -# command name category [deprecated] [common]\n>>> -git-add mainporcelain common\n>>> +# only add group information for common commands\n>>\n>> Perhaps mention also that the order of groups here is the order in\n>> which they are output by 'git help'?\n>\n> It wouldn't be necessary if we reorder alphabetically the content of\n> each group, no ?\n\nI'm not sure to what you are referring here? (Perhaps my comment was\nunclear, or perhaps I'm misreading your response.)\n\nI meant only that the comment above [groups] should say that the order\nof the items in [groups] is the order in which the groups themselves\nare output by \"git help\".\n\n>>> +[groups]\n>>\n>> Thinking on this a bit more, perhaps [groups] is too generic. Maybe\n>> [common] or [commongroups] would be more descriptive?\n>>\n>>> +init starting a working area\n>>> +worktree working on the current change\n>>> +remote working with others\n>>\n>> \"collaborating with others\" perhaps?\n>\n> Yes, \"groups\" has been itching a bit. I thought about \"theme\", but\n> common just does the job too. \"collaborating with others\" sounds\n> redundant to me (but I'm being a grammar nazi here).\n\nI also think \"collaborating\" itself is best, but changed it at the\nlast second before sending the email.\n\n>>> -git-fast-export ancillarymanipulators\n>>> -git-fast-import ancillarymanipulators\n>>> -git-fetch mainporcelain common\n>>> +git-fast-export ancillarymanipulators\n>>> +git-fast-import ancillarymanipulators\n>>\n>> Unintended whitespace changes for fast-export and fast-import lines? I\n>> wouldn't have expected to see these lines change in this patch.\n>\n> All whitespace changes were intended to align the commands on the same\n> column. I realize this should be the object of a separate patch.\n\nStrange. In my editor, all columns are already aligned. Perhaps your\ntab with setting is incorrect? (It should be set to 8.)\n\n>>> -git-grep mainporcelain common\n>>> +git-grep mainporcelain\n>>\n>> This change isn't mentioned anywhere, not even in the cover letter.\n>> Did you intend to drop 'grep' from the common command list?\n>\n> It's a mistake in the cover letter. I indeed intended to propose to\n> remove grep and tag from the common commands.\n\nI personally consider \"grep\" an important beginner command, but that's\nan issue to be argued separately; and it's also why it's a good idea\nto put the removals in their own patch, so people can argue about it\nwithout holding up the rest of the patches.\n\n>>> [...]\n>>> -git-write-tree plumbingmanipulators\n>>> +git-write-tree plumbingmanipulators\n>>> \\ No newline at end of file\n>>\n>> Your editor is perhaps dropping the final newline in the file? This is\n>> an undesirable change. Patch 2/3 exhibits the same problem.\n>\n> As for the final newline, it was deliberately removed. I was not aware it\n> was necessary in text files. I'll correct this.\n\nHistorically, many Unix tools incorrectly handled files lacking that\nfinal newline; sometimes by dropping the line altogether, sometimes\nmis-processing it in some way or another. Misbehaviors still exist\ntoday, often in BSD tools. In fact, just a few days ago, such a\nproblem was reported for git-filter-branch[1]. Consequently, retaining\nnewline is good insurance against misbehaving tools.\n\n[1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957\n"},{"id":"260771","messageId":"xmqq7fskp6qf.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"vpqbnhw4w3r.fsf@anie.imag.fr","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-07T18:44:56Z","receivedAt":"2015-05-07T18:44:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Junio C Hamano writes:\n>\n>> And the answer may confuse that someone even further (it is not\n>> necessarily \"rm\", but is often \"reset\"). As a list of simple\n>> command set to help the dip-your-toes-in-water process, a new user\n>> may be better off starting with \"add\", \"add .\" and \"commit -a\", and\n>> learn from the last part of \"git add --help\" that there are \"rm\" and\n>> \"mv\" (both of which happen a lot less often than \"add\").\n>\n> If one wonders how to remove a file from Git, expecting that user to\n> look at the doc for \"git add\" to find out seems really backwards to me.\n\nYeah, but you are moving the goalpost.\n\nWhat you are reponding to is my reaction to your earlier \"the\nobvious question of someone who just learnt 'add' would be 'and how\ndo I do the _opposite_?'\". And I would expect such a person to look\nat 'add' to find 'SEE ALSO' section.\n"},{"id":"260777","messageId":"554BBBAF.30705@kdbg.org","threadId":"39246","inReplyTo":"CAPig+cQ2e4c5hYsRbZhgyvLcMPsqshqRUZGNLwhJd57YP9JEFA@mail.gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2015-05-07T19:23:27Z","receivedAt":"2015-05-07T19:23:27Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 07.05.2015 um 18:50 schrieb Eric Sunshine:\n> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara\n> wrote:\n>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:\n>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>>> wrote:\n>>>> -git-write-tree plumbingmanipulators\n>>>> +git-write-tree plumbingmanipulators\n>>>> \\ No newline at end of file\n>>>\n>>> Your editor is perhaps dropping the final newline in the file? This is\n>>> an undesirable change. Patch 2/3 exhibits the same problem.\n>>\n>> As for the final newline, it was deliberately removed. I was not aware it\n>> was necessary in text files. I'll correct this.\n>\n> Historically, many Unix tools incorrectly handled files lacking that\n> final newline; sometimes by dropping the line altogether, sometimes\n> mis-processing it in some way or another. Misbehaviors still exist\n> today, often in BSD tools. In fact, just a few days ago, such a\n> problem was reported for git-filter-branch[1]. Consequently, retaining\n> newline is good insurance against misbehaving tools.\n\nFiles lacking the trailing new-line are not \"text files\" according to \nthe POSIX definition, BTW.\n\n-- Hannes\n"},{"id":"260793","messageId":"20150508032011.GA10209@flurp.local","threadId":"39246","inReplyTo":"a787babf25481c99edea6dca5e5f7814601395fe.1430770308.git.sebastien.guimmara@gmail.com","subject":"Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-08T03:20:11Z","receivedAt":"2015-05-08T03:20:11Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote:\n> parse the [groups] block to create the array of group descriptions\n> \n> static char *common_cmd_groups[] = {\n> N_(\"starting a working area\"),\n> ...\n> };\n> \n> then map each element of common_cmds[] to a group via its index:\n> \n> static struct cmdname_help common_cmds[] = {\n> {\"add\", N_(\"Add file contents to the index\"), 1},\n> ...\n> \n> So that 'git help' can print those command grouped by theme.\n> ---\n> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n> @@ -1,23 +1,42 @@\n> +content=$(cat command-list.txt)\n> +\n> +group_line_no=$(expr $(echo \"$content\" | grep -n '^\\[groups\\]' | cut -f1 -d:) + 1)\n> +command_line_no=$(expr $(echo \"$content\" | grep -n '^\\[commands\\]' | cut -f1 -d:) + 1)\n> +groups=$(echo \"$content\" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')\n> [...]\n> +static char *common_cmd_groups[] = {\"\n> +echo \"$groups\" |\n> +while read group description; do\n> + if [ -z $group ]; then\n> + break\n> + fi\n> + echo ' N_(\"'$description'\"),'\n> +done\n> +echo \"};\n> [...]\n> +echo \"$content\" | grep 'common-' |\n> +awk '{ print $1, \"\\t\", $3 }' |\n> +while read cmd grp; do\n> + cmd_name=$(echo $cmd | cut -d - -f 2)\n> + group_name=$(echo $grp | cut -d - -f 2)\n> + group_idx=$(expr $(echo \"$groups\" | grep -n \"^$group_name\" | cut -c 1) - 1)\n> + sed -n '\n> + /^NAME/,/git-'\"$cmd_name\"'/H\n> + ${\n> + x\n> + s/.*git-'\"$cmd_name\"' - \\(.*\\)/ {\"'\"$cmd_name\"'\", N_(\"\\1\"), '\"$group_idx\"'},/\n> + p\n> + }' \"Documentation/$cmd.txt\"\n\nBackground: In an earlier review, I observed[1] that the \"common-\" in\nthe \"common-N_group\" form was redundant, and I suggested that you\ncould add a [groups] section listing the groups, and that the order\nof items in [groups] would imply the \"git help\" display order of the\ngroups, thus allowing you to do away with the \"N_\" qualifier, as\nwell. I also observed that you could determine if a command in\n[commands] was common by checking if it was tagged with an attribute\nfrom [groups], thus alleviating the need for the \"common-\" prefix.\n\nThis round makes nice headway toward the proposed scheme, although it\nstill depends upon the redundant \"common-\" prefix. When I earlier\nsuggested that awk could be helpful[2], I was thinking of its\nassociative arrays which could be used to determine if a command in\n[commands] was tagged with an attribute from [groups].\n\nI had intended to reply to the current patch with a short \"here's\nwhat I had in mind\" example of using awk to achieve this goal,\nhowever, the short example ended up implementing the full\nfunctionality, so I went ahead and turned it into a proper patch[6]\n(below), and shamelessly re-used your commit message (with minor\nchanges). You're welcome to include this patch in your re-roll, or\nuse it as inspiration if you want to write the functionality\nyourself.\n\nSome notes about the re-implementation in awk: It assumes that\n[groups] has been renamed to [common] as suggested[3], and assumes\nthat the \"common-\" prefix has been dropped from the [commands]\nattribute entries. The awk script replaces the current shell script\nentirely, and all common-cmds.h generation functionality is now\nhandled by the one awk invocation rather than by a series of commands\ninvoked by the shell script, which should make it faster (especially\non Windows). Finally, unlike the shell script, the awk script does\nnot bother sorting commands from command-list.txt since it assumes\nthat command sorting will happen in parallel with grouping[4].\n\nWhen the awk script encounters [common], it begins collecting group\nnames in a grp[] array and emits the appropriate common_cmd_groups[]\n\"C\" initializer for each. Upon encountering [commands], it switches\nmode and, for each command line, checks if any attribute with which a\ncommand is tagged exists in grp[]. If so, it emits the appropriate\ncommon_cmds[] \"C\" initializer. Comment and blank lines are skipped.\n\nBy the way, Junio observed[5] that you will need to adjust a couple\nMakefiles (and such) to account for the new [common] section and\n[commands] header. A good start would be to filter command-list.txt\nvia this command:\n\n sed '1,/\\[commands\\]/d' 8 ---\nFrom: Eric Sunshine \nSubject: [PATCH] generate-cmdlist: parse common group commands\n\nParse the [common] block to create the array of group descriptions:\n\nstatic char *common_cmd_groups[] = {\n N_(\"starting a working area\"),\n N_(\"working on the current change\"),\n N_(\"working with others\"),\n N_(\"examining the history and state\"),\n N_(\"growing, marking and tweaking your history\"),\n};\n\nthen map each element of common_cmds[] to a group via its index:\n\nstatic struct cmdname_help common_cmds[] = {\n {\"add\", N_(\"Add file contents to the index\"), 1},\n {\"branch\", N_(\"List, create, or delete branches\"), 4},\n {\"checkout\", N_(\"Checkout a branch or paths to the ...\"), 4},\n {\"clone\", N_(\"Clone a repository into a new directory\"), 0},\n {\"commit\", N_(\"Record changes to the repository\"), 4},\n ...\n};\n\nso that 'git help' can print those commands grouped by theme.\n\nOnly commands tagged with an attribute from [common] are emitted to\ncommon_cmds[].\n\n[commit message by Sébastien Guimmara ]\n\nSigned-off-by: Eric Sunshine \n---\n Makefile | 4 ++--\n generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++\n generate-cmdlist.sh | 23 -----------------------\n 3 files changed, 41 insertions(+), 25 deletions(-)\n create mode 100644 generate-cmdlist.awk\n delete mode 100755 generate-cmdlist.sh\n\ndiff --git a/Makefile b/Makefile\nindex 5f3987f..de28ae1 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X\n \tln -s $< $@ 2>/dev/null || \\\n \tcp $< $@\n \n-common-cmds.h: ./generate-cmdlist.sh command-list.txt\n+common-cmds.h: generate-cmdlist.awk command-list.txt\n \n common-cmds.h: $(wildcard Documentation/git-*.txt)\n-\t$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n+\t$(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@\n \n SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\\\n \t$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\\\ndiff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\nnew file mode 100644\nindex 0000000..19b36e5\n--- /dev/null\n+++ b/generate-cmdlist.awk\n@@ -0,0 +1,39 @@\n+BEGIN {\n+\tprint \"/* Automatically generated */\\n\"\n+\tprint \"struct cmdname_help {\"\n+\tprint \"\\tchar name[16];\"\n+\tprint \"\\tchar help[80];\"\n+\tprint \"\\tunsigned char group;\"\n+\tprint \"};\\n\"\n+\tprint \"static char *common_cmd_groups[] = {\"\n+}\n+/^#/ || /^[ \t]*$/ { next }\n+state == 2 {\n+\tfor (i = 2; i <= NF; i++)\n+\t\tif (grp[$i]) {\n+\t\t\tf = \"Documentation/\"$1\".txt\"\n+\t\t\twhile (getline s 0)\n+\t\t\t\tif (match(s, $1\" - \")) {\n+\t\t\t\t\tt = substr(s, length($1\" - \") + 1)\n+\t\t\t\t\tbreak\n+\t\t\t\t}\n+\t\t\tclose(f)\n+\t\t\tprintf \"\\t{\\\"%s\\\", N_(\\\"%s\\\"), %s},\\n\",\n+\t\t\t\tsubstr($1, length(\"git-\") + 1), t, grp[$i] - 1\n+\t\t\tbreak\n+\t\t}\n+}\n+/\\[commands\\]/ {\n+\tprint \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\"\n+\tstate = 2\n+}\n+state == 1 {\n+\tgrp[$1] = ++n\n+\tsub($1\"[ \t][ \t]*\", \"\")\n+\tprintf \"\\tN_(\\\"%s\\\"),\\n\", $0\n+\tnext\n+}\n+/\\[common\\]/ {\n+\tstate = 1\n+}\n+END { print \"};\" }\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\ndeleted file mode 100755\nindex 9a4c9b9..0000000\n--- a/generate-cmdlist.sh\n+++ /dev/null\n@@ -1,23 +0,0 @@\n-#!/bin/sh\n-\n-echo \"/* Automatically generated by $0 */\n-struct cmdname_help {\n- char name[16];\n- char help[80];\n-};\n-\n-static struct cmdname_help common_cmds[] = {\"\n-\n-sed -n -e 's/^git-\\([^ \t]*\\)[ \t].* common.*/\\1/p' command-list.txt |\n-sort |\n-while read cmd\n-do\n- sed -n '\n- /^NAME/,/git-'\"$cmd\"'/H\n- ${\n-\t x\n-\t s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n-\t p\n- }' \"Documentation/git-$cmd.txt\"\n-done\n-echo \"};\"\n-- \n2.4.0.319.g7a04823\n--- >8 ---\n"},{"id":"260794","messageId":"CAPig+cR67f02F0q7ZjPFG4V-EdtSgmnxs2BLqzH1TwfhcObR1A@mail.gmail.com","threadId":"39246","inReplyTo":"20150508032011.GA10209@flurp.local","subject":"Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-08T03:39:56Z","receivedAt":"2015-05-08T03:39:56Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 7, 2015 at 11:20 PM, Eric Sunshine wrote:\n> From: Eric Sunshine \n> Subject: [PATCH] generate-cmdlist: parse common group commands\n>\n> Signed-off-by: Eric Sunshine \n> ---\n> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\n> new file mode 100644\n> index 0000000..19b36e5\n> --- /dev/null\n> +++ b/generate-cmdlist.awk\n> @@ -0,0 +1,39 @@\n> [...]\n> +state == 1 {\n> + grp[$1] = ++n\n> + sub($1\"[ ][ ]*\", \"\")\n> + printf \"\\tN_(\\\"%s\\\"),\\n\", $0\n> + next\n\nBy the way, this 'next' line can be deleted. It was leftover gunk from\nan earlier iteration. It doesn't harm, but doesn't help either, and is\nthus potentially confusing.\n\n> +}\n> +/\\[common\\]/ {\n> + state = 1\n> +}\n> +END { print \"};\" }\n"},{"id":"260804","messageId":"vpqioc38ot3.fsf@anie.imag.fr","threadId":"39246","inReplyTo":"xmqq7fskp6qf.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-05-08T08:18:48Z","receivedAt":"2015-05-08T08:18:48Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> Matthieu Moy writes:\n>\n>> Junio C Hamano writes:\n>>\n>>> And the answer may confuse that someone even further (it is not\n>>> necessarily \"rm\", but is often \"reset\"). As a list of simple\n>>> command set to help the dip-your-toes-in-water process, a new user\n>>> may be better off starting with \"add\", \"add .\" and \"commit -a\", and\n>>> learn from the last part of \"git add --help\" that there are \"rm\" and\n>>> \"mv\" (both of which happen a lot less often than \"add\").\n>>\n>> If one wonders how to remove a file from Git, expecting that user to\n>> look at the doc for \"git add\" to find out seems really backwards to me.\n>\n> Yeah, but you are moving the goalpost.\n\nYes, because Git has more than one user and each user may have different\nways of thinking. I both find it weird to present \"add\" without \"rm\" and\nto expect users to look at the doc for \"add\" to find \"rm\".\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"260806","messageId":"0eb58475c6238be314eb4f0be08f8ae6@www.dscho.org","threadId":"39246","inReplyTo":"554BBBAF.30705@kdbg.org","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2015-05-08T10:11:33Z","receivedAt":"2015-05-08T10:11:33Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Hannes,\n\nOn 2015-05-07 21:23, Johannes Sixt wrote:\n\n> Files lacking the trailing new-line are not \"text files\" according to\n> the POSIX definition, BTW.\n\nIt's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?\n\nThank you,\nJohannes\n\nP.S.: Somehow when I ask GMX to send mail to Eric Sunshine today, it refuses (\"mailbox not available\"?), so I removed the address from the Cc: list. Will investigate what is wrong if that happens again. Sorry!\n"},{"id":"260808","messageId":"87egmrth00.fsf@igel.home","threadId":"39246","inReplyTo":"0eb58475c6238be314eb4f0be08f8ae6@www.dscho.org","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2015-05-08T12:01:51Z","receivedAt":"2015-05-08T12:01:51Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Johannes Schindelin writes:\n\n> It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?\n\nhttp://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html\n\n3.206 Line\nA sequence of zero or more non- characters plus a terminating\n character.\n\n3.397 Text File\nA file that contains characters organized into zero or more lines. The\nlines do not contain NUL characters and none can exceed {LINE_MAX} bytes\nin length, including the character. Although POSIX.1-2008 does\nnot distinguish between text files and binary files (see the ISO C\nstandard), many utilities only produce predictable or meaningful output\nwhen operating on text files. The standard utilities that have such\nrestrictions always specify \"text files\" in their STDIN or INPUT FILES\nsections.\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":"260810","messageId":"14b541cabe4f1051859364eada40d153@www.dscho.org","threadId":"39246","inReplyTo":"87egmrth00.fsf@igel.home","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2015-05-08T13:02:09Z","receivedAt":"2015-05-08T13:02:09Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Andreas,\n\nOn 2015-05-08 14:01, Andreas Schwab wrote:\n> Johannes Schindelin writes:\n> \n>> It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement?\n> \n> http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html\n> \n> 3.206 Line\n> A sequence of zero or more non- characters plus a terminating\n> character.\n> \n> 3.397 Text File\n> A file that contains characters organized into zero or more lines. The\n> lines do not contain NUL characters and none can exceed {LINE_MAX} bytes\n> in length, including the character. Although POSIX.1-2008 does\n> not distinguish between text files and binary files (see the ISO C\n> standard), many utilities only produce predictable or meaningful output\n> when operating on text files. The standard utilities that have such\n> restrictions always specify \"text files\" in their STDIN or INPUT FILES\n> sections.\n\nThanks!\nDscho\n"},{"id":"260817","messageId":"xmqqk2wjm47w.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"vpqioc38ot3.fsf@anie.imag.fr","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-08T16:19:47Z","receivedAt":"2015-05-08T16:19:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Junio C Hamano writes:\n> \n>> Yeah, but you are moving the goalpost.\n>\n> Yes, because Git has more than one user and each user may have different\n> ways of thinking. I both find it weird to present \"add\" without \"rm\" and\n> to expect users to look at the doc for \"add\" to find \"rm\".\n\nI would not expect somebody who wants to find 'rm' to look in 'add',\nbut you were talking about 'I just learnt add. What is the opposite\nof add?' people. 'remove', 'revert', 'reset', 'unadd'...?\n\nYes, you can try \"git help revert\", \"git help remove\", ..., giving\nall random words you think of in turn, but that is crazy. That is\nwhy 'git add' lists related subcommands in SEE ALSO.\n\nI do not mind keeping 'rm' with the description of what it does in\nthe list if we had enough vertical space. I think it would hurt to\nhave it in the list without the description of what it does, though,\nbecause 'rm' is not opposite of 'add'.\n"},{"id":"260831","messageId":"554CF9A4.4050103@gmail.com","threadId":"39246","inReplyTo":"xmqqegmucqyh.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T18:00:04Z","receivedAt":"2015-05-08T18:00:04Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Hi Junio,\n\nA preliminary question to prepare the next round (v5) of this patch:\n\nAll versions of these patches were based upon the tip of 'master' 2.4.0\n(3d4a3ff).\n\nShould I rebase subsequent patches on top of 'next' ?\n\nSébastien\n"},{"id":"260835","messageId":"554CFEC3.5030105@gmail.com","threadId":"39246","inReplyTo":"554B30D5.3050909@emmajane.net","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T18:21:55Z","receivedAt":"2015-05-08T18:21:55Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:\n> Sébastien !\n>\n> This is fantastic! My apologies for jumping in late. Hopefully\n> I'm not too late.\n>\n\nThank you :) It's just a very modest contribution though.\n\n>\n> Sébastien Guimmara wrote:\n>> This v4 includes the following suggestions:\n>>\n>> In command-list.txt:\n>> - Add a [groups] block containing names and description for groups:\n>>\n>> [groups]\n>> init starting a working area\n>> worktree working on the current change\n>> remote working with others\n>> info examining the history and state\n>> history growing, marking and tweaking your history\n> I like these headings / separation.\n>\n> As you've already \"lost\" a line to the header, would it make sense to\n> add a \"see also\" into the Guides from here? For example:\n>\n> starting a working area (see also: git help tutorial)\n> working on the current change (see also: git help everyday)\n> working with others (see also: git help workflows)\n> examining the history and state (see also: git help revisions)\n>\n\nI think it's a good idea.\n\n> [...]\n>> This produces the following output of $ git help:\n>>\n>> [...]\n>> The most commonly used git commands are:\n>>\n>> * starting a working area:\n>> clone Clone a repository into a new directory\n>> init Create an empty Git repository or reinitialize [...]\n>>\n>> * working on the current change:\n>> add Add file contents to the index\n>> reset Reset current HEAD to the specified state\n> I could not live without status at this stage, and status always tells\n> me what I should do next. I'm tempted to see it up here instead...\n\nThe layout was not designed to be workflow oriented (even if it appears\nso), but rather theme oriented. But I think that a redesign that\nintroduces the typical Git workflow in a gentle, not intimidating manner\ncould help beginners realize that Git is extremely simple in its core\nprinciples.\n\n>\n>> * working with others:\n>> fetch Download objects and refs from another repository\n>> pull Fetch from and integrate with another repository [...]\n>> push Update remote refs along with associated objects\n>>\n>> * examining the history and state:\n>> log Show commit logs\n>> status Show the working tree status\n> For this grouping, instead of also having \"state\", I'd like to see log\n> and diff. Perhaps the header is simply \"examining the history\". This\n> narrowing would make more sense to then move status up to \"working on\n> the current change\".\n>\n>> * growing, marking and tweaking your history:\n>> branch List, create, or delete branches\n>> checkout Checkout a branch or paths to the working tree\n>> commit Record changes to the repository\n>> diff Show changes between commits, commit and working [...]\n>> merge Join two or more development histories together\n> By the definition of \"tweaking\" I would include rebase. Hiding rebase\n> from the \"common\" list will increase its mystique and make people\n> even more hesitant to use it. Best to shine some light on it and help\n> to make it less scary. I would remove diff from this group as it is\n> a non-destructive command.\n\nIn a workflow-oriented 'git help', I believe this would make sense.\nThe patch originally started by examining what is really a 'common'\ncommand, and I estimated that 'rebase' was not that common. However,\nsince 'rebase' is such a powerful tool and a killer feature of git\n(among others), we could mention it in a way that is less intimidating\n(see above)\n\n>\n> What a wonderful thing to have started, Sébastien ! Thank you. :)\n>\nThank you again :)\n"},{"id":"260837","messageId":"554D03C9.9030406@gmail.com","threadId":"39246","inReplyTo":"CAPig+cQ2e4c5hYsRbZhgyvLcMPsqshqRUZGNLwhJd57YP9JEFA@mail.gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T18:43:21Z","receivedAt":"2015-05-08T18:43:21Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/07/2015 06:50 PM, Eric Sunshine wrote:\n> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara\n> wrote:\n>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:\n>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>>> wrote:\n>>>> Signed-off-by: Sébastien Guimmara \n>>>> ---\n>>>> diff --git a/command-list.txt b/command-list.txt\n>>>> index f1eae08..64394ca 100644\n>>>> --- a/command-list.txt\n>>>> +++ b/command-list.txt\n>>>> @@ -1,29 +1,39 @@\n>>>> # List of known git commands.\n>>>> -# command name category [deprecated] [common]\n>>>> -git-add mainporcelain common\n>>>> +# only add group information for common commands\n>>>\n>>> Perhaps mention also that the order of groups here is the order in\n>>> which they are output by 'git help'?\n>>\n>> It wouldn't be necessary if we reorder alphabetically the content of\n>> each group, no ?\n>\n> I'm not sure to what you are referring here? (Perhaps my comment was\n> unclear, or perhaps I'm misreading your response.)\n>\n\nI was mistaken, I thought you wanted to reorder the commands\nalphabetically, which was unnecessary since they were sorted in\nhelp.c anyway. But yes, I shall add a comment in command-list.txt\n\n> I meant only that the comment above [groups] should say that the order\n> of the items in [groups] is the order in which the groups themselves\n> are output by \"git help\".\n>\n>>>> +[groups]\n>>>\n>>> Thinking on this a bit more, perhaps [groups] is too generic. Maybe\n>>> [common] or [commongroups] would be more descriptive?\n>>>\n>>>> +init starting a working area\n>>>> +worktree working on the current change\n>>>> +remote working with others\n>>>\n>>> \"collaborating with others\" perhaps?\n>>\n>> Yes, \"groups\" has been itching a bit. I thought about \"theme\", but\n>> common just does the job too. \"collaborating with others\" sounds\n>> redundant to me (but I'm being a grammar nazi here).\n>\n> I also think \"collaborating\" itself is best, but changed it at the\n> last second before sending the email.\n>\n>>>> -git-fast-export ancillarymanipulators\n>>>> -git-fast-import ancillarymanipulators\n>>>> -git-fetch mainporcelain common\n>>>> +git-fast-export ancillarymanipulators\n>>>> +git-fast-import ancillarymanipulators\n>>>\n>>> Unintended whitespace changes for fast-export and fast-import lines? I\n>>> wouldn't have expected to see these lines change in this patch.\n>>\n>> All whitespace changes were intended to align the commands on the same\n>> column. I realize this should be the object of a separate patch.\n>\n> Strange. In my editor, all columns are already aligned. Perhaps your\n> tab with setting is incorrect? (It should be set to 8.)\n>\n\nActually I only removed the few tabs that were wandering in some lines\nto replace them by spaces (almost all lines were space aligned, only a few\nwere tab aligned).\n\n>>>> -git-grep mainporcelain common\n>>>> +git-grep mainporcelain\n>>>\n>>> This change isn't mentioned anywhere, not even in the cover letter.\n>>> Did you intend to drop 'grep' from the common command list?\n>>\n>> It's a mistake in the cover letter. I indeed intended to propose to\n>> remove grep and tag from the common commands.\n>\n> I personally consider \"grep\" an important beginner command, but that's\n> an issue to be argued separately; and it's also why it's a good idea\n> to put the removals in their own patch, so people can argue about it\n> without holding up the rest of the patches.\n>\n>>>> [...]\n>>>> -git-write-tree plumbingmanipulators\n>>>> +git-write-tree plumbingmanipulators\n>>>> \\ No newline at end of file\n>>>\n>>> Your editor is perhaps dropping the final newline in the file? This is\n>>> an undesirable change. Patch 2/3 exhibits the same problem.\n>>\n>> As for the final newline, it was deliberately removed. I was not aware it\n>> was necessary in text files. I'll correct this.\n>\n> Historically, many Unix tools incorrectly handled files lacking that\n> final newline; sometimes by dropping the line altogether, sometimes\n> mis-processing it in some way or another. Misbehaviors still exist\n> today, often in BSD tools. In fact, just a few days ago, such a\n> problem was reported for git-filter-branch[1]. Consequently, retaining\n> newline is good insurance against misbehaving tools.\n>\n> [1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957\n>\n"},{"id":"260839","messageId":"xmqqlhgylx3l.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"554CF9A4.4050103@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-08T18:53:34Z","receivedAt":"2015-05-08T18:53:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> A preliminary question to prepare the next round (v5) of this patch:\n>\n> All versions of these patches were based upon the tip of 'master' 2.4.0\n> (3d4a3ff).\n>\n> Should I rebase subsequent patches on top of 'next' ?\n\nI think doing it on 2.4.0 is fine.\n\nIn general, you shouldn't base anything on 'next', unless you are\nusing some new features that are still cooking in 'next' on their\nown topic branches. And even if that were the case, I would prefer\na series that introduces a new feature to wait for those other topic\nbranches it wants to use to graduate to 'master'. Alternatively,\nyou can identify these still-in-flight topics that you absolutely\nneed to depend on, merge them to 'master' yourself, _and_ build your\npatches on top, but please make it clear that you did that when\nsending the patches in if you take this route. Your patches would\nbecome hostage of these other topics and cannot graduate to 'master'\nbefore they do, so keep that in mind if you do so.\n\nWhatever you do, you would still need to make sure that the result\nof applying your patches merges cleanly to 'next' and works well.\n\nNeedless to say, a fix is preferrable to be based on 'maint' (or\neven older maintenance tracks when it is feasible), but that does\nnot concern this \"update help output\" topic.\n\nThanks.\n"},{"id":"260841","messageId":"xmqqh9rmlwut.fsf@gitster.dls.corp.google.com","threadId":"39246","inReplyTo":"554CFEC3.5030105@gmail.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-08T18:58:50Z","receivedAt":"2015-05-08T18:58:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:\n>\n>>> The most commonly used git commands are:\n>>>\n>>> * starting a working area:\n>>> clone Clone a repository into a new directory\n>>> init Create an empty Git repository or reinitialize [...]\n>>>\n>>> * working on the current change:\n>>> add Add file contents to the index\n>>> reset Reset current HEAD to the specified state\n>> I could not live without status at this stage, and status always tells\n>> me what I should do next. I'm tempted to see it up here instead...\n>\n> The layout was not designed to be workflow oriented (even if it appears\n> so), but rather theme oriented.\n\nI tend to agree with Emma here; even if your original ordering was\nnot using the workflow as the grouping criterion, that is something\nthat can easily be fixed, I would think.\n\nAfter all, the very original did not categorize and sorted\nalphabetically, so there is no room for the \"we chose to be\ntheme-oriented (I am not sure what it means, though) and a major\nredesign at this point will confuse users\" kind of resistance to\ncome into the picture. At least not yet.\n\nThanks.\n"},{"id":"260842","messageId":"CAPig+cS=3KMxBGnQF7v8mkcDbpw4_2LyB4coOtbJEYq-2pymAg@mail.gmail.com","threadId":"39246","inReplyTo":"554D03C9.9030406@gmail.com","subject":"Re: [PATCH 1/3] command-list.txt: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-08T19:00:04Z","receivedAt":"2015-05-08T19:00:04Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 8, 2015 at 2:43 PM, Sébastien Guimmara\n wrote:\n> On 05/07/2015 06:50 PM, Eric Sunshine wrote:\n>> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara\n>> wrote:\n>>> On 05/06/2015 08:57 AM, Eric Sunshine wrote:\n>>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>>>> wrote:\n>>>>> -git-fast-export ancillarymanipulators\n>>>>> -git-fast-import ancillarymanipulators\n>>>>> -git-fetch mainporcelain common\n>>>>> +git-fast-export ancillarymanipulators\n>>>>> +git-fast-import ancillarymanipulators\n>>>>\n>>>> Unintended whitespace changes for fast-export and fast-import lines? I\n>>>> wouldn't have expected to see these lines change in this patch.\n>>>\n>>> All whitespace changes were intended to align the commands on the same\n>>> column. I realize this should be the object of a separate patch.\n>>\n>> Strange. In my editor, all columns are already aligned. Perhaps your\n>> tab with setting is incorrect? (It should be set to 8.)\n>\n> Actually I only removed the few tabs that were wandering in some lines\n> to replace them by spaces (almost all lines were space aligned, only a few\n> were tab aligned).\n\nAh, I see. Thanks for the explanation.\n"},{"id":"260851","messageId":"554D17AD.9070306@gmail.com","threadId":"39246","inReplyTo":"xmqqh9rmlwut.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T20:08:13Z","receivedAt":"2015-05-08T20:08:13Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/08/2015 08:58 PM, Junio C Hamano wrote:\n> Sébastien Guimmara writes:\n>\n>> On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:\n>>\n>>>> The most commonly used git commands are:\n>>>>\n>>>> * starting a working area:\n>>>> clone Clone a repository into a new directory\n>>>> init Create an empty Git repository or reinitialize [...]\n>>>>\n>>>> * working on the current change:\n>>>> add Add file contents to the index\n>>>> reset Reset current HEAD to the specified state\n>>> I could not live without status at this stage, and status always tells\n>>> me what I should do next. I'm tempted to see it up here instead...\n>>\n>> The layout was not designed to be workflow oriented (even if it appears\n>> so), but rather theme oriented.\n>\n> I tend to agree with Emma here; even if your original ordering was\n> not using the workflow as the grouping criterion, that is something\n> that can easily be fixed, I would think.\n>\n> After all, the very original did not categorize and sorted\n> alphabetically, so there is no room for the \"we chose to be\n> theme-oriented (I am not sure what it means, though) and a major\n> redesign at this point will confuse users\" kind of resistance to\n> come into the picture. At least not yet.\n>\n> Thanks.\n>\n\nExactly. The new version will be workflow-oriented.\n\nBy \"theme-oriented\", I mean that the group order does not necessarily\nfollow a \"typical workflow\" chronological order, even though it was\nheavily implied. I should emphasize this \"workflow\" thing in the next\npatch.\n"},{"id":"260860","messageId":"554D22BE.10703@gmail.com","threadId":"39246","inReplyTo":"20150508032011.GA10209@flurp.local","subject":"Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T20:55:26Z","receivedAt":"2015-05-08T20:55:26Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/08/2015 05:20 AM, Eric Sunshine wrote:\n> On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote:\n>> parse the [groups] block to create the array of group descriptions\n>>\n>> static char *common_cmd_groups[] = {\n>> N_(\"starting a working area\"),\n>> ...\n>> };\n>>\n>> then map each element of common_cmds[] to a group via its index:\n>>\n>> static struct cmdname_help common_cmds[] = {\n>> {\"add\", N_(\"Add file contents to the index\"), 1},\n>> ...\n>>\n>> So that 'git help' can print those command grouped by theme.\n>> ---\n>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n>> @@ -1,23 +1,42 @@\n>> +content=$(cat command-list.txt)\n>> +\n>> +group_line_no=$(expr $(echo \"$content\" | grep -n '^\\[groups\\]' | cut -f1 -d:) + 1)\n>> +command_line_no=$(expr $(echo \"$content\" | grep -n '^\\[commands\\]' | cut -f1 -d:) + 1)\n>> +groups=$(echo \"$content\" | sed -n ''$group_line_no', '$(expr $command_line_no)'p')\n>> [...]\n>> +static char *common_cmd_groups[] = {\"\n>> +echo \"$groups\" |\n>> +while read group description; do\n>> + if [ -z $group ]; then\n>> + break\n>> + fi\n>> + echo ' N_(\"'$description'\"),'\n>> +done\n>> +echo \"};\n>> [...]\n>> +echo \"$content\" | grep 'common-' |\n>> +awk '{ print $1, \"\\t\", $3 }' |\n>> +while read cmd grp; do\n>> + cmd_name=$(echo $cmd | cut -d - -f 2)\n>> + group_name=$(echo $grp | cut -d - -f 2)\n>> + group_idx=$(expr $(echo \"$groups\" | grep -n \"^$group_name\" | cut -c 1) - 1)\n>> + sed -n '\n>> + /^NAME/,/git-'\"$cmd_name\"'/H\n>> + ${\n>> + x\n>> + s/.*git-'\"$cmd_name\"' - \\(.*\\)/ {\"'\"$cmd_name\"'\", N_(\"\\1\"), '\"$group_idx\"'},/\n>> + p\n>> + }' \"Documentation/$cmd.txt\"\n>\n> Background: In an earlier review, I observed[1] that the \"common-\" in\n> the \"common-N_group\" form was redundant, and I suggested that you\n> could add a [groups] section listing the groups, and that the order\n> of items in [groups] would imply the \"git help\" display order of the\n> groups, thus allowing you to do away with the \"N_\" qualifier, as\n> well. I also observed that you could determine if a command in\n> [commands] was common by checking if it was tagged with an attribute\n> from [groups], thus alleviating the need for the \"common-\" prefix.\n>\n> This round makes nice headway toward the proposed scheme, although it\n> still depends upon the redundant \"common-\" prefix. When I earlier\n> suggested that awk could be helpful[2], I was thinking of its\n> associative arrays which could be used to determine if a command in\n> [commands] was tagged with an attribute from [groups].\n>\n> I had intended to reply to the current patch with a short \"here's\n> what I had in mind\" example of using awk to achieve this goal,\n> however, the short example ended up implementing the full\n> functionality, so I went ahead and turned it into a proper patch[6]\n> (below), and shamelessly re-used your commit message (with minor\n> changes). You're welcome to include this patch in your re-roll, or\n> use it as inspiration if you want to write the functionality\n> yourself.\n>\n> Some notes about the re-implementation in awk: It assumes that\n> [groups] has been renamed to [common] as suggested[3], and assumes\n> that the \"common-\" prefix has been dropped from the [commands]\n> attribute entries. The awk script replaces the current shell script\n> entirely, and all common-cmds.h generation functionality is now\n> handled by the one awk invocation rather than by a series of commands\n> invoked by the shell script, which should make it faster (especially\n> on Windows). Finally, unlike the shell script, the awk script does\n> not bother sorting commands from command-list.txt since it assumes\n> that command sorting will happen in parallel with grouping[4].\n>\n> When the awk script encounters [common], it begins collecting group\n> names in a grp[] array and emits the appropriate common_cmd_groups[]\n> \"C\" initializer for each. Upon encountering [commands], it switches\n> mode and, for each command line, checks if any attribute with which a\n> command is tagged exists in grp[]. If so, it emits the appropriate\n> common_cmds[] \"C\" initializer. Comment and blank lines are skipped.\n>\n> By the way, Junio observed[5] that you will need to adjust a couple\n> Makefiles (and such) to account for the new [common] section and\n> [commands] header. A good start would be to filter command-list.txt\n> via this command:\n>\n> sed '1,/\\[commands\\]/d' \n> which will strip out everything up to and including the [commands]\n> header.\n>\n> [1]: http://article.gmane.org/gmane.comp.version-control.git/268291\n> [2]: http://article.gmane.org/gmane.comp.version-control.git/268294\n> [3]: http://article.gmane.org/gmane.comp.version-control.git/268453\n> [4]: http://article.gmane.org/gmane.comp.version-control.git/268442\n> [5]: http://article.gmane.org/gmane.comp.version-control.git/268443\n> [6]: Below is full patch which replaces 2/3 from this round:\n>\n> --- >8 ---\n> From: Eric Sunshine \n> Subject: [PATCH] generate-cmdlist: parse common group commands\n>\n> Parse the [common] block to create the array of group descriptions:\n>\n> static 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>\n> then map each element of common_cmds[] to a group via its index:\n>\n> static 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>\n> so that 'git help' can print those commands grouped by theme.\n>\n> Only commands tagged with an attribute from [common] are emitted to\n> common_cmds[].\n>\n> [commit message by Sébastien Guimmara ]\n>\n> Signed-off-by: Eric Sunshine \n> ---\n> Makefile | 4 ++--\n> generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++\n> generate-cmdlist.sh | 23 -----------------------\n> 3 files changed, 41 insertions(+), 25 deletions(-)\n> create mode 100644 generate-cmdlist.awk\n> delete mode 100755 generate-cmdlist.sh\n>\n> diff --git a/Makefile b/Makefile\n> index 5f3987f..de28ae1 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X\n> \tln -s $< $@ 2>/dev/null || \\\n> \tcp $< $@\n>\n> -common-cmds.h: ./generate-cmdlist.sh command-list.txt\n> +common-cmds.h: generate-cmdlist.awk command-list.txt\n>\n> common-cmds.h: $(wildcard Documentation/git-*.txt)\n> -\t$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@\n> +\t$(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@\n>\n> SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\\\n> \t$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\\\n> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk\n> new file mode 100644\n> index 0000000..19b36e5\n> --- /dev/null\n> +++ b/generate-cmdlist.awk\n> @@ -0,0 +1,39 @@\n> +BEGIN {\n> +\tprint \"/* Automatically generated */\\n\"\n> +\tprint \"struct cmdname_help {\"\n> +\tprint \"\\tchar name[16];\"\n> +\tprint \"\\tchar help[80];\"\n> +\tprint \"\\tunsigned char group;\"\n> +\tprint \"};\\n\"\n> +\tprint \"static char *common_cmd_groups[] = {\"\n> +}\n> +/^#/ || /^[ \t]*$/ { next }\n> +state == 2 {\n> +\tfor (i = 2; i <= NF; i++)\n> +\t\tif (grp[$i]) {\n> +\t\t\tf = \"Documentation/\"$1\".txt\"\n> +\t\t\twhile (getline s 0)\n> +\t\t\t\tif (match(s, $1\" - \")) {\n> +\t\t\t\t\tt = substr(s, length($1\" - \") + 1)\n> +\t\t\t\t\tbreak\n> +\t\t\t\t}\n> +\t\t\tclose(f)\n> +\t\t\tprintf \"\\t{\\\"%s\\\", N_(\\\"%s\\\"), %s},\\n\",\n> +\t\t\t\tsubstr($1, length(\"git-\") + 1), t, grp[$i] - 1\n> +\t\t\tbreak\n> +\t\t}\n> +}\n> +/\\[commands\\]/ {\n> +\tprint \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\"\n> +\tstate = 2\n> +}\n> +state == 1 {\n> +\tgrp[$1] = ++n\n> +\tsub($1\"[ \t][ \t]*\", \"\")\n> +\tprintf \"\\tN_(\\\"%s\\\"),\\n\", $0\n> +\tnext\n> +}\n> +/\\[common\\]/ {\n> +\tstate = 1\n> +}\n> +END { print \"};\" }\n> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\n> deleted file mode 100755\n> index 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>\n\nWow. Thanks very much. It has been added in the new version of the patch,\nincluding the removal of the 'next' line.\n"},{"id":"260863","messageId":"554D25B1.8050605@gmail.com","threadId":"39246","inReplyTo":"CAPig+cS=u-HK1qNicWiLOQC6RPkR7QueX+kOu8fQwpHekgs1yg@mail.gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T21:08:01Z","receivedAt":"2015-05-08T21:08:01Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/06/2015 05:16 AM, Eric Sunshine wrote:\n> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>> +\n>> + if (group1 == group2)\n>> + return 0;\n>> + if (group1 > group2)\n>> + return 1;\n>> + else\n>> + return -1;\n>\n> Do you also want to sort the commands alphabetically within group?\n> That is, something like this?\n>\n> struct cmdname_help *e1 = elem1;\n> struct cmdname_help *e2 = elem2;\n>\n> if (e1->group < e2->group)\n> return -1;\n> if (e1->group > e2->group)\n> return 1;\n> return strcmp(e1->name, e2->name);\n>\n>> +}\n\nYour version raises:\n\nhelp.c: In function ‘cmd_group_cmp’:\nhelp.c:223:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default]\n struct cmdname_help *e1 = elem1;\n ^\nhelp.c:224:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default]\n struct cmdname_help *e2 = elem2;\n ^\n\nWith the cast:\n\nstruct cmdname_help *e1 = (struct cmdname_help*)elem1;\n\nIt compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)\n\n>> +\n>> void list_common_cmds_help(void)\n>> {\n>> int i, longest = 0;\n>> + unsigned char 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>> + qsort(common_cmds, ARRAY_SIZE(common_cmds),\n>> + sizeof(common_cmds[0]), cmd_group_cmp);\n>> +\n>> puts(_(\"The most commonly used git commands are:\"));\n>> +\n>> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n>> - printf(\" %s \", common_cmds[i].name);\n>> + if (common_cmds[i].group != current_grp) {\n>> + printf(\"\\n * %s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n>> + }\n>\n> Style: Drop unnecessary braces.\n>\n>> + current_grp = common_cmds[i].group;\n>\n> Alternately, move this assignment inside the braces.\n>\n>> + printf(\" %s \", common_cmds[i].name);\n>> mput_char(' ', longest - strlen(common_cmds[i].name));\n>> puts(_(common_cmds[i].help));\n>> }\n>> --\n>> 2.4.0\n>\n"},{"id":"260866","messageId":"CAGZ79kaL219wN4=c9_SQGDk+Mtie0Xm5PDc0Jy6mTQiQ37wj4A@mail.gmail.com","threadId":"39246","inReplyTo":"554D25B1.8050605@gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-08T21:17:00Z","receivedAt":"2015-05-08T21:17:00Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara\n wrote:\n> On 05/06/2015 05:16 AM, Eric Sunshine wrote:\n>>\n>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>>>\n>>> +\n>>> + if (group1 == group2)\n>>> + return 0;\n>>> + if (group1 > group2)\n>>> + return 1;\n>>> + else\n>>> + return -1;\n>>\n>>\n>> Do you also want to sort the commands alphabetically within group?\n>> That is, something like this?\n>>\n>> struct cmdname_help *e1 = elem1;\n>> struct cmdname_help *e2 = elem2;\n>>\n>> if (e1->group < e2->group)\n>> return -1;\n>> if (e1->group > e2->group)\n>> return 1;\n>> return strcmp(e1->name, e2->name);\n>>\n>>> +}\n>\n>\n> Your version raises:\n>\n> help.c: In function ‘cmd_group_cmp’:\n> help.c:223:28: warning: initialization discards ‘const’ qualifier from\n> pointer target type [enabled by default]\n> struct cmdname_help *e1 = elem1;\n> ^\n> help.c:224:28: warning: initialization discards ‘const’ qualifier from\n> pointer target type [enabled by default]\n> struct cmdname_help *e2 = elem2;\n> ^\n>\n> With the cast:\n>\n> struct cmdname_help *e1 = (struct cmdname_help*)elem1;\n>\n> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)\n>\n>\n\nI'd rather change the type of struct cmdname_help to be const, such\nthat it reads:\n\n const struct cmdname_help *e1 = elem1;\n const struct cmdname_help *e2 = elem2;\n\n if (e1->group < e2->group)\n return -1;\n if (e1->group > e2->group)\n return 1;\n return strcmp(e1->name, e2->name);\n\ninstead of casting if possible.\n"},{"id":"260867","messageId":"CAPig+cS5OmsEz-_DRZqA_5G9p1ODA1qV4cMhmJWBtPFAMqDbrw@mail.gmail.com","threadId":"39246","inReplyTo":"CAGZ79kaL219wN4=c9_SQGDk+Mtie0Xm5PDc0Jy6mTQiQ37wj4A@mail.gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-08T21:19:43Z","receivedAt":"2015-05-08T21:19:43Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, May 8, 2015 at 5:17 PM, Stefan Beller wrote:\n> On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara\n> wrote:\n>> On 05/06/2015 05:16 AM, Eric Sunshine wrote:\n>>> Do you also want to sort the commands alphabetically within group?\n>>> That is, something like this?\n>>>\n>>> struct cmdname_help *e1 = elem1;\n>>> struct cmdname_help *e2 = elem2;\n>>>\n>>> if (e1->group < e2->group)\n>>> return -1;\n>>> if (e1->group > e2->group)\n>>> return 1;\n>>> return strcmp(e1->name, e2->name);\n>>>\n>>>> +}\n>>\n>> Your version raises:\n>>\n>> help.c:223:28: warning: initialization discards ‘const’ qualifier from\n>> pointer target type [enabled by default]\n>> struct cmdname_help *e1 = elem1;\n>> ^\n>> With the cast:\n>> struct cmdname_help *e1 = (struct cmdname_help*)elem1;\n>> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)\n>\n> I'd rather change the type of struct cmdname_help to be const, such\n> that it reads:\n>\n> const struct cmdname_help *e1 = elem1;\n> const struct cmdname_help *e2 = elem2;\n>\n> if (e1->group < e2->group)\n> return -1;\n> if (e1->group > e2->group)\n> return 1;\n> return strcmp(e1->name, e2->name);\n>\n> instead of casting if possible.\n\nRight. That was just a quickly typed example in the email. The \"real\"\ncode should use a 'const' pointer.\n"},{"id":"260868","messageId":"554D2884.9040607@gmail.com","threadId":"39246","inReplyTo":"CAGZ79kaL219wN4=c9_SQGDk+Mtie0Xm5PDc0Jy6mTQiQ37wj4A@mail.gmail.com","subject":"Re: [PATCH 3/3] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-08T21:20:04Z","receivedAt":"2015-05-08T21:20:04Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"\n\nOn 05/08/2015 11:17 PM, Stefan Beller wrote:\n> On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara\n> wrote:\n>> On 05/06/2015 05:16 AM, Eric Sunshine wrote:\n>>>\n>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara\n>>>>\n>>>> +\n>>>> + if (group1 == group2)\n>>>> + return 0;\n>>>> + if (group1 > group2)\n>>>> + return 1;\n>>>> + else\n>>>> + return -1;\n>>>\n>>>\n>>> Do you also want to sort the commands alphabetically within group?\n>>> That is, something like this?\n>>>\n>>> struct cmdname_help *e1 = elem1;\n>>> struct cmdname_help *e2 = elem2;\n>>>\n>>> if (e1->group < e2->group)\n>>> return -1;\n>>> if (e1->group > e2->group)\n>>> return 1;\n>>> return strcmp(e1->name, e2->name);\n>>>\n>>>> +}\n>>\n>>\n>> Your version raises:\n>>\n>> help.c: In function ‘cmd_group_cmp’:\n>> help.c:223:28: warning: initialization discards ‘const’ qualifier from\n>> pointer target type [enabled by default]\n>> struct cmdname_help *e1 = elem1;\n>> ^\n>> help.c:224:28: warning: initialization discards ‘const’ qualifier from\n>> pointer target type [enabled by default]\n>> struct cmdname_help *e2 = elem2;\n>> ^\n>>\n>> With the cast:\n>>\n>> struct cmdname_help *e1 = (struct cmdname_help*)elem1;\n>>\n>> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2)\n>>\n>>\n>\n> I'd rather change the type of struct cmdname_help to be const, such\n> that it reads:\n>\n> const struct cmdname_help *e1 = elem1;\n> const struct cmdname_help *e2 = elem2;\n>\n> if (e1->group < e2->group)\n> return -1;\n> if (e1->group > e2->group)\n> return 1;\n> return strcmp(e1->name, e2->name);\n>\n> instead of casting if possible.\n>\n\nyes, much better, thanks.\n"}]}