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

Scott Chacon [off-list ref] 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 <redacted>
---

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

Hey,

On Sun, Jun 13, 2010 at 11:30 PM, Junio C Hamano [off-list ref] wrote:

I am lazy, and I loathe having to maintain another hardcoded table (let
alone sequence of print_command() calls, like this patch does, yuck).

Sorry, but it seemed to me this would have to be separately maintained
anyhow, plus it doesn't change much.  How often are basic commands
going to be added or removed?  Also, it may not be that pretty, but
it's undeniably clear.

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.

The only issue I would have with this statement is the word 'perfect'.

To disambiguate what we're talking about here, this is the output that
is generated from this new patch:

Some commonly used git commands per developer roles are:
 * Individual Developer (Standalone)
   init          Create an empty git repository or reinitialize an existing one
   show-branch   Show branches and their commits
   log           Show commit logs
   checkout      Checkout a branch or paths to the working tree
   add           Add file contents to the index
   diff          Show changes between commits, commit and working tree, etc
   commit        Record changes to the repository
   reset         Reset current HEAD to the specified state
   merge         Join two or more development histories together
   rebase        Forward-port local commits to the updated upstream head
   tag           Create, list, delete or verify a tag object signed with GPG
 * Individual Developer (Participant)
   clone         Clone a repository into a new directory
   pull          Fetch from and merge with another repository or a local branch
   push          Update remote refs along with associated objects
   format-patch  Prepare patches for e-mail submission
 * Integrator
   am            Apply a series of patches from a mailbox
   revert        Revert an existing commit
 * Repository Administration
   daemon        A really simple server for git repositories
   shell         Restricted login shell for GIT-only SSH access

Though the implementation of the solution is undeniably more elegant,
I have some serious issues with the output.  As you mention next,
'show-branches' is second in the list, which is an issue, but there
are several more.  'am', 'revert', 'daemon', 'shell', 'rebase' - none
of these are appropriate for someone running 'git' and trying to see
where to start.  If we put those aside, all we have is a big list of
commands again which adds almost no value to what we had before.

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 ;-)

That's a fine goal, but I feel like it shouldn't be an "everyday"
document that generates that output, it should be a "beginner"
document or a "how to start using Git" document that isn't really in
the Git source.  I mean, I suppose we could write one with the goal of
using it to generate the help output, but given how much people
disagreed with even the basic grouping of the first patch I sent, I
can't see how we're going to agree on a new help doc.  Perhaps we
should decide on what we would ultimately like the basic help output
to look like and then I can craft a document that would produce it
given this patch and then the list can rip it apart until it's
basically acceptable.

Thoughts?

Scott

Hi,

On Mon, Jun 14, 2010 at 11:31 PM, Scott Chacon [off-list ref] wrote:

[snip]
On Sun, Jun 13, 2010 at 11:30 PM, Junio C Hamano [off-list ref] wrote:
[snip]
To disambiguate what we're talking about here, this is the output that
is generated from this new patch:

Some commonly used git commands per developer roles are:
 * Individual Developer (Standalone)
  init          Create an empty git repository or reinitialize an existing one
  show-branch   Show branches and their commits
  log           Show commit logs
  checkout      Checkout a branch or paths to the working tree
  add           Add file contents to the index
  diff          Show changes between commits, commit and working tree, etc
  commit        Record changes to the repository
  reset         Reset current HEAD to the specified state
  merge         Join two or more development histories together
  rebase        Forward-port local commits to the updated upstream head
  tag           Create, list, delete or verify a tag object signed with GPG
 * Individual Developer (Participant)
  clone         Clone a repository into a new directory
  pull          Fetch from and merge with another repository or a local branch
  push          Update remote refs along with associated objects
  format-patch  Prepare patches for e-mail submission
 * Integrator
  am            Apply a series of patches from a mailbox
  revert        Revert an existing commit
 * Repository Administration
  daemon        A really simple server for git repositories
  shell         Restricted login shell for GIT-only SSH access

On behalf of people too lazy to patch and compile, like myself - thanks.

[snip]
As you mention next,
'show-branches' is second in the list, which is an issue,

Then perhaps we should do something about Documentation/everyday.txt.

but there
are several more.  'am', 'revert', 'daemon', 'shell', 'rebase' - none
of these are appropriate for someone running 'git' and trying to see
where to start.  If we put those aside, all we have is a big list of
commands again which adds almost no value to what we had before.

They are placed under the titles 'Integrator' and 'Repository
Administration', which, I think, is enough to serve as a 'warning!
git-fu ahead' for users who wish to preserve their sanity.

On 'big' - mercurial, which is associated with 'user-friendly', shows
a list of 50 commands.

quoted

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 ;-)

That's a fine goal, but I feel like it shouldn't be an "everyday"
document that generates that output, it should be a "beginner"
document or a "how to start using Git" document that isn't really in
the Git source.

I, for one, don't think "git help" is the place beginners go to when
they first start off - I sure didn't.

The goal of re-grouping and having a short list of commands is nice,
and I see this as useful for people starting to use git, but not for
people learning it.

-- 
Cheers,
Ray Chuan

Hey,

On Mon, Jun 14, 2010 at 9:49 AM, Tay Ray Chuan [off-list ref] wrote:

I, for one, don't think "git help" is the place beginners go to when
they first start off - I sure didn't.

The goal of re-grouping and having a short list of commands is nice,
and I see this as useful for people starting to use git, but not for
people learning it.

I would still argue that 'git daemon' and friends are not what people
starting to use Git need to see.

Scott