Re: [PATCH v2] Group the default git help message by topic

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Fri, Jun 11, 2010 at 16:03, Scott Chacon <schacon@gmail.com> wrote:

I like the basic idea behind this patch, i.e. grouping the help
output.

> It's difficult to process 21 commands (which is what is output
> by default for git when no command is given).  They have been
> re-grouped into 4 groups of 5-6 commands each, which is clearer
> and easier for new users to process.  More advanced commands
> such as bisect and rebase have also been removed as this should
> be output for beginners.

"should not"

> Here is the second version of this patch.  Instead of hard-coding
> all the descriptions, I'm just pulling them from the common-cmds.h
> file.

The reason there are 21 is:

    $ grep -c "mainporcelain common" command-list.txt
    21

Perhaps if `git help` is going to be some subset of that aimed at
newbies a new command-list.txt category should be introduced as part
of the patch? E.g. "mainporcelain common newbie"?

As a further suggestion for future improvements, perhaps we should
document *all* commands in the future, or at least those in
mainporcelain and make a full summary available through `git help
--full` or something like that.

As far as I can see with this patch the the description for the
commands you removed in the `cmdname_help common_cmds` struct is now
dead code. If that's the case shouldn't they strings be removed from
there?

These are the commands you removed (I think the commit message should
be changed to explicitly mention this):

    git-bisect                              mainporcelain common
    git-grep                                mainporcelain common
    git-mv                                  mainporcelain common
    git-rebase                              mainporcelain common
    git-rm                                  mainporcelain common

"mv" and "rm" are certainly something a newbie might frequently
used. Why not list it under "Basic commands" along with "add"?

I use "rebase" much more than some of the commands now listed, it's
one of the main distinguishing features of git, so perhaps it should
be under "Branch Commands", if for no other reason than to give users
a peek down the rabbit hole.

>  builtin/help.c |   54 ++++++++++++++++++++++++++++++++++++++++++------------
>  1 files changed, 42 insertions(+), 12 deletions(-)
>
> diff --git a/builtin/help.c b/builtin/help.c
> index 3182a2b..2975b3d 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -269,23 +269,53 @@ static int git_help_config(const char *var,
> const char *value, void *cb)
>        return git_default_config(var, value, cb);
>  }
>
> -static struct cmdnames main_cmds, other_cmds;
> -
> -void list_common_cmds_help(void)
> +void print_command(const char *s)
>  {
> -       int i, longest = 0;
> +       int i = 0;
> +       int longest = 10;
>
>        for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> -               if (longest < strlen(common_cmds[i].name))
> -                       longest = strlen(common_cmds[i].name);
> +               if (!strcmp(s, common_cmds[i].name)) {
> +                       printf("   %s   ", common_cmds[i].name);
> +                       mput_char(' ', longest - strlen(common_cmds[i].name));
> +                       puts(common_cmds[i].help);
> +               }
>        }
> +}
>
> -       puts("The most commonly used git commands are:");
> -       for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
> -               printf("   %s   ", common_cmds[i].name);
> -               mput_char(' ', longest - strlen(common_cmds[i].name));
> -               puts(common_cmds[i].help);
> -       }
> +static struct cmdnames main_cmds, other_cmds;
> +
> +void list_common_cmds_help(void)
> +{
> +       puts("The most commonly used git commands are:\n");
> +
> +       puts("Basic Commands:");

Why capitalize "Commands" when it's not at the beginning of a
sentence? 'bzr help' doesn't do this. And For What It's Worth I Find
It Uncomfortable To Read Text Formatted Like That.

> +       print_command("init");
> +       print_command("clone");
> +       print_command("add");
> +       print_command("status");
> +       print_command("commit");
> +       puts("");
> +
> +       puts("Branch Commands:");
> +       print_command("branch");
> +       print_command("checkout");
> +       print_command("merge");
> +       print_command("tag");
> +       puts("");
> +
> +       puts("History Commands:");
> +       print_command("log");
> +       print_command("diff");
> +       print_command("reset");
> +       print_command("show");
> +       puts("");
> +
> +       puts("Remote Commands:");
> +       print_command("remote");
> +       print_command("fetch");
> +       print_command("pull");
> +       print_command("push");
>  }