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

From: Sébastien Guimmara <[email-masked]>
Date: Fri, 01 May 2015 17:12:24 +0200

Author: Sébastien Guimmara <[email-masked]>
Date:   Fri May 1 16:35:41 2015 +0200

     help.c - teach list_common_cmds_help() to group common commands by 
theme

     Until now, the output of list_common_cmds_help() was 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

     [...]

     This is a bit confusing for a beginner.
     This patch changes the output this way:

     [...]

     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

     [...]

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));

Sébastien

On 05/01/2015 04:51 PM, Sébastien Guimmara wrote:
> Hello everyone,
>
> This is my first contribution to an open source project.
>
> I tackled the issue found here:
> https://git.wiki.kernel.org/index.php/SmallProjectsIdeas#improve_.22git_help.22 
>
>
> Namely, format the output of 'git help' so that
> the commands are grouped by theme.
>
> Author: Sébastien Guimmara <[email-masked]>
> Date:   Fri May 1 15:48:57 2015 +0200
>
>     command-list.txt - added command groups to common commands
>
>     groups are in the form: 'x_group',
>     where x is a number used to order (ascending)
>     commands in the displayed help.
>
>     example:  git-add        mainporcelain common-2_worktree
>
> 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
>