Re: [PATCH v2] Group the default git help message by topic
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jun 14, 2010, 06:30 UTC
- Message-ID
- <7vbpbeazy5.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <AANLkTiloErvcWS1hW80cIV9SiWu_7CBdNSx_iAppcGOd@mail.gmail.com>
Scott Chacon <schacon@gmail.com> writes:
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.
I am lazy, and I loathe having to maintain another hardcoded table (let alone sequence of print_command() calls, like this patch does, yuck).
The two words, "21" and "group", in your proposed commit log message have been nagging me for a while, and I finally figured out why this patch made me feel very disturbed. We already have a perfect source to generate the necessary most commonly used command list with a good grouping hint, but the patch does not make use of it.
So here is a counterproposal.
If readers notice that there are some commands that are out of fashion (e.g. I don't think many people use show-branch anymore in the presence of "log --oneline --graph" and friends) listed in the "git help" output, that is a _good thing_. It will give us an incentive to keep the Everyday document up to date, and with the effort spent for that, "git help" will automatically be kept up to date as well for free ;-)
-- >8 -- Subject: generate "git help" command list using the "Everyday" document
Alphabetized list of "commonly used commands" we currently give is hard to approach. Instead, using the "Everyday" document as a template, group commands by the role the user plays, and present the commands in the order they typically used while playing each role.
Signed-off-by: Junio C Hamano <gitster@pobox.com> ---
Makefile | 2 +- builtin/help.c | 14 ++++++++--- generate-cmdlist.sh | 64 +++++++++++++++++++++++++++++++++++--------------- 3 files changed, 56 insertions(+), 24 deletions(-)
diff --git a/Makefile b/Makefile index 5fa893c..770bea8 100644 --- a/Makefile +++ b/Makefile @@ -1529,7 +1529,7 @@ $(BUILT_INS): git$X common-cmds.h: ./generate-cmdlist.sh command-list.txt -common-cmds.h: $(wildcard Documentation/git-*.txt) +common-cmds.h: $(wildcard Documentation/git-*.txt) Documentation/everyday.txt $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@ define cmd_munge_script diff --git a/builtin/help.c b/builtin/help.c index 3182a2b..546b3a7 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -276,15 +276,21 @@ void list_common_cmds_help(void) int i, longest = 0; for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { + if (!common_cmds[i].help) + continue; if (longest < strlen(common_cmds[i].name)) longest = strlen(common_cmds[i].name); } - puts("The most commonly used git commands are:"); + puts("Some commonly used git commands per developer roles 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); + if (!common_cmds[i].help) { + printf(" * %s\n", common_cmds[i].name); + } else { + printf(" %s ", common_cmds[i].name); + mput_char(' ', longest - strlen(common_cmds[i].name)); + puts(common_cmds[i].help); + } } } diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh index 75c68d9..c6cab26 100755 --- a/generate-cmdlist.sh +++ b/generate-cmdlist.sh @@ -1,24 +1,50 @@ #!/bin/sh -echo "/* Automatically generated by $0 */ -struct cmdname_help +echo "/* Automatically generated by $0 - do not edit */ + +/* + * Special entries without 'help' are section headers. + */ +static struct cmdname_help { - char name[16]; - char help[80]; -}; + const char *name; + const char *help; +} common_cmds[] = {" + +perl -e ' +my %seen = (); +my $section = undef; + +while (<STDIN>) { + chomp; + if (/^\S.*\[\[(.+)\]\]$/) { + print "\n { \"$1\", NULL },\n\n"; + next; + } + while (s/linkgit:git-([-a-z]*)//) { + my $cmd = $1; + next if ($seen{$cmd}++); -static struct cmdname_help common_cmds[] = {" + my $desc = undef; + open I, "<", "Documentation/git-$cmd.txt" + or die "Cannot read Documentation/git-$cmd.txt: $!"; + while (<I>) { + next if (1../^NAME/); + if (/^git-$cmd /) { + s/^git-$cmd - //; + chomp; + $desc = $_; + last; + } + } + close I; + if (!defined $desc) { + die "Cannot read description for $cmd"; + } + print " { \"$cmd\", \"$desc\" },\n"; + } +} +' <Documentation/everyday.txt -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | -sort | -while read cmd -do - sed -n ' - /^NAME/,/git-'"$cmd"'/H - ${ - x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", "\1"},/ - p - }' "Documentation/git-$cmd.txt" -done -echo "};" +echo " +};"