Re: [PATCH v2] Group the default git help message by topic
From: Ævar Arnfjörð Bjarmason <hidden>
Date: 2016-06-15 22:48:57
On Fri, Jun 11, 2010 at 16:03, Scott Chacon [off-list ref] 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.
quoted hunk ↗ jump to hunk
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");
}