{"thread":{"id":"39334","subject":"[PATCH 0/5] git help: group common commands by theme","startedAt":"2015-05-14T12:59:05Z","lastAt":"2015-05-15T14:40:04Z","messageCount":12,"participants":["Sébastien Guimmara","Junio C Hamano","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"261226","messageId":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":null,"subject":"[PATCH 0/5] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:05Z","receivedAt":"2015-05-14T12:59:05Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"This v6 is very similar in content to the v5 [1], except minor formatting\nadjustments in 'git help' output and recommendations from Eric.\n\nThe major change is in the patch series itself. Commits have been\nreordered and adjusted so that each 'apply' doesn't break the build, and\npreserve bisectability.\n\nSummary: make 'git help' outputs a more usable and friendlier\nlist of commands, grouped by theme according to the typical Git workflow:\n\n[...]\n\nThe typical Git workflow includes:\n\nstart a working area (see also: git help tutorial):\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize an existing one\n\nwork on the current change (see also: git help everyday):\n add Add file contents to the index\n mv Move or rename a file, a directory, or a symlink\n reset Reset current HEAD to the specified state\n rm Remove files from the working tree and from the index\n\n[...]\n\nMany thanks to Eric Sunshine for the detailed help and advice !\n\n[1]: http://thread.gmane.org/gmane.comp.version-control.git/268701\n\nEric Sunshine (1):\n generate-cmdlist: parse common group commands\n\nSébastien Guimmara (4):\n command-list.txt: prepare with [commands] header\n command-list.txt: add with [common] block\n command-list.txt: drop the common- prefix\n help.c: output the typical Git workflow\n\n Documentation/cmd-list.perl | 4 +++\n Documentation/howto/new-command.txt | 4 ++-\n Makefile | 7 ++---\n command-list.txt | 53 ++++++++++++++++++++++---------------\n generate-cmdlist.awk | 39 +++++++++++++++++++++++++++\n generate-cmdlist.sh | 23 ----------------\n help.c | 24 ++++++++++++++++-\n 7 files changed, 105 insertions(+), 49 deletions(-)\n create mode 100644 generate-cmdlist.awk\n delete mode 100755 generate-cmdlist.sh\n\n-- \n2.4.0\n"},{"id":"261227","messageId":"1431608351-9413-2-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH 1/5] command-list.txt: prepare with [commands] header","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:06Z","receivedAt":"2015-05-14T12:59:06Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"Add a [commands] header before the actual command list, then make the\nfollowing files ignore this header in their parsing:\n\n\t* cmd-list.perl\n\t* Makefile (check-docks target)\n\nHelped-by: Eric Sunshine \nSigned-off-by: Sébastien Guimmara \n---\n Documentation/cmd-list.perl | 4 ++++\n Makefile | 3 ++-\n command-list.txt | 1 +\n 3 files changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 04f9977..06a5fd6 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -38,6 +38,10 @@ sub format_one {\n \t}\n }\n \n+while (<>) {\n+\tlast if /^\\[commands\\]/;\n+}\n+\n my %cmds = ();\n for (sort <>) {\n \tnext if /^#/;\ndiff --git a/Makefile b/Makefile\nindex 5f3987f..7c57369 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2447,7 +2447,7 @@ check-docs::\n \t\tesac ; \\\n \t\ttest -f \"Documentation/$$v.txt\" || \\\n \t\techo \"no doc: $$v\"; \\\n-\t\tsed -e '/^#/d' command-list.txt | \\\n+\t\tsed -e '1,/^\\[commands\\]/d' -e '/^#/d' \nHelped-by: Junio C Hamano \nHelped-by: Emma Jane Hogbin Westby \nSigned-off-by: Sébastien Guimmara \n---\n Documentation/howto/new-command.txt | 4 ++-\n command-list.txt | 52 ++++++++++++++++++++++---------------\n 2 files changed, 34 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt\nindex d7de5a3..6d772bd 100644\n--- a/Documentation/howto/new-command.txt\n+++ b/Documentation/howto/new-command.txt\n@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.\n that categorizes commands by type, so they can be listed in appropriate\n subsections in the documentation's summary command list. Add an entry\n for yours. To understand the categories, look at git-commands.txt\n-in the main directory.\n+in the main directory. If the new command is part of the typical Git\n+workflow and you believe it common enough to be mentioned in 'git help',\n+map this command to a common group in the column [common].\n \n 7. Give the maintainer one paragraph to include in the RelNotes file\n to describe the new feature; a good place to do so is in the cover\ndiff --git a/command-list.txt b/command-list.txt\nindex 40fbe2f..7cb77f0 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -1,30 +1,40 @@\n+# common commands are grouped by themes\n+# this order is the same that output by 'git help'\n+# map each common command in the [commands] list to one of these groups.\n+[common]\n+init start a working area (see also: git help tutorial)\n+worktree work on the current change (see also: git help everyday)\n+info examine the history and state (see also: git help revisions)\n+history grow, mark and tweak your history\n+remote collaborate (see also: git help workflows)\n+\n # List of known git commands.\n # command name\t\t\t\tcategory [deprecated] [common]\n [commands]\n-git-add mainporcelain common\n+git-add mainporcelain common-worktree\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n git-apply plumbingmanipulators\n git-archimport foreignscminterface\n git-archive mainporcelain\n-git-bisect mainporcelain common\n+git-bisect mainporcelain common-info\n git-blame ancillaryinterrogators\n-git-branch mainporcelain common\n+git-branch mainporcelain common-history\n git-bundle mainporcelain\n git-cat-file plumbinginterrogators\n git-check-attr purehelpers\n git-check-ignore purehelpers\n git-check-mailmap purehelpers\n-git-checkout mainporcelain common\n+git-checkout mainporcelain common-history\n git-checkout-index plumbingmanipulators\n git-check-ref-format purehelpers\n git-cherry ancillaryinterrogators\n git-cherry-pick mainporcelain\n git-citool mainporcelain\n git-clean mainporcelain\n-git-clone mainporcelain common\n+git-clone mainporcelain common-init\n git-column purehelpers\n-git-commit mainporcelain common\n+git-commit mainporcelain common-history\n git-commit-tree plumbingmanipulators\n git-config ancillarymanipulators\n git-count-objects ancillaryinterrogators\n@@ -36,14 +46,14 @@ git-cvsimport foreignscminterface\n git-cvsserver foreignscminterface\n git-daemon synchingrepositories\n git-describe mainporcelain\n-git-diff mainporcelain common\n+git-diff mainporcelain common-history\n git-diff-files plumbinginterrogators\n git-diff-index plumbinginterrogators\n git-diff-tree plumbinginterrogators\n git-difftool ancillaryinterrogators\n git-fast-export\t\t\t\tancillarymanipulators\n git-fast-import\t\t\t\tancillarymanipulators\n-git-fetch mainporcelain common\n+git-fetch mainporcelain common-remote\n git-fetch-pack synchingrepositories\n git-filter-branch ancillarymanipulators\n git-fmt-merge-msg purehelpers\n@@ -52,7 +62,7 @@ git-format-patch mainporcelain\n git-fsck\t ancillaryinterrogators\n git-gc mainporcelain\n git-get-tar-commit-id ancillaryinterrogators\n-git-grep mainporcelain common\n+git-grep mainporcelain common-info\n git-gui mainporcelain\n git-hash-object plumbingmanipulators\n git-help\t\t\t\tancillaryinterrogators\n@@ -61,17 +71,17 @@ git-http-fetch synchelpers\n git-http-push synchelpers\n git-imap-send foreignscminterface\n git-index-pack plumbingmanipulators\n-git-init mainporcelain common\n+git-init mainporcelain common-init\n git-instaweb ancillaryinterrogators\n git-interpret-trailers purehelpers\n gitk mainporcelain\n-git-log mainporcelain common\n+git-log mainporcelain common-info\n git-ls-files plumbinginterrogators\n git-ls-remote plumbinginterrogators\n git-ls-tree plumbinginterrogators\n git-mailinfo purehelpers\n git-mailsplit purehelpers\n-git-merge mainporcelain common\n+git-merge mainporcelain common-history\n git-merge-base plumbinginterrogators\n git-merge-file plumbingmanipulators\n git-merge-index plumbingmanipulators\n@@ -80,7 +90,7 @@ git-mergetool ancillarymanipulators\n git-merge-tree ancillaryinterrogators\n git-mktag plumbingmanipulators\n git-mktree plumbingmanipulators\n-git-mv mainporcelain common\n+git-mv mainporcelain common-worktree\n git-name-rev plumbinginterrogators\n git-notes mainporcelain\n git-p4 foreignscminterface\n@@ -91,11 +101,11 @@ git-parse-remote synchelpers\n git-patch-id purehelpers\n git-prune ancillarymanipulators\n git-prune-packed plumbingmanipulators\n-git-pull mainporcelain common\n-git-push mainporcelain common\n+git-pull mainporcelain common-remote\n+git-push mainporcelain common-remote\n git-quiltimport foreignscminterface\n git-read-tree plumbingmanipulators\n-git-rebase mainporcelain common\n+git-rebase mainporcelain common-history\n git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n@@ -104,28 +114,28 @@ git-repack ancillarymanipulators\n git-replace ancillarymanipulators\n git-request-pull foreignscminterface\n git-rerere ancillaryinterrogators\n-git-reset mainporcelain common\n+git-reset mainporcelain common-worktree\n git-revert mainporcelain\n git-rev-list plumbinginterrogators\n git-rev-parse ancillaryinterrogators\n-git-rm mainporcelain common\n+git-rm mainporcelain common-worktree\n git-send-email foreignscminterface\n git-send-pack synchingrepositories\n git-shell synchelpers\n git-shortlog mainporcelain\n-git-show mainporcelain common\n+git-show mainporcelain common-info\n git-show-branch ancillaryinterrogators\n git-show-index plumbinginterrogators\n git-show-ref plumbinginterrogators\n git-sh-i18n purehelpers\n git-sh-setup purehelpers\n git-stash mainporcelain\n-git-status mainporcelain common\n+git-status mainporcelain common-info\n git-stripspace purehelpers\n git-submodule mainporcelain\n git-svn foreignscminterface\n git-symbolic-ref plumbingmanipulators\n-git-tag mainporcelain common\n+git-tag mainporcelain common-history\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n-- \n2.4.0\n"},{"id":"261228","messageId":"1431608351-9413-4-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH 3/5] generate-cmdlist: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:08Z","receivedAt":"2015-05-14T12:59:08Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"From: Eric Sunshine \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 \nSigned-off-by: Sébastien Guimmara \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 7c57369..286a68f 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..b5cc789\n--- /dev/null\n+++ b/generate-cmdlist.awk\n@@ -0,0 +1,39 @@\n+BEGIN {\n+\tprint \"/* Automatically generated by generate-cmdlist.awk */\\n\"\n+\tprint \"struct cmdname_help {\"\n+\tprint \"\\tchar name[16];\"\n+\tprint \"\\tchar help[80];\"\n+\tprint \"\\tunsigned char group;\"\n+\tprint \"};\\n\"\n+\tprint \"static char *common_cmd_groups[] = {\"\n+}\n+/^#/ || /^[ \t]*$/ { next }\n+state == 2 {\n+\tfor (i = 2; i <= NF; i++)\n+\t\tif (grp[$i]) {\n+\t\t\tf = \"Documentation/\"$1\".txt\"\n+\t\t\twhile (getline s 0)\n+\t\t\t\tif (match(s, $1\" - \")) {\n+\t\t\t\t\tt = substr(s, length($1\" - \") + 1)\n+\t\t\t\t\tbreak\n+\t\t\t\t}\n+\t\t\tclose(f)\n+\t\t\tprintf \"\\t{\\\"%s\\\", N_(\\\"%s\\\"), %s},\\n\",\n+\t\t\t\tsubstr($1, length(\"git-\") + 1), t, grp[$i] - 1\n+\t\t\tbreak\n+\t\t}\n+}\n+/\\[commands\\]/ {\n+\tprint \"};\\n\\nstatic struct cmdname_help common_cmds[] = {\"\n+\tstate = 2\n+}\n+state == 1 {\n+\tgrp[$1] = ++n\n+\tsub($1\"[ \t][ \t]*\", \"\")\n+\tprintf \"\\tN_(\\\"%s\\\"),\\n\", $0\n+\tnext\n+}\n+/\\[common\\]/ {\n+\tstate = 1\n+}\n+END { print \"};\" }\ndiff --git a/generate-cmdlist.sh b/generate-cmdlist.sh\ndeleted file mode 100755\nindex 9a4c9b9..0000000\n--- a/generate-cmdlist.sh\n+++ /dev/null\n@@ -1,23 +0,0 @@\n-#!/bin/sh\n-\n-echo \"/* Automatically generated by $0 */\n-struct cmdname_help {\n- char name[16];\n- char help[80];\n-};\n-\n-static struct cmdname_help common_cmds[] = {\"\n-\n-sed -n -e 's/^git-\\([^ \t]*\\)[ \t].* common.*/\\1/p' command-list.txt |\n-sort |\n-while read cmd\n-do\n- sed -n '\n- /^NAME/,/git-'\"$cmd\"'/H\n- ${\n-\t x\n-\t s/.*git-'\"$cmd\"' - \\(.*\\)/ {\"'\"$cmd\"'\", N_(\"\\1\")},/\n-\t p\n- }' \"Documentation/git-$cmd.txt\"\n-done\n-echo \"};\"\n-- \n2.4.0\n"},{"id":"261230","messageId":"1431608351-9413-5-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH 4/5] command-list.txt: drop the common- prefix","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:09Z","receivedAt":"2015-05-14T12:59:09Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"The parser generate-cmdlist.awk gathers all group information without\nneeding the common- prefix.\n\nbefore:\n git-add mainporcelain common-worktree\n\nafter:\n git-add mainporcelain worktree\n\nHelped-by: Eric Sunshine \nSigned-off-by: Sébastien Guimmara \n---\n command-list.txt | 42 +++++++++++++++++++++---------------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex 7cb77f0..65e40ee 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -11,30 +11,30 @@ remote collaborate (see also: git help workflows)\n # List of known git commands.\n # command name\t\t\t\tcategory [deprecated] [common]\n [commands]\n-git-add mainporcelain common-worktree\n+git-add mainporcelain worktree\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n git-apply plumbingmanipulators\n git-archimport foreignscminterface\n git-archive mainporcelain\n-git-bisect mainporcelain common-info\n+git-bisect mainporcelain info\n git-blame ancillaryinterrogators\n-git-branch mainporcelain common-history\n+git-branch mainporcelain history\n git-bundle mainporcelain\n git-cat-file plumbinginterrogators\n git-check-attr purehelpers\n git-check-ignore purehelpers\n git-check-mailmap purehelpers\n-git-checkout mainporcelain common-history\n+git-checkout mainporcelain history\n git-checkout-index plumbingmanipulators\n git-check-ref-format purehelpers\n git-cherry ancillaryinterrogators\n git-cherry-pick mainporcelain\n git-citool mainporcelain\n git-clean mainporcelain\n-git-clone mainporcelain common-init\n+git-clone mainporcelain init\n git-column purehelpers\n-git-commit mainporcelain common-history\n+git-commit mainporcelain history\n git-commit-tree plumbingmanipulators\n git-config ancillarymanipulators\n git-count-objects ancillaryinterrogators\n@@ -46,14 +46,14 @@ git-cvsimport foreignscminterface\n git-cvsserver foreignscminterface\n git-daemon synchingrepositories\n git-describe mainporcelain\n-git-diff mainporcelain common-history\n+git-diff mainporcelain history\n git-diff-files plumbinginterrogators\n git-diff-index plumbinginterrogators\n git-diff-tree plumbinginterrogators\n git-difftool ancillaryinterrogators\n git-fast-export\t\t\t\tancillarymanipulators\n git-fast-import\t\t\t\tancillarymanipulators\n-git-fetch mainporcelain common-remote\n+git-fetch mainporcelain remote\n git-fetch-pack synchingrepositories\n git-filter-branch ancillarymanipulators\n git-fmt-merge-msg purehelpers\n@@ -62,7 +62,7 @@ git-format-patch mainporcelain\n git-fsck\t ancillaryinterrogators\n git-gc mainporcelain\n git-get-tar-commit-id ancillaryinterrogators\n-git-grep mainporcelain common-info\n+git-grep mainporcelain info\n git-gui mainporcelain\n git-hash-object plumbingmanipulators\n git-help\t\t\t\tancillaryinterrogators\n@@ -71,17 +71,17 @@ git-http-fetch synchelpers\n git-http-push synchelpers\n git-imap-send foreignscminterface\n git-index-pack plumbingmanipulators\n-git-init mainporcelain common-init\n+git-init mainporcelain init\n git-instaweb ancillaryinterrogators\n git-interpret-trailers purehelpers\n gitk mainporcelain\n-git-log mainporcelain common-info\n+git-log mainporcelain info\n git-ls-files plumbinginterrogators\n git-ls-remote plumbinginterrogators\n git-ls-tree plumbinginterrogators\n git-mailinfo purehelpers\n git-mailsplit purehelpers\n-git-merge mainporcelain common-history\n+git-merge mainporcelain history\n git-merge-base plumbinginterrogators\n git-merge-file plumbingmanipulators\n git-merge-index plumbingmanipulators\n@@ -90,7 +90,7 @@ git-mergetool ancillarymanipulators\n git-merge-tree ancillaryinterrogators\n git-mktag plumbingmanipulators\n git-mktree plumbingmanipulators\n-git-mv mainporcelain common-worktree\n+git-mv mainporcelain worktree\n git-name-rev plumbinginterrogators\n git-notes mainporcelain\n git-p4 foreignscminterface\n@@ -101,11 +101,11 @@ git-parse-remote synchelpers\n git-patch-id purehelpers\n git-prune ancillarymanipulators\n git-prune-packed plumbingmanipulators\n-git-pull mainporcelain common-remote\n-git-push mainporcelain common-remote\n+git-pull mainporcelain remote\n+git-push mainporcelain remote\n git-quiltimport foreignscminterface\n git-read-tree plumbingmanipulators\n-git-rebase mainporcelain common-history\n+git-rebase mainporcelain history\n git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n@@ -114,28 +114,28 @@ git-repack ancillarymanipulators\n git-replace ancillarymanipulators\n git-request-pull foreignscminterface\n git-rerere ancillaryinterrogators\n-git-reset mainporcelain common-worktree\n+git-reset mainporcelain worktree\n git-revert mainporcelain\n git-rev-list plumbinginterrogators\n git-rev-parse ancillaryinterrogators\n-git-rm mainporcelain common-worktree\n+git-rm mainporcelain worktree\n git-send-email foreignscminterface\n git-send-pack synchingrepositories\n git-shell synchelpers\n git-shortlog mainporcelain\n-git-show mainporcelain common-info\n+git-show mainporcelain info\n git-show-branch ancillaryinterrogators\n git-show-index plumbinginterrogators\n git-show-ref plumbinginterrogators\n git-sh-i18n purehelpers\n git-sh-setup purehelpers\n git-stash mainporcelain\n-git-status mainporcelain common-info\n+git-status mainporcelain info\n git-stripspace purehelpers\n git-submodule mainporcelain\n git-svn foreignscminterface\n git-symbolic-ref plumbingmanipulators\n-git-tag mainporcelain common-history\n+git-tag mainporcelain history\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n-- \n2.4.0\n"},{"id":"261229","messageId":"1431608351-9413-6-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH 5/5] help.c: output the typical Git workflow","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:10Z","receivedAt":"2015-05-14T12:59: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 explain their relationship\nwith the typical Git workflow:\n\nThe typical Git workflow includes:\n\nstart a working area (see also: git help tutorial):\n clone Clone a repository into a new directory\n init Create an empty Git repository or reinitialize [...]\n\nwork on the current change (see also: git help everyday):\n add Add file contents to the index\n reset Reset current HEAD to the specified state\n\nexamine the history and state (see also: git help revisions):\n log Show commit logs\n status Show the working tree status\n\n [...]\n\nHelped-by: Eric Sunshine \nSigned-off-by: Sébastien Guimmara \n---\n help.c | 24 +++++++++++++++++++++++-\n 1 file changed, 23 insertions(+), 1 deletion(-)\n\ndiff --git a/help.c b/help.c\nindex 2072a87..bdb69d1 100644\n--- a/help.c\n+++ b/help.c\n@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,\n \t}\n }\n \n+int cmd_group_cmp(const void *elem1, const void *elem2)\n+{\n+\tconst struct cmdname_help *e1 = elem1;\n+\tconst struct cmdname_help *e2 = elem2;\n+\n+\tif (e1->group < e2->group)\n+\t\treturn -1;\n+\tif (e1->group > e2->group)\n+\t\treturn 1;\n+\treturn strcmp(e1->name, e2->name);\n+}\n+\n void list_common_cmds_help(void)\n {\n \tint i, longest = 0;\n+\tint current_grp = -1;\n \n \tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n \t\tif (longest < strlen(common_cmds[i].name))\n \t\t\tlongest = strlen(common_cmds[i].name);\n \t}\n \n-\tputs(_(\"The most commonly used git commands are:\"));\n+\tqsort(common_cmds, ARRAY_SIZE(common_cmds),\n+\t\tsizeof(common_cmds[0]), cmd_group_cmp);\n+\n+\tputs(_(\"The typical Git workflow includes:\"));\n+\n \tfor (i = 0; i < ARRAY_SIZE(common_cmds); i++) {\n+\t\tif (common_cmds[i].group != current_grp) {\n+\t\t\tprintf(\"\\n%s:\\n\", _(common_cmd_groups[common_cmds[i].group]));\n+\t\t\tcurrent_grp = common_cmds[i].group;\n+\t\t}\n+\n \t\tprintf(\" %s \", common_cmds[i].name);\n \t\tmput_char(' ', longest - strlen(common_cmds[i].name));\n \t\tputs(_(common_cmds[i].help));\n-- \n2.4.0\n"},{"id":"261231","messageId":"1431608351-9413-7-git-send-email-sebastien.guimmara@gmail.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"[PATCH 5/5] help.c: output the typical Git workflow","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-14T12:59:11Z","receivedAt":"2015-05-14T12:59:11Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"From: Eric Sunshine sunshineco.com>\nSubject: Re: [PATCH v5 0/6] git help: group common commands by theme\nNewsgroups: gmane.comp.version-control.git\nDate: 2015-05-11 05:52:50 GMT (1 day, 12 hours and 19 minutes ago)\n\nOn Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara\n gmail.com> wrote:\n> Sébastien Guimmara (6):\n> generate-cmdlist: parse common group commands\n> help.c: output the typical Git workflow\n> command-list.txt: group common commands by theme\n> Makefile: update to new command-list.txt format\n> new-command.txt: mention the common command groups\n> cmd-list.perl: ignore all lines until [commands]\n\nWhen preparing a patch series, it's important to think not just about\nthe final result but also the state of the project at any point within\nthe series. The project should remain in a working state (not broken\nand not regressed) at all steps during the patch series[1]. As each\npatch is applied, you should be able to build git successfully, and\nrun \"git help\" and get expected results (for that point in the\nseries). If you can't do either, then there is a problem.\n\nUnfortunately, the organization of this series (v5) breaks the build\nand raw functionality from the get-go. Here is a proposed organization\nwhich will keep the project in a sane state as each patch is applied:\n\npatch 1:\n\n[x] Add a [commands] header to command-list.txt\n[x] check-docs in Makefile, and either\n[x] cmd-list.perl to ignore everything up to and including [commands]. \n\nYou're not actually doing any classification in\ncommand-list.txt at this point, but instead merely preparing the\nmachinery to deal with the [commands] header (and the [common] section\nwhich you will add in a subsequent patch).\n\npatch 2:\n\n[x] Add the [common] block to command-list.txt and tag each of\nthe common commands with an attribute from [common]. Do *not*,\nhowever, remove the old \"common\" tag at this point since\ngenerate-cmdlist.sh still needs it.\n\npatch 3: \n[x] Introduce generate-cmdlist.awk and \n[x] retire generate-cmdlist.sh, \n[x] along with the associated Makefile changes. This\npatch should be exactly the one I posted[2] (between the \"--- >8 ---\"\nlines), along with the minor fixup[3]. The changes in that patch are a\nlogical unit, so they shouldn't be split up (as you did in v5 between\npatches 1/6 and 4/6).\n\npatch 4: \n[x] Drop the old \"common\" attribute from command-list.txt items\nsince it's no longer needed by any machinery.\n\npatch 5: Update help.c to group and sort the commands using the new\ncommon_cmd_groups[] array and common_commands[].group field.\n\npatch 6 [optional]: Update howto/new-command.txt. Alternately, and\nprobably preferably, fold this documentation update into patch 2 and\nomit this step.\n\n[1]: This is called \"preserving bisectability\". See \"git bisect\".\n[2]: http://article.gmane.org/gmane.comp.version-control.git/268598\n[3]: http://article.gmane.org/gmane.comp.version-control.git/268599\n"},{"id":"261286","messageId":"xmqqa8x6khlr.fsf@gitster.dls.corp.google.com","threadId":"39334","inReplyTo":"1431608351-9413-1-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH 0/5] git help: group common commands by theme","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-14T20:51:44Z","receivedAt":"2015-05-14T20:51:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> This v6 is very similar in content to the v5 [1], except minor formatting\n> adjustments in 'git help' output and recommendations from Eric.\n>\n> The major change is in the patch series itself. Commits have been\n> reordered and adjusted so that each 'apply' doesn't break the build, and\n> preserve bisectability.\n\nHmph, did you decide to abandon the \"whitespace fix\" patch? This\ndoes not seem to be based on that one, and it would be crazy to\nhave these patches *and* the other one as independent two topics\nand expect them to be merged cleanly later.\n"},{"id":"261288","messageId":"xmqq617ukhal.fsf@gitster.dls.corp.google.com","threadId":"39334","inReplyTo":"1431608351-9413-4-git-send-email-sebastien.guimmara@gmail.com","subject":"Re: [PATCH 3/5] generate-cmdlist: parse common group commands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-14T20:58:26Z","receivedAt":"2015-05-14T20:58:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sébastien Guimmara writes:\n\n> From: Eric Sunshine \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> Signed-off-by: Sébastien Guimmara \n> ---\n\nI seem to be getting an empty common_cmds[] list after this step\n(with GNU Awk 4.0.1, ICIM).\n"},{"id":"261290","messageId":"CAPig+cTrDd3eYXo1WPoWRk5XSuLyH_m_VU1JsnP8pjkM=n6O2Q@mail.gmail.com","threadId":"39334","inReplyTo":"xmqq617ukhal.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 3/5] generate-cmdlist: parse common group commands","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-05-14T21:05:26Z","receivedAt":"2015-05-14T21:05:26Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 14, 2015 at 4:58 PM, Junio C Hamano wrote:\n> Sébastien Guimmara writes:\n>> From: Eric Sunshine \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>> Signed-off-by: Sébastien Guimmara \n>> ---\n>\n> I seem to be getting an empty common_cmds[] list after this step\n> (with GNU Awk 4.0.1, ICIM).\n\nIndeed. I haven't had a chance to look at this version of the series\nyet, but a quick glance shows that this is because patch 2/5 uses\n\"common-\" as a prefix rather than as a standalone tag. That is, lines\nin patch 2/5 like this:\n\n git-add mainporcelain common-worktree\n\nshould be:\n\n git-add mainporcelain common worktree\n\nas proposed here[1]. And, then patch 4/5 should drop the standalone\n\"common\" tag rather than the \"common-\" prefix.\n\n[1]: http://article.gmane.org/gmane.comp.version-control.git/268756\n"},{"id":"261340","messageId":"555604A2.6080204@gmail.com","threadId":"39334","inReplyTo":"xmqqa8x6khlr.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 0/5] git help: group common commands by theme","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T14:37:22Z","receivedAt":"2015-05-15T14:37:22Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/14/2015 10:51 PM, Junio C Hamano wrote:\n> Sébastien Guimmara writes:\n>\n>> This v6 is very similar in content to the v5 [1], except minor formatting\n>> adjustments in 'git help' output and recommendations from Eric.\n>>\n>> The major change is in the patch series itself. Commits have been\n>> reordered and adjusted so that each 'apply' doesn't break the build, and\n>> preserve bisectability.\n>\n> Hmph, did you decide to abandon the \"whitespace fix\" patch? This\n> does not seem to be based on that one, and it would be crazy to\n> have these pa beltches *and* the other one as independent two topics\n> and expect them to be merged cleanly later.\n>\n\nMy mistake : I believed the preparatory patch and the new series had to be\nindependent, and thus had to be merged in your own tree. I will correct this.\n\nThanks\n"},{"id":"261341","messageId":"55560544.3090705@gmail.com","threadId":"39334","inReplyTo":"CAPig+cTrDd3eYXo1WPoWRk5XSuLyH_m_VU1JsnP8pjkM=n6O2Q@mail.gmail.com","subject":"Re: [PATCH 3/5] generate-cmdlist: parse common group commands","fromName":"Sébastien Guimmara","fromEmail":"sebastien.guimmara@gmail.com","sentAt":"2015-05-15T14:40:04Z","receivedAt":"2015-05-15T14:40:04Z","isPatch":true,"sender":{"key":"sebastien.guimmara@gmail.com","avatar":"https://gravatar.com/avatar/05d0b6a53712c5ed78d640976986949a3bda22c0dbf5ff13cabdd12c3f4094d6?d=mp&s=160"},"body":"On 05/14/2015 11:05 PM, Eric Sunshine wrote:\n> On Thu, May 14, 2015 at 4:58 PM, Junio C Hamano wrote:\n>> Sébastien Guimmara writes:\n>>> From: Eric Sunshine \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>>> Signed-off-by: Sébastien Guimmara \n>>> ---\n>>\n>> I seem to be getting an empty common_cmds[] list after this step\n>> (with GNU Awk 4.0.1, ICIM).\n>\n> Indeed. I haven't had a chance to look at this version of the series\n> yet, but a quick glance shows that this is because patch 2/5 uses\n> \"common-\" as a prefix rather than as a standalone tag. That is, lines\n> in patch 2/5 like this:\n>\n> git-add mainporcelain common-worktree\n>\n> should be:\n>\n> git-add mainporcelain common worktree\n>\n> as proposed here[1]. And, then patch 4/5 should drop the standalone\n> \"common\" tag rather than the \"common-\" prefix.\n>\n> [1]: http://article.gmane.org/gmane.comp.version-control.git/268756\n>\n\nIndeed, I misread your description. Thanks for pointing that out,\nI will correct this.\n"}]}