[PATCH v11 0/5] group common commands by theme

[PATCH v11 0/5] group common commands by theme

[Sébastien Guimmara]

Just a minor change, the modification of new-command.txt was squashed to 
2/5 instead of 1/5.

Eric Sunshine (2):
  command-list: prepare machinery for upcoming "common groups" section
  generate-cmdlist: parse common group commands

Sébastien Guimmara (3):
  command-list.txt: add the common groups block
  command-list.txt: drop the "common" tag
  help: respect new common command grouping

 Documentation/cmd-list.perl         |  4 +++
 Documentation/howto/new-command.txt |  4 ++-
 Makefile                            |  9 ++++---
 command-list.txt                    | 53 ++++++++++++++++++++++---------------
 generate-cmdlist.perl               | 50 ++++++++++++++++++++++++++++++++++
 generate-cmdlist.sh                 | 23 ----------------
 help.c                              | 24 ++++++++++++++++-
 7 files changed, 117 insertions(+), 50 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

-- 
2.4.0.GIT

[PATCH v11 1/5] command-list: prepare machinery for upcoming "common groups" section

[Sébastien Guimmara]

From: Eric Sunshine <sunshine@sunshineco.com>

The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 Documentation/cmd-list.perl | 4 ++++
 Makefile                    | 5 +++--
 command-list.txt            | 2 +-
 3 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 04f9977..5aa73cf 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -38,6 +38,10 @@ sub format_one {
 	}
 }
 
+while (<>) {
+	last if /^### command list/;
+}
+
 my %cmds = ();
 for (sort <>) {
 	next if /^#/;
diff --git a/Makefile b/Makefile
index 323c401..655740d 100644
--- a/Makefile
+++ b/Makefile
@@ -2455,7 +2455,7 @@ check-docs::
 		esac ; \
 		test -f "Documentation/$$v.txt" || \
 		echo "no doc: $$v"; \
-		sed -e '/^#/d' command-list.txt | \
+		sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \
 		grep -q "^$$v[ 	]" || \
 		case "$$v" in \
 		git) ;; \
@@ -2463,7 +2463,8 @@ check-docs::
 		esac ; \
 	done; \
 	( \
-		sed -e '/^#/d' \
+		sed -e '1,/^### command list/d' \
+		    -e '/^#/d' \
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' command-list.txt; \
 		$(MAKE) -C Documentation print-man1 | \
diff --git a/command-list.txt b/command-list.txt
index 54d8d21..181a9c2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,4 +1,4 @@
-# List of known git commands.
+### command list (do not change this line)
 # command name                          category [deprecated] [common]
 git-add                                 mainporcelain common
 git-am                                  mainporcelain
-- 
2.4.0.GIT

[PATCH v11 2/5] command-list.txt: add the common groups block

[Sébastien Guimmara]

The ultimate goal is for "git help" to display common commands in
groups rather than alphabetically. As a first step, define the
groups in a new block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

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

storing information about common commands group, then map each common
command to a group:

    git-add          mainporcelain        common worktree

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
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>
---
 Documentation/howto/new-command.txt |  4 ++-
 command-list.txt                    | 51 ++++++++++++++++++++++---------------
 2 files changed, 34 insertions(+), 21 deletions(-)

diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index d7de5a3..6d772bd 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 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
diff --git a/command-list.txt b/command-list.txt
index 181a9c2..32ddab3 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,3 +1,14 @@
+# common commands are grouped by themes
+# these groups are output by 'git help' in the order declared here.
+# map each common command in the command list to one of these groups.
+### common groups (do not change this line)
+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 common history
+remote       collaborate (see also: git help workflows)
+
+# List of known git commands.
 ### command list (do not change this line)
 # command name                          category [deprecated] [common]
 git-add                                 mainporcelain common
@@ -6,24 +17,24 @@ git-annotate                            ancillaryinterrogators
 git-apply                               plumbingmanipulators
 git-archimport                          foreignscminterface
 git-archive                             mainporcelain
-git-bisect                              mainporcelain common
+git-bisect                              mainporcelain           common info
 git-blame                               ancillaryinterrogators
-git-branch                              mainporcelain common
+git-branch                              mainporcelain           common 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           common 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           common init
 git-column                              purehelpers
-git-commit                              mainporcelain common
+git-commit                              mainporcelain           common history
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
@@ -35,14 +46,14 @@ git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
 git-daemon                              synchingrepositories
 git-describe                            mainporcelain
-git-diff                                mainporcelain common
+git-diff                                mainporcelain           common 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           common remote
 git-fetch-pack                          synchingrepositories
 git-filter-branch                       ancillarymanipulators
 git-fmt-merge-msg                       purehelpers
@@ -51,7 +62,7 @@ git-format-patch                        mainporcelain
 git-fsck                                ancillaryinterrogators
 git-gc                                  mainporcelain
 git-get-tar-commit-id                   ancillaryinterrogators
-git-grep                                mainporcelain common
+git-grep                                mainporcelain           common info
 git-gui                                 mainporcelain
 git-hash-object                         plumbingmanipulators
 git-help                                ancillaryinterrogators
@@ -60,17 +71,17 @@ git-http-fetch                          synchelpers
 git-http-push                           synchelpers
 git-imap-send                           foreignscminterface
 git-index-pack                          plumbingmanipulators
-git-init                                mainporcelain common
+git-init                                mainporcelain           common init
 git-instaweb                            ancillaryinterrogators
 git-interpret-trailers                  purehelpers
 gitk                                    mainporcelain
-git-log                                 mainporcelain common
+git-log                                 mainporcelain           common 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           common history
 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
 git-merge-index                         plumbingmanipulators
@@ -79,7 +90,7 @@ git-mergetool                           ancillarymanipulators
 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators
-git-mv                                  mainporcelain common
+git-mv                                  mainporcelain           common worktree
 git-name-rev                            plumbinginterrogators
 git-notes                               mainporcelain
 git-p4                                  foreignscminterface
@@ -90,11 +101,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           common remote
+git-push                                mainporcelain           common remote
 git-quiltimport                         foreignscminterface
 git-read-tree                           plumbingmanipulators
-git-rebase                              mainporcelain common
+git-rebase                              mainporcelain           common history
 git-receive-pack                        synchelpers
 git-reflog                              ancillarymanipulators
 git-relink                              ancillarymanipulators
@@ -103,28 +114,28 @@ git-repack                              ancillarymanipulators
 git-replace                             ancillarymanipulators
 git-request-pull                        foreignscminterface
 git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain common
+git-reset                               mainporcelain           common worktree
 git-revert                              mainporcelain
 git-rev-list                            plumbinginterrogators
 git-rev-parse                           ancillaryinterrogators
-git-rm                                  mainporcelain common
+git-rm                                  mainporcelain           common worktree
 git-send-email                          foreignscminterface
 git-send-pack                           synchingrepositories
 git-shell                               synchelpers
 git-shortlog                            mainporcelain
-git-show                                mainporcelain common
+git-show                                mainporcelain           common 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           common info
 git-stripspace                          purehelpers
 git-submodule                           mainporcelain
 git-svn                                 foreignscminterface
 git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain common
+git-tag                                 mainporcelain           common history
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
 git-update-index                        plumbingmanipulators
-- 
2.4.0.GIT

[PATCH v11 3/5] generate-cmdlist: parse common group commands

[Sébastien Guimmara]

From: Eric Sunshine <sunshine@sunshineco.com>

Parse the group block to create the array of group descriptions:

static char *common_cmd_groups[] = {
    N_("starting a working area"),
    N_("working on the current change"),
    N_("working with others"),
    N_("examining the history and state"),
    N_("growing, marking and tweaking your history"),
};

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 the group block are emitted to
common_cmds[].

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

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 Makefile              |  4 ++--
 generate-cmdlist.perl | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 generate-cmdlist.sh   | 23 -----------------------
 3 files changed, 52 insertions(+), 25 deletions(-)
 create mode 100755 generate-cmdlist.perl
 delete mode 100755 generate-cmdlist.sh

diff --git a/Makefile b/Makefile
index 655740d..54ec511 100644
--- a/Makefile
+++ b/Makefile
@@ -1694,10 +1694,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.perl command-list.txt
 
 common-cmds.h: $(wildcard Documentation/git-*.txt)
-	$(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@
+	$(QUIET_GEN)$(PERL_PATH) generate-cmdlist.perl command-list.txt > $@+ && mv $@+ $@
 
 SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\
 	$(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\
diff --git a/generate-cmdlist.perl b/generate-cmdlist.perl
new file mode 100755
index 0000000..31516e3
--- /dev/null
+++ b/generate-cmdlist.perl
@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+
+print <<"EOT";
+/* Automatically generated by $0 */
+
+struct cmdname_help {
+	char name[16];
+	char help[80];
+	unsigned char group;
+};
+
+static char *common_cmd_groups[] = {
+EOT
+
+my $n = 0;
+my %grp;
+while (<>) {
+	last if /^### command list/;
+	next if (1../^### common groups/) || /^#/ || /^\s*$/;
+	chop;
+	my ($k, $v) = split ' ', $_, 2;
+	$grp{$k} = $n++;
+	print "\tN_(\"$v\"),\n";
+}
+
+print "};\n\nstatic struct cmdname_help common_cmds[] = {\n";
+
+while (<>) {
+	next if /^#/ || /^\s*$/;
+	my @tags = split;
+	my $cmd = shift @tags;
+	for my $t (@tags) {
+		if (exists $grp{$t}) {
+			my $s;
+			open my $f, '<', "Documentation/$cmd.txt" or die;
+			while (<$f>) {
+				($s) = /^$cmd - (.+)$/;
+				last if $s;
+			}
+			close $f;
+			$cmd =~ s/^git-//;
+			print "\t{\"$cmd\", N_(\"$s\"), $grp{$t}},\n";
+			last;
+		}
+	}
+}
+
+print "};\n";
diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
deleted file mode 100755
index 9a4c9b9..0000000
--- a/generate-cmdlist.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/sh
-
-echo "/* Automatically generated by $0 */
-struct cmdname_help {
-    char name[16];
-    char help[80];
-};
-
-static struct cmdname_help common_cmds[] = {"
-
-sed -n -e 's/^git-\([^ 	]*\)[ 	].* common.*/\1/p' command-list.txt |
-sort |
-while read cmd
-do
-     sed -n '
-     /^NAME/,/git-'"$cmd"'/H
-     ${
-	    x
-	    s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
-	    p
-     }' "Documentation/git-$cmd.txt"
-done
-echo "};"
-- 
2.4.0.GIT

[PATCH v11 4/5] command-list.txt: drop the "common" tag

[Sébastien Guimmara]

command-list.sh, retired in the previous patch, was the only
consumer of the "common" tag, so drop this now-unnecessary
attribute.

before:
    git-add          mainporcelain        common worktree

after:
    git-add          mainporcelain        worktree

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 command-list.txt | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/command-list.txt b/command-list.txt
index 32ddab3..9a98752 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -11,30 +11,30 @@ remote       collaborate (see also: git help workflows)
 # List of known git commands.
 ### command list (do not change this line)
 # command name                          category [deprecated] [common]
-git-add                                 mainporcelain common
+git-add                                 mainporcelain           worktree
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators
 git-apply                               plumbingmanipulators
 git-archimport                          foreignscminterface
 git-archive                             mainporcelain
-git-bisect                              mainporcelain           common info
+git-bisect                              mainporcelain           info
 git-blame                               ancillaryinterrogators
-git-branch                              mainporcelain           common history
+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 history
+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 init
+git-clone                               mainporcelain           init
 git-column                              purehelpers
-git-commit                              mainporcelain           common history
+git-commit                              mainporcelain           history
 git-commit-tree                         plumbingmanipulators
 git-config                              ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
@@ -46,14 +46,14 @@ git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
 git-daemon                              synchingrepositories
 git-describe                            mainporcelain
-git-diff                                mainporcelain           common history
+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 remote
+git-fetch                               mainporcelain           remote
 git-fetch-pack                          synchingrepositories
 git-filter-branch                       ancillarymanipulators
 git-fmt-merge-msg                       purehelpers
@@ -62,7 +62,7 @@ git-format-patch                        mainporcelain
 git-fsck                                ancillaryinterrogators
 git-gc                                  mainporcelain
 git-get-tar-commit-id                   ancillaryinterrogators
-git-grep                                mainporcelain           common info
+git-grep                                mainporcelain           info
 git-gui                                 mainporcelain
 git-hash-object                         plumbingmanipulators
 git-help                                ancillaryinterrogators
@@ -71,17 +71,17 @@ git-http-fetch                          synchelpers
 git-http-push                           synchelpers
 git-imap-send                           foreignscminterface
 git-index-pack                          plumbingmanipulators
-git-init                                mainporcelain           common init
+git-init                                mainporcelain           init
 git-instaweb                            ancillaryinterrogators
 git-interpret-trailers                  purehelpers
 gitk                                    mainporcelain
-git-log                                 mainporcelain           common info
+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 history
+git-merge                               mainporcelain           history
 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
 git-merge-index                         plumbingmanipulators
@@ -90,7 +90,7 @@ git-mergetool                           ancillarymanipulators
 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators
-git-mv                                  mainporcelain           common worktree
+git-mv                                  mainporcelain           worktree
 git-name-rev                            plumbinginterrogators
 git-notes                               mainporcelain
 git-p4                                  foreignscminterface
@@ -101,11 +101,11 @@ git-parse-remote                        synchelpers
 git-patch-id                            purehelpers
 git-prune                               ancillarymanipulators
 git-prune-packed                        plumbingmanipulators
-git-pull                                mainporcelain           common remote
-git-push                                mainporcelain           common remote
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
 git-quiltimport                         foreignscminterface
 git-read-tree                           plumbingmanipulators
-git-rebase                              mainporcelain           common history
+git-rebase                              mainporcelain           history
 git-receive-pack                        synchelpers
 git-reflog                              ancillarymanipulators
 git-relink                              ancillarymanipulators
@@ -114,28 +114,28 @@ git-repack                              ancillarymanipulators
 git-replace                             ancillarymanipulators
 git-request-pull                        foreignscminterface
 git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain           common worktree
+git-reset                               mainporcelain           worktree
 git-revert                              mainporcelain
 git-rev-list                            plumbinginterrogators
 git-rev-parse                           ancillaryinterrogators
-git-rm                                  mainporcelain           common worktree
+git-rm                                  mainporcelain           worktree
 git-send-email                          foreignscminterface
 git-send-pack                           synchingrepositories
 git-shell                               synchelpers
 git-shortlog                            mainporcelain
-git-show                                mainporcelain           common info
+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 info
+git-status                              mainporcelain           info
 git-stripspace                          purehelpers
 git-submodule                           mainporcelain
 git-svn                                 foreignscminterface
 git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain           common history
+git-tag                                 mainporcelain           history
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
 git-update-index                        plumbingmanipulators
-- 
2.4.0.GIT

[PATCH v11 5/5] help: respect new common command grouping

[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 most commonly used git commands are:

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: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
 help.c | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/help.c b/help.c
index 2072a87..8f72051 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
 	}
 }
 
+static 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;
+	int current_grp = -1;
 
 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
 		if (longest < strlen(common_cmds[i].name))
 			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(_("These are common Git commands used in various situations:"));
+
 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
+		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.GIT

Re: [PATCH v11 2/5] command-list.txt: add the common groups block

[Eric Sunshine]

On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> The ultimate goal is for "git help" to display common commands in
> groups rather than alphabetically. As a first step, define the
> groups in a new block, and then assign a group to each
> common command.
>
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> 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 181a9c2..32ddab3 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,3 +1,14 @@
> +# common commands are grouped by themes
> +# these groups are output by 'git help' in the order declared here.
> +# map each common command in the command list to one of these groups.
> +### common groups (do not change this line)
> +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 common history
> +remote       collaborate (see also: git help workflows)
> +
> +# List of known git commands.

This is odd. The above line was removed in 1/5 but then re-appears
here in 2/5. I think the intent is that it should remain removed.

>  ### command list (do not change this line)
>  # command name                          category [deprecated] [common]
>  git-add                                 mainporcelain common

Re: [PATCH v11 5/5] help: respect new common command grouping

[Eric Sunshine]

On Thu, May 21, 2015 at 1:39 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 most commonly used git commands are:

The above line in the commit message does not match the actual output:

    "These are common Git commands used in various situations:"

> 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: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/help.c b/help.c
> index 2072a87..8f72051 100644
> --- a/help.c
> +++ b/help.c
> @@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
>         }
>  }
>
> +static 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;
> +       int current_grp = -1;
>
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>                 if (longest < strlen(common_cmds[i].name))
>                         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(_("These are common Git commands used in various situations:"));
> +
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> +               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.GIT

Re: [PATCH v11 0/5] group common commands by theme

[Eric Sunshine]

On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Just a minor change, the modification of new-command.txt was squashed to
> 2/5 instead of 1/5.

Thanks. With or without addressing the two very minor nits I pointed
out in patches 2/5 and 5/5, this entire patch series (v11) is:

Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>

> Eric Sunshine (2):
>   command-list: prepare machinery for upcoming "common groups" section
>   generate-cmdlist: parse common group commands
>
> Sébastien Guimmara (3):
>   command-list.txt: add the common groups block
>   command-list.txt: drop the "common" tag
>   help: respect new common command grouping
>
>  Documentation/cmd-list.perl         |  4 +++
>  Documentation/howto/new-command.txt |  4 ++-
>  Makefile                            |  9 ++++---
>  command-list.txt                    | 53 ++++++++++++++++++++++---------------
>  generate-cmdlist.perl               | 50 ++++++++++++++++++++++++++++++++++
>  generate-cmdlist.sh                 | 23 ----------------
>  help.c                              | 24 ++++++++++++++++-
>  7 files changed, 117 insertions(+), 50 deletions(-)
>  create mode 100755 generate-cmdlist.perl
>  delete mode 100755 generate-cmdlist.sh

Re: [PATCH v11 5/5] help: respect new common command grouping

[Sébastien Guimmara]

On 05/21/2015 08:04 PM, Eric Sunshine wrote:
> On Thu, May 21, 2015 at 1:39 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 most commonly used git commands are:
>
> The above line in the commit message does not match the actual output:
>
>      "These are common Git commands used in various situations:"
>

Thanks. Will correct this.

>> 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: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> diff --git a/help.c b/help.c
>> index 2072a87..8f72051 100644
>> --- a/help.c
>> +++ b/help.c
>> @@ -218,17 +218,39 @@ void list_commands(unsigned int colopts,
>>          }
>>   }
>>
>> +static 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;
>> +       int current_grp = -1;
>>
>>          for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>>                  if (longest < strlen(common_cmds[i].name))
>>                          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(_("These are common Git commands used in various situations:"));
>> +
>>          for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>> +               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.GIT

Re: [PATCH v11 2/5] command-list.txt: add the common groups block

[Sébastien Guimmara]

On 05/21/2015 08:01 PM, Eric Sunshine wrote:
> On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> The ultimate goal is for "git help" to display common commands in
>> groups rather than alphabetically. As a first step, define the
>> groups in a new block, and then assign a group to each
>> common command.
>>
>> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
>> 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 181a9c2..32ddab3 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,3 +1,14 @@
>> +# common commands are grouped by themes
>> +# these groups are output by 'git help' in the order declared here.
>> +# map each common command in the command list to one of these groups.
>> +### common groups (do not change this line)
>> +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 common history
>> +remote       collaborate (see also: git help workflows)
>> +
>> +# List of known git commands.
>
> This is odd. The above line was removed in 1/5 but then re-appears
> here in 2/5. I think the intent is that it should remain removed.
>
>>   ### command list (do not change this line)
>>   # command name                          category [deprecated] [common]
>>   git-add                                 mainporcelain common

My mistake. This will be corrected in the next version. Thank you for taking time
to review this series.

Sébastien

Re: [PATCH v11 2/5] command-list.txt: add the common groups block

[Eric Sunshine]

[Re-sending this for on-list completeness. It was sent off-list
earlier when I was using an email client capable only of HTML
messages.]

On Mon, May 25, 2015 at 1:31 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/21/2015 08:01 PM, Eric Sunshine wrote:
>> On Thu, May 21, 2015 at 1:39 PM, Sébastien Guimmara
>> <sebastien.guimmara@gmail.com> wrote:
>>>
>>> The ultimate goal is for "git help" to display common commands in
>>> groups rather than alphabetically. As a first step, define the
>>> groups in a new block, and then assign a group to each
>>> common command.
>>>
>>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>>> ---
>>> diff --git a/command-list.txt b/command-list.txt
>>> index 181a9c2..32ddab3 100644
>>> --- a/command-list.txt
>>> +++ b/command-list.txt
>>> @@ -1,3 +1,14 @@
>>> +# common commands are grouped by themes
>>> +# these groups are output by 'git help' in the order declared here.
>>> +# map each common command in the command list to one of these groups.
>>> +### common groups (do not change this line)
>>> +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 common history
>>> +remote       collaborate (see also: git help workflows)
>>> +
>>> +# List of known git commands.
>>
>> This is odd. The above line was removed in 1/5 but then re-appears
>> here in 2/5. I think the intent is that it should remain removed.
>>
>>>   ### command list (do not change this line)
>>>   # command name                          category [deprecated] [common]
>>>   git-add                                 mainporcelain common
>
> My mistake. This will be corrected in the next version. Thank you for taking
> time to review this series.

Junio already made these corrections locally when he picked up the
series. Take a look at his 'pu' branch, and you'll find the series
there with the corrections[1]. Thus, no need to re-send.

[1]: Series currently merged into 'pu' at de905cf0.

Re: [PATCH v11 2/5] command-list.txt: add the common groups block

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>>>> +history      grow, mark and tweak your common history
>>>> +remote       collaborate (see also: git help workflows)
>>>> +
>>>> +# List of known git commands.
>>>
>>> This is odd. The above line was removed in 1/5 but then re-appears
>>> here in 2/5. I think the intent is that it should remain removed.
>>>
>>>>   ### command list (do not change this line)
>>>>   # command name                          category [deprecated] [common]
>>>>   git-add                                 mainporcelain common
>>
>> My mistake. This will be corrected in the next version. Thank you for taking
>> time to review this series.
>
> Junio already made these corrections locally when he picked up the
> series. Take a look at his 'pu' branch, and you'll find the series
> there with the corrections[1]. Thus, no need to re-send.
>
> [1]: Series currently merged into 'pu' at de905cf0.

Yeah, resurrecting "List of known git commands." does look somewhat
strange, but looking at what this step does, especially this bit:

> diff --git a/command-list.txt b/command-list.txt
> index 181a9c2..32ddab3 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,3 +1,14 @@
> +# common commands are grouped by themes
> +# these groups are output by 'git help' in the order declared here.
> +# map each common command in the command list to one of these groups.
> +### common groups (do not change this line)
> +init         start a working area (see also: git help tutorial)
> +worktree     work on the current change (see also: git help everyday)

I do not think we would terribly mind an introductory comment that
applies to the next "###" block before it, e.g.

    # list of known git commands; ordered alphabetically
    # for easy spotting
    ### command list (do not change this line)

For some reason the patch seems to want to spell that comment in all
lowercase, so I just imitated it here.

In any case, if somebody wants to add such a comment there for
symmetry, that can be done as a follow-up patch after dust from
these patches settles, I think.  Let's have these 5 patches graduate
to 'next' without further bikeshedding ;-)