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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jun 11, 2010, 16:46 UTC
Message-ID: <AANLkTilX5HWm3Om349Cbe397B6EKmu_nJijEvqdq38iw@mail.gmail.com>
In-Reply-To: <AANLkTiloErvcWS1hW80cIV9SiWu_7CBdNSx_iAppcGOd@mail.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.

Show 6 quoted lines

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

Show 45 quoted lines

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

Show 27 quoted lines

> +       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");
>  }