Skip to contentSkip to conversation

git help: group common commands by theme

PATCH Superseded Sébastien Guimmara 1 participant 3 messages Jun 15, 2016

v1 of 11 Superseded Latest is v11 →

lore
Share & tools
lore

Sébastien Guimmara

author
#0 lore raw

cover git help: group common commands by theme

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 protected]>
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

command-list.txt +21 -21
index f1eae08..b0730a2 100644
@@ -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
author
#1 lore raw

(My mistake, the patch was in 3 parts, not 4)

Author: Sébastien Guimmara <[email protected]>
Date:   Fri May 1 16:25:53 2015 +0200

generate-cmdlist.sh - Add command group information for common commands

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.

generate-cmdlist.sh +6 -3
index 9a4c9b9..818b2f3 100755
@@ -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
Quoted 159 lines · Sébastien Guimmara

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 protected]>
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

command-list.txt +21 -21
index f1eae08..b0730a2 100644
@@ -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
author
#2 lore raw
In reply to Sébastien Guimmara
Author: Sébastien Guimmara <[email protected]>
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
    [...]
help.c +21 -0
index 2072a87..2169a59 100644
@@ -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

Quoted 168 lines · Sébastien Guimmara

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 protected]>
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

command-list.txt +21 -21
index f1eae08..b0730a2 100644
@@ -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