From: Junio C Hamano <gitster@pobox•com>
To: Scott Chacon <schacon@gmail•com>
Cc: git list <git@vger•kernel.org>
Subject: Re: [PATCH v2] Group the default git help message by topic
Date: Sun, 13 Jun 2010 23:30:26 -0700 [thread overview]
Message-ID: <7vbpbeazy5.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <AANLkTiloErvcWS1hW80cIV9SiWu_7CBdNSx_iAppcGOd@mail.gmail.com> (Scott Chacon's message of "Fri\, 11 Jun 2010 09\:03\:44 -0700")
Scott Chacon <schacon@gmail•com> 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@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 "
+};"
next prev parent reply other threads:[~2010-06-14 6:30 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-06-11 16:03 [PATCH v2] Group the default git help message by topic Scott Chacon
2010-06-11 16:26 ` Wincent Colaiuta
2010-06-11 22:00 ` A Large Angry SCM
2010-06-11 22:28 ` Ævar Arnfjörð Bjarmason
2010-06-12 16:19 ` Scott Chacon
2010-06-12 16:35 ` Ævar Arnfjörð Bjarmason
2010-06-12 18:44 ` A Large Angry SCM
2010-06-12 16:17 ` Scott Chacon
2010-06-12 17:53 ` Wincent Colaiuta
2010-06-11 16:46 ` Ævar Arnfjörð Bjarmason
2010-06-14 6:30 ` Junio C Hamano [this message]
2010-06-14 15:31 ` Scott Chacon
2010-06-14 16:49 ` Tay Ray Chuan
2010-06-14 16:59 ` Scott Chacon
2010-06-14 17:24 ` Junio C Hamano
2010-06-14 7:48 ` Matthieu Moy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vbpbeazy5.fsf@alter.siamese.dyndns.org \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=schacon@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox