Re: [PATCH] Add subcommand "help" to the list of most commonly used subcommands

Teemu Likonen [off-list ref] writes:

  $ git
  usage: [...]

  The most commonly used git commands are:
  [There's no "help" command in the list.]

I think it belongs there,...

While I do agree that a word 'help' should appear in the above output
somewhere, it is a horrible idea to place it in "list of common commands"
for two reasons.

 (1) nobody keeps typing "git help".  The reason we may want to mention
     'help' in this output is not because it is common;

 (2) 'help' _is_ different from other commands.  It is something one may
     want to know the presense of when one is still lost after seeing the
     above quoted output, especially when one is starting to learn.  It
     makes it more difficult to spot it if you bury it as one of the
     commands in a list.

It is reasonable to mention 'help' somewhere in the output, but if we are
going to do this, we should make it stand out.  Perhaps like this.

-- >8 --
$ git
usage: git [--version] ...

The most commonly used git commands are:
   add        Add file contents to the index
   bisect     Find the change that introduced a bug by binary search
   branch     List, create, or delete branches
   ...
   show       Show various types of objects
   status     Show the working tree status
   tag        Create, list, delete or verify a tag object signed with GPG

See 'man git' and 'git help' for more information.
-- 8< --

On 5 jun 2008, at 20:13, Junio C Hamano wrote:

See 'man git' and 'git help' for more information.

I'd like to see something more like

See 'git help COMMAND' for more information on a specific command


- Pieter

El 5/6/2008, a las 20:13, Junio C Hamano escribió:

It is reasonable to mention 'help' somewhere in the output, but if  
we are
going to do this, we should make it stand out.  Perhaps like this.

-- >8 --
$ git
usage: git [--version] ...

The most commonly used git commands are:
  add        Add file contents to the index
  bisect     Find the change that introduced a bug by binary search
  branch     List, create, or delete branches
  ...
  show       Show various types of objects
  status     Show the working tree status
  tag        Create, list, delete or verify a tag object signed with  
GPG

See 'man git' and 'git help' for more information.
-- 8< --

But if the user types "git help" they'll be presented with the exact  
same list of common commands again, at which point they'll probably  
wonder why Git suggested that.

Funnily enough, if they type "git help help" then they'll get the "git- 
help" man page. So, there is no command called "git-help" on the  
system, but from the user's perspective it walks, talks and quacks  
like all the "real" commands, and so they probably consider it to be  
one. Whether or not the "help" subcommand corresponds to a real  
executable or script is really just an implementation detail, I think.

Having said that, I think your suggestion is sound if it were reworded  
as:

   See 'man git' and 'git help [command]' for more information.

Cheers,
Wincent

On Thu, Jun 5, 2008 at 8:42 PM, Wincent Colaiuta [off-list ref] wrote:

But if the user types "git help" they'll be presented with the exact same
list of common commands again, at which point they'll probably wonder why
Git suggested that.

This is exactly what I meant with my earlier comment.

Funnily enough, if they type "git help help" then they'll get the "git-help"
man page. So, there is no command called "git-help" on the system, but from
the user's perspective it walks, talks and quacks like all the "real"
commands, and so they probably consider it to be one. Whether or not the
"help" subcommand corresponds to a real executable or script is really just
an implementation detail, I think.

I fully agree here, it doesn't matter if there is a 'git-help.sh' or
'git-help' executable, as long as from the users POV there is a 'git
help' command should we advertise it.

Having said that, I think your suggestion is sound if it were reworded as:

 See 'man git' and 'git help [command]' for more information.

That would be good, since it does not advertise a git help command,
instead it advertises 'git help command', which clearly -is- a command
(since typing 'git help command' brings up a man page).

-- 
Cheers,

Sverre Rabbelier

Pieter de Bie wrote (2008-06-05 20:38 +0200):

On 5 jun 2008, at 20:13, Junio C Hamano wrote:

quoted

See 'man git' and 'git help' for more information.

I'd like to see something more like

See 'git help COMMAND' for more information on a specific command

Sounds good. Here comes my first _ever_ attempt on C "programming". It
implements (i.e. tries to) what pretty much seems like an agreement on
the list: a separate info line after the command list. If the patch
sucks, well, at least I've had fun trying. And there's no need to ask me
to defend my code; I'm not able to answer. :-)

---snip---
Print info about "git help COMMAND" on git's main usage pages

Git's main usage pages did not show "git help" as a way to get more
information on a specific subcommand. This patch adds an info line after
the list of git commands currently printed by "git", "git help", "git
--help" and "git help --all".

Signed-off-by: Teemu Likonen <redacted>
---
 builtin.h |    1 +
 git.c     |    4 ++++
 help.c    |    2 ++
 3 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/builtin.h b/builtin.h
index 8bda111..b460b2d 100644
--- a/builtin.h
+++ b/builtin.h

@@ -5,6 +5,7 @@
 
 extern const char git_version_string[];
 extern const char git_usage_string[];
+extern const char git_more_info_string[];
 
 extern void list_common_cmds_help(void);
 extern void help_unknown_cmd(const char *cmd);

diff --git a/git.c b/git.c
index 272bf03..15a0e71 100644
--- a/git.c
+++ b/git.c

@@ -6,6 +6,9 @@
 const char git_usage_string[] =
 	"git [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate|--no-pager] [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] [--help] COMMAND [ARGS]";
 
+const char git_more_info_string[] =
+	"See 'git help COMMAND' for more information on a specific command.";
+
 static int handle_options(const char*** argv, int* argc, int* envchanged)
 {
 	int handled = 0;

@@ -427,6 +430,7 @@ int main(int argc, const char **argv)
 		/* The user didn't specify a command; give them help */
 		printf("usage: %s\n\n", git_usage_string);
 		list_common_cmds_help();
+		printf("\n%s\n", git_more_info_string);
 		exit(1);
 	}
 	cmd = argv[0];

diff --git a/help.c b/help.c
index d89d437..8aff94c 100644
--- a/help.c
+++ b/help.c

@@ -649,12 +649,14 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 	if (show_all) {
 		printf("usage: %s\n\n", git_usage_string);
 		list_commands();
+		printf("%s\n", git_more_info_string);
 		return 0;
 	}
 
 	if (!argv[0]) {
 		printf("usage: %s\n\n", git_usage_string);
 		list_common_cmds_help();
+		printf("\n%s\n", git_more_info_string);
 		return 0;
 	}
 

-- 
1.5.6.rc1.16.gc6796