Subject: [PATCH v3 0/4] git help: group common commands by themes

From: Sébastien Guimmara <[email-masked]>
Date: Sun, 03 May 2015 02:19:28 +0200

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.