[PATCH v5 0/6] git help: group common commands by theme

[PATCH v5 0/6] git help: group common commands by theme

[Sébastien Guimmara]

This v5 includes suggestions from Junio C Hamano, Eric Sunshine and 
Emma Jane Hogbin Westby, as well as a complete and much cleaner rewrite 
of the generate-cmdlist parser in awk by Eric Sunshine.

The main idea of this version is to go a little further in the idea of
making 'git help' a warmer welcome to the unfamiliar user, by a gentle
summary of the typical Git workflow. Instead of simply telling what
the Git common commands are, we rather explain how they fit in the
typical workflow, ordered in (chrono)logical order:

1. I setup my repo (init)
2. I work on changes (worktree)
3. I gather information on the history (info)
4. I grow, tweak and clean my local history (history)
5. To finally share my nice contribution with the world (remote)

Sébastien Guimmara (6):
  generate-cmdlist: parse common group commands
  help.c: output the typical Git workflow
  command-list.txt: group common commands by theme
  Makefile: update to new command-list.txt format
  new-command.txt: mention the common command groups
  cmd-list.perl: ignore all lines until [commands]

 Documentation/cmd-list.perl         |  8 +++++-
 Documentation/howto/new-command.txt |  4 ++-
 Makefile                            |  8 +++---
 command-list.txt                    | 56 ++++++++++++++++++++++---------------
 generate-cmdlist.awk                | 38 +++++++++++++++++++++++++
 help.c                              | 25 +++++++++++++++--
 6 files changed, 109 insertions(+), 30 deletions(-)
 create mode 100644 generate-cmdlist.awk

-- 
2.4.0

[PATCH v5 1/6] generate-cmdlist: parse common group commands

[Sébastien Guimmara]

Parse the [common] block to create the array of group descriptions:

static char *common_cmd_groups[] = {
    N_("start a working area (see also: git help tutorial)"),
    N_("work on the current change (see also: git help everyday)"),
    N_("examine the history and state (see also: git help revisions)"),
    N_("grow, mark and tweak your history"),
    N_("collaborate (see also: git help workflows)"),
};

then map each element of common_cmds[] to a group via its index:

static struct cmdname_help common_cmds[] = {
    {"add", N_("Add file contents to the index"), 1},
    {"branch", N_("List, create, or delete branches"), 4},
    {"checkout", N_("Checkout a branch or paths to the ..."), 4},
    {"clone", N_("Clone a repository into a new directory"), 0},
    {"commit", N_("Record changes to the repository"), 4},
    ...
};

so that 'git help' can print those commands grouped by theme.

Only commands tagged with an attribute from [common] are emitted to
common_cmds[].

[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 generate-cmdlist.awk | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 generate-cmdlist.awk

diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
new file mode 100644
index 0000000..cbaac88
--- /dev/null
+++ b/generate-cmdlist.awk
@@ -0,0 +1,38 @@
+BEGIN {
+	print "/* Automatically generated by generate-cmdlist.awk */\n"
+	print "struct cmdname_help {"
+	print "\tchar name[16];"
+	print "\tchar help[80];"
+	print "\tunsigned char group;"
+	print "};\n"
+	print "static char *common_cmd_groups[] = {"
+}
+/^#/ || /^[ 	]*$/ { next }
+state == 2 {
+	for (i = 2; i <= NF; i++)
+		if (grp[$i]) {
+			f = "Documentation/"$1".txt"
+			while (getline s <f > 0)
+				if (match(s, $1" - ")) {
+					t = substr(s, length($1" - ") + 1)
+					break
+				}
+			close(f)
+			printf "\t{\"%s\", N_(\"%s\"), %s},\n",
+				substr($1, length("git-") + 1), t, grp[$i] - 1
+			break
+		}
+}
+/\[commands\]/ {
+	print "};\n\nstatic struct cmdname_help common_cmds[] = {"
+	state = 2
+}
+state == 1 {
+	grp[$1] = ++n
+	sub($1"[ 	][ 	]*", "")
+	printf "\tN_(\"%s\"),\n", $0
+}
+/\[common\]/ {
+	state = 1
+}
+END { print "};" }
-- 
2.4.0

[PATCH v5 2/6] help.c: output the typical Git workflow

[Sébastien Guimmara]

'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
   add        Add file contents to the index
   bisect     Find by binary search the change that introduced a bug
   branch     List, create, or delete branches
   checkout   Checkout a branch or paths to the working tree
   clone      Clone a repository into a new directory
   commit     Record changes to the repository
   [...]

without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:

The typical Git workflow includes:

   * start a working area (see also: git help tutorial):
      clone      Clone a repository into a new directory
      init       Create an empty Git repository or reinitialize [...]

   * work on the current change (see also: git help everyday):
      add        Add file contents to the index
      reset      Reset current HEAD to the specified state

   * examine the history and state (see also: git help revisions):
      log        Show commit logs
      status     Show the working tree status

   [...]

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 help.c | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/help.c b/help.c
index 2072a87..1df205f 100644
--- a/help.c
+++ b/help.c
@@ -218,6 +218,18 @@ void list_commands(unsigned int colopts,
 	}
 }
 
+int cmd_group_cmp(const void *elem1, const void *elem2)
+{
+	const struct cmdname_help *e1 = elem1;
+	const struct cmdname_help *e2 = elem2;
+
+	if (e1->group < e2->group)
+		return -1;
+	if (e1->group > e2->group)
+		return 1;
+	return strcmp(e1->name, e2->name);
+}
+
 void list_common_cmds_help(void)
 {
 	int i, longest = 0;
@@ -227,9 +239,18 @@ void list_common_cmds_help(void)
 			longest = strlen(common_cmds[i].name);
 	}
 
-	puts(_("The most commonly used git commands are:"));
+	qsort(common_cmds, ARRAY_SIZE(common_cmds),
+		sizeof(common_cmds[0]), cmd_group_cmp);
+
+	puts(_("The typical Git workflow includes:"));
+
 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
-		printf("   %s   ", common_cmds[i].name);
+		if (common_cmds[i].group != current_grp) {
+			printf("\n   * %s:\n", _(common_cmd_groups[common_cmds[i].group]));
+			current_grp = common_cmds[i].group;
+		}
+
+		printf("      %s   ", common_cmds[i].name);
 		mput_char(' ', longest - strlen(common_cmds[i].name));
 		puts(_(common_cmds[i].help));
 	}
-- 
2.4.0

[PATCH v5 3/6] command-list.txt: group common commands by theme

[Sébastien Guimmara]

Declare groups for common commands in the [common] block,
followed by group names and descriptions:

    [common]
    init         start a working area (see also: git help tutorial)
    worktree     work on the current change (see also: git [...]
    info         examine the history and state (see also: git [...]
    history      grow, mark and tweak your history
    remote       collaborate (see also: git help workflows)

Some descriptions include a 'see also' to redirect user to more
detailed documentation.

Then, in the [commands] block, map all common commands with a group:

    [commands]
    git-add        mainporcelain     worktree
    git-branch     mainporcelain     history
    git-checkout   mainporcelain     history
    [...]

So that 'git help' outputs those commands in headered groups.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by:  Emma Jane Hogbin Westby <emma.westby@gmail.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 command-list.txt | 56 ++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index f1eae08..7e7ce53 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,41 @@
+# common commands are grouped by themes
+# this order is the same that output by 'git help'
+# map each common commands in the [commands] list to one of the groups.
+# a command should not be marked both [deprecated] and [common]
+[common]
+init         start a working area (see also: git help tutorial)
+worktree     work on the current change (see also: git help everyday)
+info         examine the history and state (see also: git help revisions)
+history      grow, mark and tweak your history
+remote       collaborate (see also: git help workflows)
+
 # List of known git commands.
-# command name				category [deprecated] [common]
-git-add                                 mainporcelain common
+# command name         [deprecated]     category                [common]
+[commands]
+git-add                                 mainporcelain           worktree
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators
 git-apply                               plumbingmanipulators
 git-archimport                          foreignscminterface
 git-archive                             mainporcelain
-git-bisect                              mainporcelain common
+git-bisect                              mainporcelain           info
 git-blame                               ancillaryinterrogators
-git-branch                              mainporcelain common
+git-branch                              mainporcelain           history
 git-bundle                              mainporcelain
 git-cat-file                            plumbinginterrogators
 git-check-attr                          purehelpers
 git-check-ignore                        purehelpers
 git-check-mailmap                       purehelpers
-git-checkout                            mainporcelain common
+git-checkout                            mainporcelain           history
 git-checkout-index                      plumbingmanipulators
 git-check-ref-format                    purehelpers
 git-cherry                              ancillaryinterrogators
 git-cherry-pick                         mainporcelain
 git-citool                              mainporcelain
 git-clean                               mainporcelain
-git-clone                               mainporcelain common
+git-clone                               mainporcelain           init
 git-column                              purehelpers
-git-commit                              mainporcelain common
+git-commit                              mainporcelain           history
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
@@ -35,14 +47,14 @@ git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
 git-daemon                              synchingrepositories
 git-describe                            mainporcelain
-git-diff                                mainporcelain common
+git-diff                                mainporcelain           history
 git-diff-files                          plumbinginterrogators
 git-diff-index                          plumbinginterrogators
 git-diff-tree                           plumbinginterrogators
 git-difftool                            ancillaryinterrogators
 git-fast-export				ancillarymanipulators
 git-fast-import				ancillarymanipulators
-git-fetch                               mainporcelain common
+git-fetch                               mainporcelain           remote
 git-fetch-pack                          synchingrepositories
 git-filter-branch                       ancillarymanipulators
 git-fmt-merge-msg                       purehelpers
@@ -51,7 +63,7 @@ git-format-patch                        mainporcelain
 git-fsck	                        ancillaryinterrogators
 git-gc                                  mainporcelain
 git-get-tar-commit-id                   ancillaryinterrogators
-git-grep                                mainporcelain common
+git-grep                                mainporcelain           info
 git-gui                                 mainporcelain
 git-hash-object                         plumbingmanipulators
 git-help				ancillaryinterrogators
@@ -60,17 +72,17 @@ git-http-fetch                          synchelpers
 git-http-push                           synchelpers
 git-imap-send                           foreignscminterface
 git-index-pack                          plumbingmanipulators
-git-init                                mainporcelain common
+git-init                                mainporcelain           init
 git-instaweb                            ancillaryinterrogators
 git-interpret-trailers                  purehelpers
 gitk                                    mainporcelain
-git-log                                 mainporcelain common
+git-log                                 mainporcelain           info
 git-ls-files                            plumbinginterrogators
 git-ls-remote                           plumbinginterrogators
 git-ls-tree                             plumbinginterrogators
 git-mailinfo                            purehelpers
 git-mailsplit                           purehelpers
-git-merge                               mainporcelain common
+git-merge                               mainporcelain           history
 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
 git-merge-index                         plumbingmanipulators
@@ -79,7 +91,7 @@ git-mergetool                           ancillarymanipulators
 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators
-git-mv                                  mainporcelain common
+git-mv                                  mainporcelain           worktree
 git-name-rev                            plumbinginterrogators
 git-notes                               mainporcelain
 git-p4                                  foreignscminterface
@@ -90,11 +102,11 @@ git-parse-remote                        synchelpers
 git-patch-id                            purehelpers
 git-prune                               ancillarymanipulators
 git-prune-packed                        plumbingmanipulators
-git-pull                                mainporcelain common
-git-push                                mainporcelain common
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
 git-quiltimport                         foreignscminterface
 git-read-tree                           plumbingmanipulators
-git-rebase                              mainporcelain common
+git-rebase                              mainporcelain           history
 git-receive-pack                        synchelpers
 git-reflog                              ancillarymanipulators
 git-relink                              ancillarymanipulators
@@ -103,28 +115,28 @@ git-repack                              ancillarymanipulators
 git-replace                             ancillarymanipulators
 git-request-pull                        foreignscminterface
 git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain common
+git-reset                               mainporcelain           worktree
 git-revert                              mainporcelain
 git-rev-list                            plumbinginterrogators
 git-rev-parse                           ancillaryinterrogators
-git-rm                                  mainporcelain common
+git-rm                                  mainporcelain           worktree
 git-send-email                          foreignscminterface
 git-send-pack                           synchingrepositories
 git-shell                               synchelpers
 git-shortlog                            mainporcelain
-git-show                                mainporcelain common
+git-show                                mainporcelain           info
 git-show-branch                         ancillaryinterrogators
 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators
 git-sh-i18n                             purehelpers
 git-sh-setup                            purehelpers
 git-stash                               mainporcelain
-git-status                              mainporcelain common
+git-status                              mainporcelain           info
 git-stripspace                          purehelpers
 git-submodule                           mainporcelain
 git-svn                                 foreignscminterface
 git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain common
+git-tag                                 mainporcelain           history
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
 git-update-index                        plumbingmanipulators
-- 
2.4.0

[PATCH v5 4/6] Makefile: update to new command-list.txt format

[Sébastien Guimmara]

* In target common-cmds.h:
  The AWK script 'generate-cmdlist.awk' replaces 'generate-cmdlist.sh'

* In target check-docs:
  command-list.txt now contains common commands group in
  the header [common]. sed ignore all lines in command-list.txt
  until the [commands] list to correctly checks for missing
  documentation on Git commands.

For the target common-cmds.h part:
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>

For the target check-docs part:
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 Makefile | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 5f3987f..9f333e9 100644
--- a/Makefile
+++ b/Makefile
@@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X
 	ln -s $< $@ 2>/dev/null || \
 	cp $< $@
 
-common-cmds.h: ./generate-cmdlist.sh command-list.txt
+common-cmds.h: generate-cmdlist.awk command-list.txt
 
 common-cmds.h: $(wildcard Documentation/git-*.txt)
-	$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+	$(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@
 
 SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
 	$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
@@ -2447,7 +2447,7 @@ check-docs::
 		esac ; \
 		test -f "Documentation/$$v.txt" || \
 		echo "no doc: $$v"; \
-		sed -e '/^#/d' command-list.txt | \
+		sed -e '1,/^\[commands\]/d' <command-list.txt | \
 		grep -q "^$$v[ 	]" || \
 		case "$$v" in \
 		git) ;; \
@@ -2455,7 +2455,7 @@ check-docs::
 		esac ; \
 	done; \
 	( \
-		sed -e '/^#/d' \
+		sed -e '1,/^\[commands\]/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
-- 
2.4.0

[PATCH v5 5/6] new-command.txt: mention the common command groups

[Sébastien Guimmara]

In the 6. step, add information about the common group commands
found in command-list.txt.

Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 Documentation/howto/new-command.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index d7de5a3..e7b0cc2 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.txt
@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
 that categorizes commands by type, so they can be listed in appropriate
 subsections in the documentation's summary command list.  Add an entry
 for yours.  To understand the categories, look at git-commands.txt
-in the main directory.
+in the main directory. If the new command is part of the typical Git
+workflow and you believe it's common enough to be mentioned in
+'git help', map this command to a common group in the column [common]
 
 7. Give the maintainer one paragraph to include in the RelNotes file
 to describe the new feature; a good place to do so is in the cover
-- 
2.4.0

[PATCH v5 6/6] cmd-list.perl: ignore all lines until [commands]

[Sébastien Guimmara]

command-list.txt contains a [common] block that should be ignored
by the Documentation checker cmd-list.perl.

Filter out this block before the actual processing of the command list.

Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 Documentation/cmd-list.perl | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..d581378 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -38,8 +38,14 @@ sub format_one {
 	}
 }
 
+my @filtered = ();
+while (<>)
+{
+	push (@filtered, $_) unless 1../^\[commands\]/;
+}
+
 my %cmds = ();
-for (sort <>) {
+for (sort @filtered) {
 	next if /^#/;
 
 	chomp;
-- 
2.4.0

Re: [PATCH v5 0/6] git help: group common commands by theme

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Sébastien Guimmara (6):
>   generate-cmdlist: parse common group commands
>   help.c: output the typical Git workflow
>   command-list.txt: group common commands by theme
>   Makefile: update to new command-list.txt format
>   new-command.txt: mention the common command groups
>   cmd-list.perl: ignore all lines until [commands]

When preparing a patch series, it's important to think not just about
the final result but also the state of the project at any point within
the series. The project should remain in a working state (not broken
and not regressed) at all steps during the patch series[1]. As each
patch is applied, you should be able to build git successfully, and
run "git help" and get expected results (for that point in the
series). If you can't do either, then there is a problem.

Unfortunately, the organization of this series (v5) breaks the build
and raw functionality from the get-go. Here is a proposed organization
which will keep the project in a sane state as each patch is applied:

patch 1: Add a [commands] header to command-list.txt and augment
generate-cmdlist.sh, check-docs in Makefile, and either
Documentation/Makefile or cmd-list.perl to ignore everything up to and
including [commands]. You're not actually doing any classification in
command-list.txt at this point, but instead merely preparing the
machinery to deal with the [commands] header (and the [common] section
which you will add in a subsequent patch).

patch 2: Add the [common] block to command-list.txt and tag each of
the common commands with an attribute from [common]. Do *not*,
however, remove the old "common" tag at this point since
generate-cmdlist.sh still needs it.

patch 3: Introduce generate-cmdlist.awk and retire
generate-cmdlist.sh, along with the associated Makefile changes. This
patch should be exactly the one I posted[2] (between the "--- >8 ---"
lines), along with the minor fixup[3]. The changes in that patch are a
logical unit, so they shouldn't be split up (as you did in v5 between
patches 1/6 and 4/6).

patch 4: Drop the old "common" attribute from command-list.txt items
since it's no longer needed by any machinery.

patch 5: Update help.c to group and sort the commands using the new
common_cmd_groups[] array and common_commands[].group field.

patch 6 [optional]: Update howto/new-command.txt. Alternately, and
probably preferably, fold this documentation update into patch 2 and
omit this step.

[1]: This is called "preserving bisectability". See "git bisect".
[2]: http://article.gmane.org/gmane.comp.version-control.git/268598
[3]: http://article.gmane.org/gmane.comp.version-control.git/268599

Re: [PATCH v5 1/6] generate-cmdlist: parse common group commands

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Parse the [common] block to create the array of group descriptions:

Since you're resending a patch which I authored[1], the very first
line of the email body should be:

    From: Eric Sunshine <sunshine@sunshineco.com>

which git-am will pick up automatically in order to assign proper
attribution when the patch is applied.

More below.

> static char *common_cmd_groups[] = {
>     [...]
> };
>
> then map each element of common_cmds[] to a group via its index:
>
> static struct cmdname_help common_cmds[] = {
>     [...]
> };
>
> so that 'git help' can print those commands grouped by theme.
>
> Only commands tagged with an attribute from [common] are emitted to
> common_cmds[].
>
> [commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]
>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>

Likewise, since you're resending[1] this patch you should add your own
sign-off following the sign-off of the patch's author.

> ---
>  generate-cmdlist.awk | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>  create mode 100644 generate-cmdlist.awk

Each patch should be a self-contained logical unit, even if multiple
files are touched.

In addition to introducing generate-cmdlist.awk, the original patch I
wrote[1] also changed Makefile and removed generate-cmdlist.sh. Those
changes are a logical unit, and shouldn't be split up, as you did here
with v5 by moving the Makefile modifications to patch 4/6. Removal of
generate-cmdlist.sh seems to have been lost entirely in v5.

[1]: http://article.gmane.org/gmane.comp.version-control.git/268598

> diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk
> new file mode 100644
> index 0000000..cbaac88
> --- /dev/null
> +++ b/generate-cmdlist.awk
> @@ -0,0 +1,38 @@
> +BEGIN {
> +       print "/* Automatically generated by generate-cmdlist.awk */\n"
> +       print "struct cmdname_help {"
> +       print "\tchar name[16];"
> +       print "\tchar help[80];"
> +       print "\tunsigned char group;"
> +       print "};\n"
> +       print "static char *common_cmd_groups[] = {"
> +}
> +/^#/ || /^[    ]*$/ { next }
> +state == 2 {
> +       for (i = 2; i <= NF; i++)
> +               if (grp[$i]) {
> +                       f = "Documentation/"$1".txt"
> +                       while (getline s <f > 0)
> +                               if (match(s, $1" - ")) {
> +                                       t = substr(s, length($1" - ") + 1)
> +                                       break
> +                               }
> +                       close(f)
> +                       printf "\t{\"%s\", N_(\"%s\"), %s},\n",
> +                               substr($1, length("git-") + 1), t, grp[$i] - 1
> +                       break
> +               }
> +}
> +/\[commands\]/ {
> +       print "};\n\nstatic struct cmdname_help common_cmds[] = {"
> +       state = 2
> +}
> +state == 1 {
> +       grp[$1] = ++n
> +       sub($1"[        ][      ]*", "")
> +       printf "\tN_(\"%s\"),\n", $0
> +}
> +/\[common\]/ {
> +       state = 1
> +}
> +END { print "};" }
> --
> 2.4.0

Re: [PATCH v5 3/6] command-list.txt: group common commands by theme

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Declare groups for common commands in the [common] block,
> followed by group names and descriptions:
>
>     [common]
>     init         start a working area (see also: git help tutorial)
>     worktree     work on the current change (see also: git [...]
>     info         examine the history and state (see also: git [...]
>     history      grow, mark and tweak your history
>     remote       collaborate (see also: git help workflows)
>
> Some descriptions include a 'see also' to redirect user to more
> detailed documentation.

The example nicely shows the "see also", so this trailing sentence is
somewhat redundant.

More below.

> Then, in the [commands] block, map all common commands with a group:
>
>     [commands]
>     git-add        mainporcelain     worktree
>     git-branch     mainporcelain     history
>     git-checkout   mainporcelain     history
>     [...]
>
> So that 'git help' outputs those commands in headered groups.
>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by:  Emma Jane Hogbin Westby <emma.westby@gmail.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/command-list.txt b/command-list.txt
> index f1eae08..7e7ce53 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,29 +1,41 @@
> +# common commands are grouped by themes
> +# this order is the same that output by 'git help'
> +# map each common commands in the [commands] list to one of the groups.

Grammar: "map each common command"

Maybe also "one of these groups".

> +# a command should not be marked both [deprecated] and [common]

I wonder if it is really necessary to state this, as there is no
technical reason for the restriction, and it should be common sense
(one would hope).

> +[common]
> +init         start a working area (see also: git help tutorial)
> +worktree     work on the current change (see also: git help everyday)
> +info         examine the history and state (see also: git help revisions)
> +history      grow, mark and tweak your history
> +remote       collaborate (see also: git help workflows)
> +
>  # List of known git commands.
> -# command name                         category [deprecated] [common]
> -git-add                                 mainporcelain common
> +# command name         [deprecated]     category                [common]

Why did [deprecated] move from following "category" to preceding it?

Also, I wonder if [common] should be spelled [<common>] or something
to distinguish it from [deprecated] which is a literal token. (I don't
care strongly; I'm just wondering.)

> +[commands]
> +git-add                                 mainporcelain           worktree
>  git-am                                  mainporcelain
>  git-annotate                            ancillaryinterrogators
>  git-apply                               plumbingmanipulators
>  git-archimport                          foreignscminterface
>  git-archive                             mainporcelain
> -git-bisect                              mainporcelain common
> +git-bisect                              mainporcelain           info
>  git-blame                               ancillaryinterrogators
> -git-branch                              mainporcelain common
> +git-branch                              mainporcelain           history
>  git-bundle                              mainporcelain
>  git-cat-file                            plumbinginterrogators
>  git-check-attr                          purehelpers
>  git-check-ignore                        purehelpers
>  git-check-mailmap                       purehelpers
> -git-checkout                            mainporcelain common
> +git-checkout                            mainporcelain           history
>  git-checkout-index                      plumbingmanipulators
>  git-check-ref-format                    purehelpers
>  git-cherry                              ancillaryinterrogators
>  git-cherry-pick                         mainporcelain
>  git-citool                              mainporcelain
>  git-clean                               mainporcelain
> -git-clone                               mainporcelain common
> +git-clone                               mainporcelain           init
>  git-column                              purehelpers
> -git-commit                              mainporcelain common
> +git-commit                              mainporcelain           history
>  git-commit-tree                         plumbingmanipulators
>  git-config                              ancillarymanipulators
>  git-count-objects                       ancillaryinterrogators
> @@ -35,14 +47,14 @@ git-cvsimport                           foreignscminterface
>  git-cvsserver                           foreignscminterface
>  git-daemon                              synchingrepositories
>  git-describe                            mainporcelain
> -git-diff                                mainporcelain common
> +git-diff                                mainporcelain           history
>  git-diff-files                          plumbinginterrogators
>  git-diff-index                          plumbinginterrogators
>  git-diff-tree                           plumbinginterrogators
>  git-difftool                            ancillaryinterrogators
>  git-fast-export                                ancillarymanipulators
>  git-fast-import                                ancillarymanipulators
> -git-fetch                               mainporcelain common
> +git-fetch                               mainporcelain           remote
>  git-fetch-pack                          synchingrepositories
>  git-filter-branch                       ancillarymanipulators
>  git-fmt-merge-msg                       purehelpers
> @@ -51,7 +63,7 @@ git-format-patch                        mainporcelain
>  git-fsck                               ancillaryinterrogators
>  git-gc                                  mainporcelain
>  git-get-tar-commit-id                   ancillaryinterrogators
> -git-grep                                mainporcelain common
> +git-grep                                mainporcelain           info
>  git-gui                                 mainporcelain
>  git-hash-object                         plumbingmanipulators
>  git-help                               ancillaryinterrogators
> @@ -60,17 +72,17 @@ git-http-fetch                          synchelpers
>  git-http-push                           synchelpers
>  git-imap-send                           foreignscminterface
>  git-index-pack                          plumbingmanipulators
> -git-init                                mainporcelain common
> +git-init                                mainporcelain           init
>  git-instaweb                            ancillaryinterrogators
>  git-interpret-trailers                  purehelpers
>  gitk                                    mainporcelain
> -git-log                                 mainporcelain common
> +git-log                                 mainporcelain           info
>  git-ls-files                            plumbinginterrogators
>  git-ls-remote                           plumbinginterrogators
>  git-ls-tree                             plumbinginterrogators
>  git-mailinfo                            purehelpers
>  git-mailsplit                           purehelpers
> -git-merge                               mainporcelain common
> +git-merge                               mainporcelain           history
>  git-merge-base                          plumbinginterrogators
>  git-merge-file                          plumbingmanipulators
>  git-merge-index                         plumbingmanipulators
> @@ -79,7 +91,7 @@ git-mergetool                           ancillarymanipulators
>  git-merge-tree                          ancillaryinterrogators
>  git-mktag                               plumbingmanipulators
>  git-mktree                              plumbingmanipulators
> -git-mv                                  mainporcelain common
> +git-mv                                  mainporcelain           worktree
>  git-name-rev                            plumbinginterrogators
>  git-notes                               mainporcelain
>  git-p4                                  foreignscminterface
> @@ -90,11 +102,11 @@ git-parse-remote                        synchelpers
>  git-patch-id                            purehelpers
>  git-prune                               ancillarymanipulators
>  git-prune-packed                        plumbingmanipulators
> -git-pull                                mainporcelain common
> -git-push                                mainporcelain common
> +git-pull                                mainporcelain           remote
> +git-push                                mainporcelain           remote
>  git-quiltimport                         foreignscminterface
>  git-read-tree                           plumbingmanipulators
> -git-rebase                              mainporcelain common
> +git-rebase                              mainporcelain           history
>  git-receive-pack                        synchelpers
>  git-reflog                              ancillarymanipulators
>  git-relink                              ancillarymanipulators
> @@ -103,28 +115,28 @@ git-repack                              ancillarymanipulators
>  git-replace                             ancillarymanipulators
>  git-request-pull                        foreignscminterface
>  git-rerere                              ancillaryinterrogators
> -git-reset                               mainporcelain common
> +git-reset                               mainporcelain           worktree
>  git-revert                              mainporcelain
>  git-rev-list                            plumbinginterrogators
>  git-rev-parse                           ancillaryinterrogators
> -git-rm                                  mainporcelain common
> +git-rm                                  mainporcelain           worktree
>  git-send-email                          foreignscminterface
>  git-send-pack                           synchingrepositories
>  git-shell                               synchelpers
>  git-shortlog                            mainporcelain
> -git-show                                mainporcelain common
> +git-show                                mainporcelain           info
>  git-show-branch                         ancillaryinterrogators
>  git-show-index                          plumbinginterrogators
>  git-show-ref                            plumbinginterrogators
>  git-sh-i18n                             purehelpers
>  git-sh-setup                            purehelpers
>  git-stash                               mainporcelain
> -git-status                              mainporcelain common
> +git-status                              mainporcelain           info
>  git-stripspace                          purehelpers
>  git-submodule                           mainporcelain
>  git-svn                                 foreignscminterface
>  git-symbolic-ref                        plumbingmanipulators
> -git-tag                                 mainporcelain common
> +git-tag                                 mainporcelain           history
>  git-unpack-file                         plumbinginterrogators
>  git-unpack-objects                      plumbingmanipulators
>  git-update-index                        plumbingmanipulators
> --
> 2.4.0

Re: [PATCH v5 2/6] help.c: output the typical Git workflow

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> 'git help' shows common commands in alphabetical order:
>
> The most commonly used git commands are:
>    add        Add file contents to the index
>    bisect     Find by binary search the change that introduced a bug
>    branch     List, create, or delete branches
>    checkout   Checkout a branch or paths to the working tree
>    clone      Clone a repository into a new directory
>    commit     Record changes to the repository
>    [...]
>
> without any indication of how commands relate to high-level
> concepts or each other. Revise the output to explain their relationship
> with the typical Git workflow:
>
> The typical Git workflow includes:
>
>    * start a working area (see also: git help tutorial):
>       clone      Clone a repository into a new directory
>       init       Create an empty Git repository or reinitialize [...]

In practice, I find the indented bulleted header items somewhat
unsightly. More importantly, indenting them wastes precious horizontal
screen real-estate (for those of who use 80-column terminals). Since
the headers are already distinguished by being bulleted, you could
easily drop the indentation; and then reduce the indentation of the
commands themselves.

>    * work on the current change (see also: git help everyday):
>       add        Add file contents to the index
>       reset      Reset current HEAD to the specified state
>
>    * examine the history and state (see also: git help revisions):
>       log        Show commit logs
>       status     Show the working tree status
>
>    [...]
>
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/help.c b/help.c
> index 2072a87..1df205f 100644
> --- a/help.c
> +++ b/help.c
> @@ -218,6 +218,18 @@ void list_commands(unsigned int colopts,
>         }
>  }
>
> +int cmd_group_cmp(const void *elem1, const void *elem2)
> +{
> +       const struct cmdname_help *e1 = elem1;
> +       const struct cmdname_help *e2 = elem2;
> +
> +       if (e1->group < e2->group)
> +               return -1;
> +       if (e1->group > e2->group)
> +               return 1;
> +       return strcmp(e1->name, e2->name);
> +}
> +
>  void list_common_cmds_help(void)
>  {
>         int i, longest = 0;
> @@ -227,9 +239,18 @@ void list_common_cmds_help(void)
>                         longest = strlen(common_cmds[i].name);
>         }
>
> -       puts(_("The most commonly used git commands are:"));
> +       qsort(common_cmds, ARRAY_SIZE(common_cmds),
> +               sizeof(common_cmds[0]), cmd_group_cmp);
> +
> +       puts(_("The typical Git workflow includes:"));
> +
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> -               printf("   %s   ", common_cmds[i].name);
> +               if (common_cmds[i].group != current_grp) {
> +                       printf("\n   * %s:\n", _(common_cmd_groups[common_cmds[i].group]));
> +                       current_grp = common_cmds[i].group;
> +               }
> +
> +               printf("      %s   ", common_cmds[i].name);
>                 mput_char(' ', longest - strlen(common_cmds[i].name));
>                 puts(_(common_cmds[i].help));
>         }
> --
> 2.4.0

Re: [PATCH v5 4/6] Makefile: update to new command-list.txt format

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> * In target common-cmds.h:
>   The AWK script 'generate-cmdlist.awk' replaces 'generate-cmdlist.sh'
>
> * In target check-docs:
>   command-list.txt now contains common commands group in
>   the header [common]. sed ignore all lines in command-list.txt
>   until the [commands] list to correctly checks for missing
>   documentation on Git commands.
>
> For the target common-cmds.h part:
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>

The Makefile modification from my generate-cmdlist patch[1] is part of
the overall logical change of that patch. Its relation to the Makefile
changes in this patch is weak at best, or entirely non-existent.
Consequently, it should not be mixed with them. See my reply[2] to the
v5 cover letter for more information.

More below.

[1]: http://article.gmane.org/gmane.comp.version-control.git/268598
[2]: http://article.gmane.org/gmane.comp.version-control.git/268756

> For the target check-docs part:
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/Makefile b/Makefile
> index 5f3987f..9f333e9 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X
>         ln -s $< $@ 2>/dev/null || \
>         cp $< $@
>
> -common-cmds.h: ./generate-cmdlist.sh command-list.txt
> +common-cmds.h: generate-cmdlist.awk command-list.txt
>
>  common-cmds.h: $(wildcard Documentation/git-*.txt)
> -       $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
> +       $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@
>
>  SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
>         $(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
> @@ -2447,7 +2447,7 @@ check-docs::
>                 esac ; \
>                 test -f "Documentation/$$v.txt" || \
>                 echo "no doc: $$v"; \
> -               sed -e '/^#/d' command-list.txt | \
> +               sed -e '1,/^\[commands\]/d' <command-list.txt | \

I'm not convinced that it's a good idea to drop comment-line
processing from this sed invocation. Even though the current
command-list.txt may not have any comments following the [commands]
header, there is no guarantee that someone won't some day add some
comments following the header.

sed accepts multiple -e arguments, so retaining comment-line
processing does not make the extraction any more expensive. For
instance:

    sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \

>                 grep -q "^$$v[  ]" || \
>                 case "$$v" in \
>                 git) ;; \
> @@ -2455,7 +2455,7 @@ check-docs::
>                 esac ; \
>         done; \
>         ( \
> -               sed -e '/^#/d' \
> +               sed -e '1,/^\[commands\]/d' \

Ditto. It would be more robust to retain comment-line processing.

>                     -e 's/[     ].*//' \
>                     -e 's/^/listed /' command-list.txt; \
>                 $(MAKE) -C Documentation print-man1 | \
> --
> 2.4.0

Re: [PATCH v5 5/6] new-command.txt: mention the common command groups

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> In the 6. step, add information about the common group commands
> found in command-list.txt.

I don't feel too strongly about it, but as this is such a minor
change, and as it is directly related to the addition of the [common]
second in command-list.txt, it also would make sense just to fold this
change into the patch which introduces [common] (that is, v5 patch
3/6).

> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
> index d7de5a3..e7b0cc2 100644
> --- a/Documentation/howto/new-command.txt
> +++ b/Documentation/howto/new-command.txt
> @@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
>  that categorizes commands by type, so they can be listed in appropriate
>  subsections in the documentation's summary command list.  Add an entry
>  for yours.  To understand the categories, look at git-commands.txt
> -in the main directory.
> +in the main directory. If the new command is part of the typical Git
> +workflow and you believe it's common enough to be mentioned in
> +'git help', map this command to a common group in the column [common]
>
>  7. Give the maintainer one paragraph to include in the RelNotes file
>  to describe the new feature; a good place to do so is in the cover
> --
> 2.4.0

Re: [PATCH v5 6/6] cmd-list.perl: ignore all lines until [commands]

[Eric Sunshine]

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> command-list.txt contains a [common] block that should be ignored
> by the Documentation checker cmd-list.perl.
>
> Filter out this block before the actual processing of the command list.
>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
> index 04f9977..d581378 100755
> --- a/Documentation/cmd-list.perl
> +++ b/Documentation/cmd-list.perl
> @@ -38,8 +38,14 @@ sub format_one {
>         }
>  }
>
> +my @filtered = ();
> +while (<>)
> +{

Style: while (<>) {

> +       push (@filtered, $_) unless 1../^\[commands\]/;
> +}

Why collect the lines into @filtered when you could instead merely
skip the unwanted ones outright?

    while (<>) {
        last if /^\[commands\]/;
    }

And, then you don't need to touch the following 'for' loop at all.

>  my %cmds = ();
> -for (sort <>) {
> +for (sort @filtered) {
>         next if /^#/;
>
>         chomp;
> --
> 2.4.0