[PATCH v2 1/3] git help: group common commands by theme

[PATCH v2 1/3] git help: group common commands by theme

[Sébastien Guimmara]

This v2 contains exactly the same patches but this time they are 
properly formatted using format-patch.

Group the common commands printed by 'git help' (or 'git' without any 
options) a beginner's friendly themes. To achieve this, the file 
command-list.txt receives an additional information for all 'common' 
commands, in the form of an indexed group suffix.

Group suffixes are in the form: 'x_group', where x is a number used to 
order (ascending) commands in the displayed help:

[...]

git-add                                 mainporcelain common-3_worktree
git-bisect                              mainporcelain common-7_search
git-branch                              mainporcelain common-6_branching
git-checkout                            mainporcelain common-6_branching

[...]

Note: the proposed layout comprises:

1_init
2_info
3_worktree
4_remote
5_history
6_branching
7_search

But they can be easily modified by just changing command-list.txt

command-list.txt is then parsed by generate-cmdlist.sh to generate 
common-cmds.h with the additional group name being a 'group' field in 
the cmdname_help struct:

[...]

   {"add", N_("Add file contents to the index"), "3_worktree"},
   {"bisect", N_("Find by binary search the change that introduced a 
bug"), "7_search"},
   {"branch", N_("List, create, or delete branches"), "6_branching"},
   {"checkout", N_("Checkout a branch or paths to the working tree"), 
"6_branching"},

[...]

Finally, list_common_cmds_help() prints those common commands by groups, 
skipping a line between each group:

[...]

The most commonly used git commands are:
    clone      Clone a repository into a new directory
    init       Create an empty Git repository or reinitialize an 
existing one

    log        Show commit logs
    show       Show various types of objects
    status     Show the working tree status

    add        Add file contents to the index
    mv         Move or rename a file, a directory, or a symlink
    reset      Reset current HEAD to the specified state
    rm         Remove files from the working tree and from the index

    fetch      Download objects and refs from another repository
    pull       Fetch from and integrate with another repository or a 
local branch
    push       Update remote refs along with associated objects

    commit     Record changes to the repository
    diff       Show changes between commits, commit and working tree, etc
    rebase     Forward-port local commits to the updated upstream head
    tag        Create, list, delete or verify a tag object signed with GPG

[...]


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 f1eae08..b0730a2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,29 @@
  # List of known git commands.
  # command name                category [deprecated] [common]
-git-add                                 mainporcelain common
+git-add                                 mainporcelain common-3_worktree
  git-am                                  mainporcelain
  git-annotate                            ancillaryinterrogators
  git-apply                               plumbingmanipulators
  git-archimport                          foreignscminterface
  git-archive                             mainporcelain
-git-bisect                              mainporcelain common
+git-bisect                              mainporcelain common-7_search
  git-blame                               ancillaryinterrogators
-git-branch                              mainporcelain common
+git-branch                              mainporcelain common-6_branching
  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-6_branching
  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-1_init
  git-column                              purehelpers
-git-commit                              mainporcelain common
+git-commit                              mainporcelain common-5_history
  git-commit-tree                         plumbingmanipulators
  git-config                              ancillarymanipulators
  git-count-objects                       ancillaryinterrogators
@@ -35,14 +35,14 @@ git-cvsimport foreignscminterface
  git-cvsserver                           foreignscminterface
  git-daemon                              synchingrepositories
  git-describe                            mainporcelain
-git-diff                                mainporcelain common
+git-diff                                mainporcelain common-5_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-4_remote
  git-fetch-pack                          synchingrepositories
  git-filter-branch                       ancillarymanipulators
  git-fmt-merge-msg                       purehelpers
@@ -51,7 +51,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-7_search
  git-gui                                 mainporcelain
  git-hash-object                         plumbingmanipulators
  git-help                ancillaryinterrogators
@@ -60,17 +60,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-1_init
  git-instaweb                            ancillaryinterrogators
  git-interpret-trailers                  purehelpers
  gitk                                    mainporcelain
-git-log                                 mainporcelain common
+git-log                                 mainporcelain common-2_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-6_branching
  git-merge-base                          plumbinginterrogators
  git-merge-file                          plumbingmanipulators
  git-merge-index                         plumbingmanipulators
@@ -79,7 +79,7 @@ git-mergetool ancillarymanipulators
  git-merge-tree                          ancillaryinterrogators
  git-mktag                               plumbingmanipulators
  git-mktree                              plumbingmanipulators
-git-mv                                  mainporcelain common
+git-mv                                  mainporcelain common-3_worktree
  git-name-rev                            plumbinginterrogators
  git-notes                               mainporcelain
  git-p4                                  foreignscminterface
@@ -90,11 +90,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-4_remote
+git-push                                mainporcelain common-4_remote
  git-quiltimport                         foreignscminterface
  git-read-tree                           plumbingmanipulators
-git-rebase                              mainporcelain common
+git-rebase                              mainporcelain common-5_history
  git-receive-pack                        synchelpers
  git-reflog                              ancillarymanipulators
  git-relink                              ancillarymanipulators
@@ -103,28 +103,28 @@ git-repack ancillarymanipulators
  git-replace                             ancillarymanipulators
  git-request-pull                        foreignscminterface
  git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain common
+git-reset                               mainporcelain common-3_worktree
  git-revert                              mainporcelain
  git-rev-list                            plumbinginterrogators
  git-rev-parse                           ancillaryinterrogators
-git-rm                                  mainporcelain common
+git-rm                                  mainporcelain common-3_worktree
  git-send-email                          foreignscminterface
  git-send-pack                           synchingrepositories
  git-shell                               synchelpers
  git-shortlog                            mainporcelain
-git-show                                mainporcelain common
+git-show                                mainporcelain common-2_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-2_info
  git-stripspace                          purehelpers
  git-submodule                           mainporcelain
  git-svn                                 foreignscminterface
  git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain common
+git-tag                                 mainporcelain common-5_history
  git-unpack-file                         plumbinginterrogators
  git-unpack-objects                      plumbingmanipulators
  git-update-index                        plumbingmanipulators
-- 
2.4.0

[PATCH v2 2/3] git help: group common commands by theme

[Sébastien Guimmara]

Extract the $grp shell variable from command-list.txt (eg: 
'common-3_worktree') and add
this value to the output:

before/after:
{"add", N_("Add file contents to the index")}
{"add", N_("Add file contents to the index"), "3_worktree"}

So that when 'git' is called, we can display common commands grouped by
theme instead of a less useful alphabetical order.

Signed-off by Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
  generate-cmdlist.sh | 9 ++++++---
  1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..818b2f3 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */
  struct cmdname_help {
      char name[16];
      char help[80];
+    char group[20];
  };

  static struct cmdname_help common_cmds[] = {"

-sed -n -e 's/^git-\([^     ]*\)[     ].* common.*/\1/p' command-list.txt |
+sed -n -e 's/^git-\([^     ]*\)[     ].* common-\(.*\)/\1:\2/p' 
command-list.txt |
  sort |
-while read cmd
+while read line
  do
+     cmd=`echo $line | cut -d ':' -f 1`
+     grp=`echo $line | cut -d ':' -f 2`
       sed -n '
       /^NAME/,/git-'"$cmd"'/H
       ${
          x
-        s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
+        s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1"), "'"$grp"'"},/
          p
       }' "Documentation/git-$cmd.txt"
  done
-- 
2.4.0

Re: [PATCH v2 2/3] git help: group common commands by theme

[Luke Diamand]

Hi!

On 2 May 2015 at 00:06, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote:
> Extract the $grp shell variable from command-list.txt (eg:
> 'common-3_worktree') and add
> this value to the output:
>
> before/after:
> {"add", N_("Add file contents to the index")}
> {"add", N_("Add file contents to the index"), "3_worktree"}
>
> So that when 'git' is called, we can display common commands grouped by
> theme instead of a less useful alphabetical order.

Seems sensible to me but I'm no expert :-)

>
> Signed-off by Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
>  generate-cmdlist.sh | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
>
>
> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
> index 9a4c9b9..818b2f3 100755
> --- a/generate-cmdlist.sh
> +++ b/generate-cmdlist.sh
> @@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */
>  struct cmdname_help {
>      char name[16];
>      char help[80];
> +    char group[20];

Is 20 chars long enough? git-p4 shows up as "foreignscminterface"
which is pretty close to that limit.

>  };
>
>  static struct cmdname_help common_cmds[] = {"
>
> -sed -n -e 's/^git-\([^     ]*\)[     ].* common.*/\1/p' command-list.txt |
> +sed -n -e 's/^git-\([^     ]*\)[     ].* common-\(.*\)/\1:\2/p'
> command-list.txt |
>  sort |
> -while read cmd
> +while read line
>  do
> +     cmd=`echo $line | cut -d ':' -f 1`
> +     grp=`echo $line | cut -d ':' -f 2`

Should this use $(...) rather than `...` ?
i.e.
cmd=$(echo $(line | cut -d : -f 1)

(And I don't think you need the quotes around the ':'.

Luke

Re: [PATCH v2 2/3] git help: group common commands by theme

[Sébastien Guimmara]

Hello,

On 05/02/2015 08:32 AM, Luke Diamand wrote:
>> Signed-off by Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>>   generate-cmdlist.sh | 9 ++++++---
>>   1 file changed, 6 insertions(+), 3 deletions(-)
>>
>>
>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
>> index 9a4c9b9..818b2f3 100755
>> --- a/generate-cmdlist.sh
>> +++ b/generate-cmdlist.sh
>> @@ -4,19 +4,22 @@ echo "/* Automatically generated by $0 */
>>   struct cmdname_help {
>>       char name[16];
>>       char help[80];
>> +    char group[20];
> Is 20 chars long enough? git-p4 shows up as "foreignscminterface"
> which is pretty close to that limit.

This 'foreignscminterface' is actually a category in the 2nd column
of the file (like 'porcelain'). It is unrelated to common command
groups (3rd column). Since those group names are not meant to be printed,
I guess it is sufficient to keep them short.
>>   };
>>
>>   static struct cmdname_help common_cmds[] = {"
>>
>> -sed -n -e 's/^git-\([^     ]*\)[     ].* common.*/\1/p' command-list.txt |
>> +sed -n -e 's/^git-\([^     ]*\)[     ].* common-\(.*\)/\1:\2/p'
>> command-list.txt |
>>   sort |
>> -while read cmd
>> +while read line
>>   do
>> +     cmd=`echo $line | cut -d ':' -f 1`
>> +     grp=`echo $line | cut -d ':' -f 2`
> Should this use $(...) rather than `...` ?
> i.e.
> cmd=$(echo $(line | cut -d : -f 1)
>
> (And I don't think you need the quotes around the ':'.
>
> Luke
Indeed, the quotes are unnecessary and $(...) seems to be more
appropriate too.
I'll update the patch.

Thank you,

Sébastien

Re: [PATCH v2 2/3] git help: group common commands by theme

[Andreas Schwab]

Luke Diamand <luke@diamand.org> writes:

>>  };
>>
>>  static struct cmdname_help common_cmds[] = {"
>>
>> -sed -n -e 's/^git-\([^     ]*\)[     ].* common.*/\1/p' command-list.txt |
>> +sed -n -e 's/^git-\([^     ]*\)[     ].* common-\(.*\)/\1:\2/p'
>> command-list.txt |
>>  sort |
>> -while read cmd
>> +while read line
>>  do
>> +     cmd=`echo $line | cut -d ':' -f 1`
>> +     grp=`echo $line | cut -d ':' -f 2`
>
> Should this use $(...) rather than `...` ?
> i.e.
> cmd=$(echo $(line | cut -d : -f 1)

There are various ways to do that without a command substitution, eg:

   cmd=${line%%:*}
   grp=${line#:*}

or:

   IFS=:
   set $line
   cmd=$1 grp=$2

or:

  sort |
  while IFS=: read cmd grp
  do

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH v2 2/3] git help: group common commands by theme

[Sébastien Guimmara]

On 05/02/2015 01:43 PM, Andreas Schwab wrote:
>  or:
>
>    sort |
>    while IFS=: read cmd grp
>    do
>
>  Andreas.

I believe this is the most legible form, the intention is much clearer.

Sébastien

Re: [PATCH v2 2/3] git help: group common commands by theme

[Sébastien Guimmara]

extract the $grp shell variable from command-list.txt (eg: 
'common-3_worktree') and add
this value to the output:

before/after:
{"add", N_("Add file contents to the index")}
{"add", N_("Add file contents to the index"), "3_worktree"}

When 'git help' is called, the displayed commands can be grouped by theme
instead of a less useful alphabetical order.

Signed-off by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
  generate-cmdlist.sh | 7 ++++---
  1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..98f937b 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
  struct cmdname_help {
      char name[16];
      char help[80];
+    char group[20];
  };

  static struct cmdname_help common_cmds[] = {"

-sed -n -e 's/^git-\([^     ]*\)[     ].* common.*/\1/p' command-list.txt |
+sed -n -e 's/^git-\([^     ]*\)[     ].* common-\(.*\)/\1:\2/p' 
command-list.txt |
  sort |
-while read cmd
+while IFS=: read cmd grp
  do
       sed -n '
       /^NAME/,/git-'"$cmd"'/H
       ${
          x
-        s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
+        s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1"), "'"$grp"'"},/
          p
       }' "Documentation/git-$cmd.txt"
  done
-- 
2.4.0

[PATCH v2 3/3] git help: group common commands by theme

[Sébastien Guimmara]

help.c - group common commands by theme

Use qsort to sort the common_cmds array by group name,
then print those common commands, skipping a line between each group.

Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>

---
  help.c | 21 +++++++++++++++++++++
  1 file changed, 21 insertions(+)

diff --git a/help.c b/help.c
index 2072a87..2169a59 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,
      }
  }

+/* sort the command name struct by group name */
+int cmd_group_cmp(const void *elem1, const void *elem2)
+{
+    struct cmdname_help *cmd1 = (struct cmdname_help*) elem1;
+    struct cmdname_help *cmd2 = (struct cmdname_help*) elem2;
+
+    return strcmp(cmd1->group, cmd2->group);
+}
+
  void list_common_cmds_help(void)
  {
      int i, longest = 0;
+    char *current_grp = NULL;

      for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
          if (longest < strlen(common_cmds[i].name))
              longest = strlen(common_cmds[i].name);
      }

+    /* sort common commands by group (i.e, beginner's relevance) */
+    qsort(common_cmds, ARRAY_SIZE(common_cmds),
+        sizeof(struct cmdname_help), cmd_group_cmp);
+
      puts(_("The most commonly used git commands are:"));
      for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
+
+        /* skip a line each time we encounter a new command group */
+        if (current_grp != NULL && strcmp(common_cmds[i].group, 
current_grp))
+            printf("\n");
+
+        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 v3 0/4] git help: group common commands by themes

[Sébastien Guimmara]

Group the common commands printed by 'git help' (or 'git' without any
options) into beginner friendly themes. To achieve this, the file
command-list.txt receives an additional information for all 'common'
commands, in the form of an indexed group suffix.

Group suffixes are in the form: 'x_group', where x is a number used to
order (ascending) commands in the displayed help:

[...]

git-add                                 mainporcelain common-3_worktree
git-bisect                              mainporcelain common-7_search
git-branch                              mainporcelain common-6_branching
git-checkout                            mainporcelain common-6_branching

[...]

Note: the proposed layout comprises:

1_init
2_info
3_worktree
4_remote
5_history
6_branching
7_search

They can be easily modified by just changing command-list.txt

command-list.txt is then parsed by generate-cmdlist.sh to generate
common-cmds.h with the additional group name being a 'group' field in
the cmdname_help struct:

[...]

    {"add", N_("Add file contents to the index"), "3_worktree"},
    {"bisect", N_("Find by binary search the change that introduced a
bug"), "7_search"},
    {"branch", N_("List, create, or delete branches"), "6_branching"},
    {"checkout", N_("Checkout a branch or paths to the working tree"),
"6_branching"},

[...]

Finally, list_common_cmds_help() prints those common commands by groups,
skipping a line between each group:

[...]

The most commonly used git commands are:
     clone      Clone a repository into a new directory
     init       Create an empty Git repository or reinitialize an
existing one

     log        Show commit logs
     show       Show various types of objects
     status     Show the working tree status

     add        Add file contents to the index
     mv         Move or rename a file, a directory, or a symlink
     reset      Reset current HEAD to the specified state
     rm         Remove files from the working tree and from the index

     fetch      Download objects and refs from another repository
     pull       Fetch from and integrate with another repository or a
local branch
     push       Update remote refs along with associated objects

     commit     Record changes to the repository
     diff       Show changes between commits, commit and working tree, etc
     rebase     Forward-port local commits to the updated upstream head
     tag        Create, list, delete or verify a tag object signed with GPG

[...]

The documentation api-builtin.txt is updated to reflect the change.

[PATCH v3 1/4] command-list.txt: group common commands by themes

[Sébastien Guimmara]

Add a group identifier in the form {x}_{name}, where {x} is a digit
identifying the group, and {name} the group name. The digit is used
to sort the common commands by groups instead of the less useful
alphabetical order.

before the patch:
git-add			mainporcelain common

after:
git-add			mainporcelain common-3_worktree

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 f1eae08..b0730a2 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -1,29 +1,29 @@
  # List of known git commands.
  # command name				category [deprecated] [common]
-git-add                                 mainporcelain common
+git-add                                 mainporcelain common-3_worktree
  git-am                                  mainporcelain
  git-annotate                            ancillaryinterrogators
  git-apply                               plumbingmanipulators
  git-archimport                          foreignscminterface
  git-archive                             mainporcelain
-git-bisect                              mainporcelain common
+git-bisect                              mainporcelain common-7_search
  git-blame                               ancillaryinterrogators
-git-branch                              mainporcelain common
+git-branch                              mainporcelain common-6_branching
  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-6_branching
  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-1_init
  git-column                              purehelpers
-git-commit                              mainporcelain common
+git-commit                              mainporcelain common-5_history
  git-commit-tree                         plumbingmanipulators
  git-config                              ancillarymanipulators
  git-count-objects                       ancillaryinterrogators
@@ -35,14 +35,14 @@ git-cvsimport                           foreignscminterface
  git-cvsserver                           foreignscminterface
  git-daemon                              synchingrepositories
  git-describe                            mainporcelain
-git-diff                                mainporcelain common
+git-diff                                mainporcelain common-5_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-4_remote
  git-fetch-pack                          synchingrepositories
  git-filter-branch                       ancillarymanipulators
  git-fmt-merge-msg                       purehelpers
@@ -51,7 +51,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-7_search
  git-gui                                 mainporcelain
  git-hash-object                         plumbingmanipulators
  git-help				ancillaryinterrogators
@@ -60,17 +60,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-1_init
  git-instaweb                            ancillaryinterrogators
  git-interpret-trailers                  purehelpers
  gitk                                    mainporcelain
-git-log                                 mainporcelain common
+git-log                                 mainporcelain common-2_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-6_branching
  git-merge-base                          plumbinginterrogators
  git-merge-file                          plumbingmanipulators
  git-merge-index                         plumbingmanipulators
@@ -79,7 +79,7 @@ git-mergetool                           ancillarymanipulators
  git-merge-tree                          ancillaryinterrogators
  git-mktag                               plumbingmanipulators
  git-mktree                              plumbingmanipulators
-git-mv                                  mainporcelain common
+git-mv                                  mainporcelain common-3_worktree
  git-name-rev                            plumbinginterrogators
  git-notes                               mainporcelain
  git-p4                                  foreignscminterface
@@ -90,11 +90,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-4_remote
+git-push                                mainporcelain common-4_remote
  git-quiltimport                         foreignscminterface
  git-read-tree                           plumbingmanipulators
-git-rebase                              mainporcelain common
+git-rebase                              mainporcelain common-5_history
  git-receive-pack                        synchelpers
  git-reflog                              ancillarymanipulators
  git-relink                              ancillarymanipulators
@@ -103,28 +103,28 @@ git-repack                              ancillarymanipulators
  git-replace                             ancillarymanipulators
  git-request-pull                        foreignscminterface
  git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain common
+git-reset                               mainporcelain common-3_worktree
  git-revert                              mainporcelain
  git-rev-list                            plumbinginterrogators
  git-rev-parse                           ancillaryinterrogators
-git-rm                                  mainporcelain common
+git-rm                                  mainporcelain common-3_worktree
  git-send-email                          foreignscminterface
  git-send-pack                           synchingrepositories
  git-shell                               synchelpers
  git-shortlog                            mainporcelain
-git-show                                mainporcelain common
+git-show                                mainporcelain common-2_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-2_info
  git-stripspace                          purehelpers
  git-submodule                           mainporcelain
  git-svn                                 foreignscminterface
  git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain common
+git-tag                                 mainporcelain common-5_history
  git-unpack-file                         plumbinginterrogators
  git-unpack-objects                      plumbingmanipulators
  git-update-index                        plumbingmanipulators
-- 
2.4.0

[PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Sébastien Guimmara]

Teach generate-cmdlist.sh to parse common command groups
found in command-list.txt in the form

common-3_worktree ('3_worktree' being the group identifier)

Extract the $grp variable, in addition to the previous $cmd,
and inject it as a third field in the cmdname_help struct:

{"add", N_("Add file contents to the index"), "3_worktree"},

So that when 'git' is called, we can display common commands
grouped by theme instead of a less useful alphabetical order.

Reviewed by: Luke Diamand <luke@diamand.org>
Reviewed by: Andreas Schwab <schwab@linux-m68k.org>
Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
  generate-cmdlist.sh | 7 ++++---
  1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 9a4c9b9..98f937b 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
  struct cmdname_help {
      char name[16];
      char help[80];
+    char group[20];
  };
  
  static struct cmdname_help common_cmds[] = {"
  
-sed -n -e 's/^git-\([^ 	]*\)[ 	].* common.*/\1/p' command-list.txt |
+sed -n -e 's/^git-\([^ 	]*\)[ 	].* common-\(.*\)/\1:\2/p' command-list.txt |
  sort |
-while read cmd
+while IFS=: read cmd grp
  do
       sed -n '
       /^NAME/,/git-'"$cmd"'/H
       ${
  	    x
-	    s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
+	    s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1"), "'"$grp"'"},/
  	    p
       }' "Documentation/git-$cmd.txt"
  done
-- 
2.4.0

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Junio C Hamano]

Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:

> Teach generate-cmdlist.sh to parse common command groups
> found in command-list.txt in the form
>
> common-3_worktree ('3_worktree' being the group identifier)
>
> Extract the $grp variable, in addition to the previous $cmd,
> and inject it as a third field in the cmdname_help struct:
>
> {"add", N_("Add file contents to the index"), "3_worktree"},
>
> So that when 'git' is called, we can display common commands
> grouped by theme instead of a less useful alphabetical order.
>
> Reviewed by: Luke Diamand <luke@diamand.org>
> Reviewed by: Andreas Schwab <schwab@linux-m68k.org>

These people may have helped you to polish your earlier round to
come up with this version, but I do not think they should be listed
as reviewed-by (in the sense that they would say "Yes, I read this
version and consider it very good--I endorse the change!") yet.

> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---

>  generate-cmdlist.sh | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
> index 9a4c9b9..98f937b 100755
> --- a/generate-cmdlist.sh
> +++ b/generate-cmdlist.sh
> @@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
>  struct cmdname_help {
>      char name[16];
>      char help[80];
> +    char group[20];

Storing group name in duplicated text for all commands and then
using string comparison at runtime is grossly wasteful, don't you
think, especially when the list is not manually maintained?

command-list.txt is something manually maintained, i.e. the source,
and it makes sense to use easy-to-see strings like "3_worktree"
label there instead of cryptic number, but the whole point of this
script is to pre-process that text into .c file to a form that is
more suited for machine consumption.  I think this script should:

 - read command list once to make the list of groups in a new
   separate array;

 - add the group as an "unsigned char group_number" (as we won't
   have more than 200 groups) field to this struct;

 - read command list again and for each command give the group
   number here.

or something like that.

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Eric Sunshine]

On Sun, May 3, 2015 at 1:55 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:
>
>> Teach generate-cmdlist.sh to parse common command groups
>> found in command-list.txt in the form
>>
>> common-3_worktree ('3_worktree' being the group identifier)
>>
>> Extract the $grp variable, in addition to the previous $cmd,
>> and inject it as a third field in the cmdname_help struct:
>>
>> {"add", N_("Add file contents to the index"), "3_worktree"},
>>
>> So that when 'git' is called, we can display common commands
>> grouped by theme instead of a less useful alphabetical order.
>>
>> Reviewed by: Luke Diamand <luke@diamand.org>
>> Reviewed by: Andreas Schwab <schwab@linux-m68k.org>
>
> These people may have helped you to polish your earlier round to
> come up with this version, but I do not think they should be listed
> as reviewed-by (in the sense that they would say "Yes, I read this
> version and consider it very good--I endorse the change!") yet.

Minor addendum: If you'd like to acknowledge Luke for $(...) and
Andreas for IFS munging, then Helped-by: would be appropriate (and
doesn't require their consent).

More below.

>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
>> index 9a4c9b9..98f937b 100755
>> --- a/generate-cmdlist.sh
>> +++ b/generate-cmdlist.sh
>> @@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
>>  struct cmdname_help {
>>      char name[16];
>>      char help[80];
>> +    char group[20];
>
> Storing group name in duplicated text for all commands and then
> using string comparison at runtime is grossly wasteful, don't you
> think, especially when the list is not manually maintained?
>
> command-list.txt is something manually maintained, i.e. the source,
> and it makes sense to use easy-to-see strings like "3_worktree"
> label there instead of cryptic number, but the whole point of this
> script is to pre-process that text into .c file to a form that is
> more suited for machine consumption.  I think this script should:
>
>  - read command list once to make the list of groups in a new
>    separate array;
>
>  - add the group as an "unsigned char group_number" (as we won't
>    have more than 200 groups) field to this struct;
>
>  - read command list again and for each command give the group
>    number here.
>
> or something like that.

Some additional observations:

The "common-N_group" form seems both redundant and unsightly.
Redundant because you could just as easily pluck out 'common' lines by
searching for "N_group", thus making the "common-" prefix unnecessary.
Unsightly because the mix of "-" and "_" is hard to read. (In general,
"-" is easier to read, thus probably a better choice.)

Thinking out loud, without regard to implementation complexity...

I might expect to see the table of groups to be declared first, in the
order that they should be displayed by "git help". Having the groups
in their own table also allows you to give them human-readable
descriptions. For actual use, you'd tag each command with the bare
group name.

So, something like this, perhaps:

    [groups]
    init    starting a working area
    info    examining history and state
    ...
    branching    branching and merging histories

    [commands]
    git-branch    mainporcelain branching
    ...
    git-clone    mainporcelain init
    ...

This way, the 'N' in "N_group" is unnecessary since presentation order
is implied by the [groups] table, and you don't need the "common-"
prefix anymore since any command having an attribute from the [groups]
table is automatically considered common.

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Sébastien Guimmara]

On 05/03/2015 10:40 PM, Eric Sunshine wrote:
>> These people may have helped you to polish your earlier round to
>> come up with this version, but I do not think they should be listed
>> as reviewed-by (in the sense that they would say "Yes, I read this
>> version and consider it very good--I endorse the change!") yet.
>
> Minor addendum: If you'd like to acknowledge Luke for $(...) and
> Andreas for IFS munging, then Helped-by: would be appropriate (and
> doesn't require their consent).

Thanks for the precision, I got confused with this one.

> So, something like this, perhaps:
>
>      [groups]
>      init    starting a working area
>      info    examining history and state
>      ...
>      branching    branching and merging histories
>
>      [commands]
>      git-branch    mainporcelain branching
>      ...
>      git-clone    mainporcelain init
>      ...
>
> This way, the 'N' in "N_group" is unnecessary since presentation order
> is implied by the [groups] table, and you don't need the "common-"
> prefix anymore since any command having an attribute from the [groups]
> table is automatically considered common.
>

It's a good idea. I'll look into it.

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Eric Sunshine]

On Sun, May 3, 2015 at 4:53 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/03/2015 10:40 PM, Eric Sunshine wrote:
>>> These people may have helped you to polish your earlier round to
>>> come up with this version, but I do not think they should be listed
>>> as reviewed-by (in the sense that they would say "Yes, I read this
>>> version and consider it very good--I endorse the change!") yet.
>>
>> Minor addendum: If you'd like to acknowledge Luke for $(...) and
>> Andreas for IFS munging, then Helped-by: would be appropriate (and
>> doesn't require their consent).
>
> Thanks for the precision, I got confused with this one.

What Junio meant was that Reviewed-by: is something that reviewers
"give" explicitly when they are confident that they understand and
believe your patches are correct. You may incorporate a "given"
Reviewed-by: into a patch when re-rolling if the patch hasn't changed
since the previous round (or has changed in very minor ways which
don't affect the Reviewed-by:). Someone merely reading your patch and
commenting on it (and possibly making suggestions) does not warrant a
Reviewed-by: since comments and suggestions alone don't necessarily
mean that they agree that a patch is acceptable or correct, thus don't
add Reviewed-by: without it being "given".

Helped-by: is for acknowledging someone's assistance.

More below.

>> So, something like this, perhaps:
>>
>>      [groups]
>>      init    starting a working area
>>      info    examining history and state
>>      ...
>>      branching    branching and merging histories
>>
>>      [commands]
>>      git-branch    mainporcelain branching
>>      ...
>>      git-clone    mainporcelain init
>>      ...
>>
>> This way, the 'N' in "N_group" is unnecessary since presentation order
>> is implied by the [groups] table, and you don't need the "common-"
>> prefix anymore since any command having an attribute from the [groups]
>> table is automatically considered common.
>
> It's a good idea. I'll look into it.

'awk' might be helpful to implement this sort of scheme, as well as
Junio's suggestion of emitting only a group number in the generated
table rather than a string. If so, try to stick to POSIX (and avoid
GNU or other extensions).

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Eric Sunshine]

On Sat, May 2, 2015 at 8:22 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Teach generate-cmdlist.sh to parse common command groups
> found in command-list.txt in the form
>
> common-3_worktree ('3_worktree' being the group identifier)
>
> Extract the $grp variable, in addition to the previous $cmd,
> and inject it as a third field in the cmdname_help struct:
>
> {"add", N_("Add file contents to the index"), "3_worktree"},
>
> So that when 'git' is called, we can display common commands
> grouped by theme instead of a less useful alphabetical order.
>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
> index 9a4c9b9..98f937b 100755
> --- a/generate-cmdlist.sh
> +++ b/generate-cmdlist.sh
> @@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
>  struct cmdname_help {
>      char name[16];
>      char help[80];
> +    char group[20];
>  };
>   static struct cmdname_help common_cmds[] = {"
>  -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' [...]
> +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' [...]

Isn't \(.*\) a bit too loose for grabbing $grp? What if someone some
day adds another column to express some other sort of attribute? (Or,
if someone perhaps uses the "deprecated" attribute but places it in
column 3 rather than 2 as documented.) It probably would be better to
tighten this up by grabbing only non-whitespace characters, as is
already done for $cmd.

(In fact, this sed invocation is already broken for "deprecated",
isn't it? According to the command-list.txt header comments,
"deprecated" should be placed before "common", yet the sed invocation
expects "common" to follow the command immediately. Perhaps a
preparatory patch could fix this issue; or just do away with
"deprecated" entirely since it's not used.)

>  sort |
> -while read cmd
> +while IFS=: read cmd grp

Since both $cmd and $grp are simple tokens, neither of which contain
whitespace, this could be handled more simply by just having sed emit
them separated by a space rather than by ':'; in which case your
'while read' loop wouldn't need to muck with IFS at all.

>  do
>       sed -n '
>       /^NAME/,/git-'"$cmd"'/H
>       ${
>             x
> -           s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1")},/
> +           s/.*git-'"$cmd"' - \(.*\)/  {"'"$cmd"'", N_("\1"), "'"$grp"'"},/
>             p
>       }' "Documentation/git-$cmd.txt"
>  done
> --
> 2.4.0

Re: [PATCH v3 2/4] generate-cmdlist.sh: parse common command groups

[Eric Sunshine]

On Sun, May 3, 2015 at 3:18 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Sat, May 2, 2015 at 8:22 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> ---
>> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
>> index 9a4c9b9..98f937b 100755
>> --- a/generate-cmdlist.sh
>> +++ b/generate-cmdlist.sh
>> @@ -4,19 +4,20 @@ echo "/* Automatically generated by $0 */
>>  };
>>   static struct cmdname_help common_cmds[] = {"
>>  -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' [...]
>> +sed -n -e 's/^git-\([^ ]*\)[ ].* common-\(.*\)/\1:\2/p' [...]
>
> Isn't \(.*\) a bit too loose for grabbing $grp? What if someone some
> day adds another column to express some other sort of attribute? (Or,
> if someone perhaps uses the "deprecated" attribute but places it in
> column 3 rather than 2 as documented.) It probably would be better to
> tighten this up by grabbing only non-whitespace characters, as is
> already done for $cmd.
>
> (In fact, this sed invocation is already broken for "deprecated",
> isn't it? According to the command-list.txt header comments,
> "deprecated" should be placed before "common", yet the sed invocation
> expects "common" to follow the command immediately. Perhaps a
> preparatory patch could fix this issue; or just do away with
> "deprecated" entirely since it's not used.)

Ah, I misread the original sed invocation slightly. It's not broken,
so scratch the second paragraph.

(Though, it does expect at least one whitespace character and then one
space before "common", which is a bit odd, but not a problem with the
current content of command-list.txt.)

[PATCH v3 3/4] help.c - group common commands by theme

[Sébastien Guimmara]

When 'git help' is called, a list of common commands are printed:

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
    [...]

Instead of a less than optimal alphabetical order, print those
commands in theme-related groups:

The most commonly used git commands are:
    clone      Clone a repository into a new directory
    init       Create an empty Git repository or reinitialize an existing one

    log        Show commit logs
    show       Show various types of objects
    status     Show the working tree status

    add        Add file contents to the index
    mv         Move or rename a file, a directory, or a symlink
    reset      Reset current HEAD to the specified state
    rm         Remove files from the working tree and from the index
    [...]

To achieve this, qsort the common_cmds array by group name,
then print those common commands, skipping a line between each group.

Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
  help.c | 21 +++++++++++++++++++++
  1 file changed, 21 insertions(+)

diff --git a/help.c b/help.c
index 2072a87..2169a59 100644
--- a/help.c
+++ b/help.c
@@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,
  	}
  }
  
+/* sort the command name struct by group name */
+int cmd_group_cmp(const void *elem1, const void *elem2)
+{
+	struct cmdname_help *cmd1 = (struct cmdname_help*) elem1;
+	struct cmdname_help *cmd2 = (struct cmdname_help*) elem2;
+
+	return strcmp(cmd1->group, cmd2->group);
+}
+
  void list_common_cmds_help(void)
  {
  	int i, longest = 0;
+	char *current_grp = NULL;
  
  	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
  		if (longest < strlen(common_cmds[i].name))
  			longest = strlen(common_cmds[i].name);
  	}
  
+	/* sort common commands by group (i.e, beginner's relevance) */
+	qsort(common_cmds, ARRAY_SIZE(common_cmds),
+		sizeof(struct cmdname_help), cmd_group_cmp);
+
  	puts(_("The most commonly used git commands are:"));
  	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
+
+		/* skip a line each time we encounter a new command group */
+		if (current_grp != NULL && strcmp(common_cmds[i].group, current_grp))
+			printf("\n");
+
+		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 v3 3/4] help.c - group common commands by theme

[Eric Sunshine]

On Sat, May 2, 2015 at 8:23 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> When 'git help' is called, a list of common commands are printed:
>
> 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
>    [...]
>
> Instead of a less than optimal alphabetical order, print those
> commands in theme-related groups:
>
> The most commonly used git commands are:
>    clone      Clone a repository into a new directory
>    init       Create an empty Git repository or reinitialize an existing one
>
>    log        Show commit logs
>    show       Show various types of objects
>    status     Show the working tree status
>
>    add        Add file contents to the index
>    mv         Move or rename a file, a directory, or a symlink
>    reset      Reset current HEAD to the specified state
>    rm         Remove files from the working tree and from the index
>    [...]
>
> To achieve this, qsort the common_cmds array by group name,
> then print those common commands, skipping a line between each group.

Just a minor observation regarding the final paragraph (feel free to ignore):

This level of detail is probably overkill. The overall intent of the
change has already been spelled out nicely via the examples, so
mentioning qsort() is unnecessary since it's a mere implementation
detail; one which a reader can easily discover by reading the patch
proper. Likewise, the example "new output" already shows clearly the
blank line between groups, so there is no need to mention it in prose.

If I was composing the commit message, I'd probably drop the final
paragraph altogether and rephrase something like this:

    'git help' shows common commands in alphabetical order like this:

        <current output>

    without any indication of how commands relate to high-level
    concepts or each other. Revise the output to group commands by
    concept, like this:

        <revised output>

More below.

> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/help.c b/help.c
> index 2072a87..2169a59 100644
> --- a/help.c
> +++ b/help.c
> @@ -218,17 +218,38 @@ void list_commands(unsigned int colopts,
>         }
>  }
>  +/* sort the command name struct by group name */
> +int cmd_group_cmp(const void *elem1, const void *elem2)
> +{
> +       struct cmdname_help *cmd1 = (struct cmdname_help*) elem1;
> +       struct cmdname_help *cmd2 = (struct cmdname_help*) elem2;

As this is C rather than C++, you can drop the cast.

Also, if you were to keep the cast, the prevailing style in git code
is to insert a space before the '*' and to drop the space after the
')'.

> +       return strcmp(cmd1->group, cmd2->group);
> +}
> +
>  void list_common_cmds_help(void)
>  {
>         int i, longest = 0;
> +       char *current_grp = NULL;
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
>                 if (longest < strlen(common_cmds[i].name))
>                         longest = strlen(common_cmds[i].name);
>         }
>  +      /* sort common commands by group (i.e, beginner's relevance) */
> +       qsort(common_cmds, ARRAY_SIZE(common_cmds),
> +               sizeof(struct cmdname_help), cmd_group_cmp);

Slightly more maintenance free would be sizeof(common_cmds[0]) instead
of sizeof(struct cmdname_help).

>         puts(_("The most commonly used git commands are:"));
>         for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> +

Style: Drop this blank line.

> +               /* skip a line each time we encounter a new command group */
> +               if (current_grp != NULL && strcmp(common_cmds[i].group,
> current_grp))
> +                       printf("\n");

This chunk of code is pretty well self-explanatory, so the comment
isn't really adding anything. A comment which merely repeat what the
code itself already says is typically considered distracting rather
than illuminating, thus it could (and probably should) be dropped. The
same observation probably applies to the comment preceding the qsort()
invocation, as well.

Finally, elsewhere in this source file, a blank line is emitted with
the more idiomatic putchar('\n') rather than printf("\n").

> +
> +               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 v3 4/4] api-builtin.txt: explain common command groups

[Sébastien Guimmara]

Update api-builtin.txt to explain how to add the group information
for common commands.

Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
---
  Documentation/technical/api-builtin.txt | 6 +++++-
  1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index 22a39b9..76baba8 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more things to do:
  
  . Write documentation in `Documentation/git-foo.txt`.
  
-. Add an entry for `git-foo` to `command-list.txt`.
+. Add an entry for `git-foo` to `command-list.txt`. If foo is considered
+  a 'common' command, add 'common-x_group' as the third value,
+  where x_group is one of the existing themes:
+
+	git-foo        mainporcelain common-3_worktree
  
  . Add an entry for `/git-foo` to `.gitignore`.
  
-- 
2.4.0

Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups

[Eric Sunshine]

On Sat, May 2, 2015 at 8:24 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> Update api-builtin.txt to explain how to add the group information
> for common commands.
>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/Documentation/technical/api-builtin.txt
> b/Documentation/technical/api-builtin.txt
> index 22a39b9..76baba8 100644
> --- a/Documentation/technical/api-builtin.txt
> +++ b/Documentation/technical/api-builtin.txt
> @@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more
> things to do:
>   . Write documentation in `Documentation/git-foo.txt`.
>  -. Add an entry for `git-foo` to `command-list.txt`.
> +. Add an entry for `git-foo` to `command-list.txt`. If foo is considered
> +  a 'common' command, add 'common-x_group' as the third value,
> +  where x_group is one of the existing themes:
> +
> +       git-foo        mainporcelain common-3_worktree
>   . Add an entry for `/git-foo` to `.gitignore`.

Unfortunately, this change breaks Asciidoc formatting by making the
following ".Add an entry..." item get glued to the new "git-foo..."
example. Fix by inserting a blank line after the "git-foo...". (And
try formatting it yourself to ensure that it is working as expected.)

Finally, all of your patches are whitespace-damaged and fail to apply
to the code-base. Did you paste them into your email client or some
such? If possible, try to send patches via git-send-email since it
does a good job of protecting against whitespace and other types of
damage.

Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups

[Sébastien Guimmara]

On 05/03/2015 10:02 PM, Eric Sunshine wrote:
> On Sat, May 2, 2015 at 8:24 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> Update api-builtin.txt to explain how to add the group information
>> for common commands.
>>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>> diff --git a/Documentation/technical/api-builtin.txt
>> b/Documentation/technical/api-builtin.txt
>> index 22a39b9..76baba8 100644
>> --- a/Documentation/technical/api-builtin.txt
>> +++ b/Documentation/technical/api-builtin.txt
>> @@ -50,7 +50,11 @@ Additionally, if `foo` is a new command, there are 3 more
>> things to do:
>>    . Write documentation in `Documentation/git-foo.txt`.
>>   -. Add an entry for `git-foo` to `command-list.txt`.
>> +. Add an entry for `git-foo` to `command-list.txt`. If foo is considered
>> +  a 'common' command, add 'common-x_group' as the third value,
>> +  where x_group is one of the existing themes:
>> +
>> +       git-foo        mainporcelain common-3_worktree
>>    . Add an entry for `/git-foo` to `.gitignore`.
>
> Unfortunately, this change breaks Asciidoc formatting by making the
> following ".Add an entry..." item get glued to the new "git-foo..."
> example. Fix by inserting a blank line after the "git-foo...". (And
> try formatting it yourself to ensure that it is working as expected.)
>

I'll look into that.

> Finally, all of your patches are whitespace-damaged and fail to apply
> to the code-base. Did you paste them into your email client or some
> such? If possible, try to send patches via git-send-email since it
> does a good job of protecting against whitespace and other types of
> damage.
>

I'm having a hard time configuring send-email through gmail,
so those patches were indeed pasted into plain text. I'll look into
making send-email work.

Thank you for the help,

Sébastien

Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups

[Eric Sunshine]

On Sun, May 3, 2015 at 4:59 PM, Sébastien Guimmara
<sebastien.guimmara@gmail.com> wrote:
> On 05/03/2015 10:02 PM, Eric Sunshine wrote:
>> Finally, all of your patches are whitespace-damaged and fail to apply
>> to the code-base. Did you paste them into your email client or some
>> such? If possible, try to send patches via git-send-email since it
>> does a good job of protecting against whitespace and other types of
>> damage.
>
> I'm having a hard time configuring send-email through gmail,
> so those patches were indeed pasted into plain text. I'll look into
> making send-email work.

The Gmail example in the "git send-email" manual should be sufficient.
However, perhaps other prerequisites are unmet in your case? (For
instance, I had to manually install the Perl Net::SMTP::SSL module on
my machine to get git-send-email working.)

Re: [PATCH v3 4/4] api-builtin.txt: explain common command groups

[Sébastien Guimmara]

On 05/03/2015 11:07 PM, Mikael Magnusson wrote:
> [sendemail]
>      smtpencryption = tls
>      smtpserver = smtp.gmail.com
>      smtpuser = sebastien.guimmara@gmail.com
>      smtpserverport = 587
>      assume8bitEncoding = UTF-8
>
> Should be all that's needed. (in ~/.gitconfig)

Thanks a lot, I was also missing packages. Now it works fine.

Re: [PATCH v2 1/3] git help: group common commands by theme

[Junio C Hamano]

Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:

> Finally, list_common_cmds_help() prints those common commands by
> groups, skipping a line between each group:
>
> [...]
>
> The most commonly used git commands are:
>    clone      Clone a repository into a new directory
>    init       Create an empty Git repository or reinitialize an existing one
>
>    log        Show commit logs
>    show       Show various types of objects
>    status     Show the working tree status
>
>    add        Add file contents to the index
>    mv         Move or rename a file, a directory, or a symlink
>    reset      Reset current HEAD to the specified state
>    rm         Remove files from the working tree and from the index
>
>    fetch      Download objects and refs from another repository
>    pull       Fetch from and integrate with another repository or a local branch
>    push       Update remote refs along with associated objects
>
>    commit     Record changes to the repository
>    diff       Show changes between commits, commit and working tree, etc
>    rebase     Forward-port local commits to the updated upstream head
>    tag        Create, list, delete or verify a tag object signed with GPG

What is the target audience?  Are they expected to be familiar
enough with Git that they can guess what the above grouping is based
on without a group header?

I consider myself experienced enough with Git but cannot explain or
justify the placement of "diff" in the above list myself, for
example.  I'd say

 * starting a working area (clone, init)
 * examining the history and state (log, show, status, diff)
 * working on the current change (add, checkout, reset)
 * growing, marking and tweaking your history (commit, tag, rebase)
 * working with others (fetch, pull, push)

might be a more sensible presentation order (and classification).

Re: [PATCH v2 1/3] git help: group common commands by theme

[Sébastien Guimmara]

On 05/03/2015 05:30 AM, Junio C Hamano wrote:
> What is the target audience?  Are they expected to be familiar
> enough with Git that they can guess what the above grouping is based
> on without a group header?

Since this help is not only displayed on '$ git help' but also on
'$ git', we can assume it's directed at people not familiar with
git and/or the command line usage.

We could then display headers this way:

The most commonly used git commands are:
    * starting a working area:
       clone      Clone a repository into a new directory
       init       Create an empty Git repository or reinitialize an existing one
    
    * examining the history and state:
       diff       Show changes between commits, commit and working tree, etc
       log        Show commit logs
       show       Show various types of objects
       status     Show the working tree status
       bisect     Find by binary search the change that introduced a bug
       grep       Print lines matching a pattern

    * working on the current change:
       add        Add file contents to the index
       checkout   Checkout a branch or paths to the working tree
       reset      Reset current HEAD to the specified state
       rm         Remove files from the working tree and from the index
       mv         Move or rename a file, a directory, or a symlink
    
    * growing, marking and tweaking your history:
       commit     Record changes to the repository
       rebase     Forward-port local commits to the updated upstream head
       tag        Create, list, delete or verify a tag object signed with GPG
    
    * working with others:
       fetch      Download objects and refs from another repository
       pull       Fetch from and integrate with another repository or a local branch
       push       Update remote refs along with associated objects
    
    * branching and merging histories:
       branch     List, create, or delete branches
       merge      Join two or more development histories together

This raises a few questions:

1. Is 'bisect' really a common command (from the target audience standpoint)
2. Does 'Forward-port local commits to the updated upstream head' really help
    to grok the idea of 'rebase' ? There are 3 words in this sentence that
    an unfamiliar git user may not be comfortable with : 'forward-port',
    'upstream' and 'head'. I'm not familiar enough with 'rebase' to think of
    a clearer explanation, but what about:
	
	'Rewrite the history of a branch with commits from another branch'

Re: [PATCH v2 1/3] git help: group common commands by theme

[Sébastien Guimmara]

The formatting in the previous email was a bit off. Here is the proper one.

The most commonly used git commands are:
    * starting a working area:
       clone      Clone a repository into a new directory
       init       Create an empty Git repository or reinitialize an existing one

    * examining the history and state:
       diff       Show changes between commits, commit and working tree, etc
       log        Show commit logs
       show       Show various types of objects
       status     Show the working tree status
       bisect     Find by binary search the change that introduced a bug
       grep       Print lines matching a pattern

    * working on the current change:
       add        Add file contents to the index
       checkout   Checkout a branch or paths to the working tree
       reset      Reset current HEAD to the specified state
       rm         Remove files from the working tree and from the index
       mv         Move or rename a file, a directory, or a symlink

    * growing, marking and tweaking your history:
       commit     Record changes to the repository
       rebase     Forward-port local commits to the updated upstream head
       tag        Create, list, delete or verify a tag object signed with GPG

    * working with others:
       fetch      Download objects and refs from another repository
       pull       Fetch from and integrate with another repository or a local branch
       push       Update remote refs along with associated objects

    * branching and merging histories:
       branch     List, create, or delete branches
       merge      Join two or more development histories together

Re: [PATCH v2 1/3] git help: group common commands by theme

[Junio C Hamano]

Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:

> We could then display headers this way:
>
> The most commonly used git commands are:
>    * starting a working area:
>       clone      Clone a repository into a new directory
>       init       Create an empty Git repository or reinitialize an existing one
>     * examining the history and state:
>       diff       Show changes between commits, commit and working tree, etc
>       log        Show commit logs
>       show       Show various types of objects
>       status     Show the working tree status
>       bisect     Find by binary search the change that introduced a bug
>       grep       Print lines matching a pattern
>
>    * working on the current change:
>       add        Add file contents to the index
>       checkout   Checkout a branch or paths to the working tree
>       reset      Reset current HEAD to the specified state
>       rm         Remove files from the working tree and from the index
>       mv         Move or rename a file, a directory, or a symlink
>     * growing, marking and tweaking your history:
>       commit     Record changes to the repository
>       rebase     Forward-port local commits to the updated upstream head
>       tag        Create, list, delete or verify a tag object signed with GPG
>     * working with others:
>       fetch      Download objects and refs from another repository
>       pull       Fetch from and integrate with another repository or a local branch
>       push       Update remote refs along with associated objects
>     * branching and merging histories:
>       branch     List, create, or delete branches
>       merge      Join two or more development histories together
>
> This raises a few questions:
>
> 1. Is 'bisect' really a common command (from the target audience standpoint)

That is a good question, but so are many other commands.

I think that (1) it is a good idea to list commands in groups, (2)
having group-head is necessary if we list commands in groups, but
(3) because group-heads consume valuable vertical space in the
output, we may have to have fewer commands in the list.

For example, "mv" and "rm" are very questionable things to have in
the "most commonly used" list.  All you need to start with Git is
"add" and "commit -a".

"clone" and "init" are "once per working area for a project you deal
with" kind of thing, and cannot be in the "commonly used and you
benefit from a gentle nudge to read about it more in the manual to
learn Git" category by definition.

"rebase" should be with "merge" and "branch", but I wouldn't have
"branching and merging" as a separate category---they are all part
of "growing and tweaking".  And "branch" itself may be questionable
for those who are starting with Git.

Do we care about the ordering of the items within groups, by the way?

> 2. Does 'Forward-port local commits to the updated upstream head' really help
>    to grok the idea of 'rebase' ? There are 3 words in this sentence that
>    an unfamiliar git user may not be comfortable with...

"Rebuild the history on a branch on top of a new commit", perhaps?

But this brings us back to "what the target audience?" question.

My answer to the question has always been "the list is a gentle
nudge to guide the user to read about it more in the manual to
learn."  The sooner users are guided to graduate from the "not be
comfortable" state, the more productive they will be.

For that to happen, we would need to (1) strongly suggest that the
subcommand is what the user wants to use, and (2) carefully avoid
giving an impression that the user learned everything there is to
know in order to use the command effectively from that single line.

Of course, an argument can be made that the single-line should aim
to teach everything there is to know in order to use the command
effectively, but because I do not think that is feasible I would
aim for the second best, which is why we want to keep the last two
lines about "git help <command> for a specific subcommand".