Scott Chacon <schacon@xxxxxxxxx> writes:
> 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@xxxxxxxxx>
---
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 "
+};"
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html