git help: promote 'git help -av'
PATCH 1/1 git help: promote 'git help -av'
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
--- git.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
git.c +1 -1
@@ -31,7 +31,7 @@ const char git_usage_string[] = " <command> [<args>]");const char git_more_info_string[] = -N_ ("'git help -a' and 'git help -g' list available subcommands and some\n" +N_ ("'git help -av' and 'git help -g' list available subcommands and some\n" "concept guides. See 'git help <command>' or 'git help <concept>'\n" "to read about a specific subcommand or concept." );
Signature · 1 line
2.19.0.647.gb9a6049235
Quoted 18 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>--- git.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)git.c +0
-0
git.c const char git_usage_string[] = · line 36
Quoted 7 lines
git.c +1
-1@@ -31,7 +31,7 @@ const char git_usage_string[] = " <command> [<args>]");const char git_more_info_string[] = -N_ ("'git help -a' and 'git help -g' list available subcommands and some\n" +N_ ("'git help -av' and 'git help -g' list available subcommands and some\n" "concept guides. See 'git help <command>' or 'git help <concept>'\n" "to read about a specific subcommand or concept." );
A side-effect of this not noted in your commit message is that we'll now invoke the pager, perhaps we should just do:
diff --git a/builtin/help.c b/builtin/help.c
index 8d4f6dd301..1a3b174aaf 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -436,9 +436,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)
parsed_help_format = help_format;
if (show_all) {
+ setup_pager();
git_config(git_help_config, NULL);
if (verbose) {
- setup_pager();
list_all_cmds_help();
return 0;
}
@@ -460,8 +460,10 @@ int cmd_help(int argc, const char **argv, const char *prefix)
return 0;
}
- if (show_guides)
+ if (show_guides) {
+ setup_pager();
list_common_guides_help();
+ }
if (show_all || show_guides) {
printf("%s\n", _(git_more_info_string));Or is there a good reason we shouldn't invoke the pager for e.g. -g when the terminal is too small (per our default less config)?
Another thing I noticed: We don't list -v in the git-help manpage, but since we use OPT_VERBOSE it's supported.
Quoted 61 lines · Ævar Arnfjörð Bjarmason
Quoted 18 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>--- git.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)git.c +0
-0git.c const char git_usage_string[] = · line 36
Quoted 7 lines
git.c +1
-1@@ -31,7 +31,7 @@ const char git_usage_string[] = " <command> [<args>]");const char git_more_info_string[] = -N_ ("'git help -a' and 'git help -g' list available subcommands and some\n" +N_ ("'git help -av' and 'git help -g' list available subcommands and some\n" "concept guides. See 'git help <command>' or 'git help <concept>'\n" "to read about a specific subcommand or concept." );A side-effect of this not noted in your commit message is that we'll now invoke the pager, perhaps we should just do:
diff --git a/builtin/help.c b/builtin/help.c index 8d4f6dd301..1a3b174aaf 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -436,9 +436,9 @@ int cmd_help(int argc, const char **argv, const char *prefix) parsed_help_format = help_format; if (show_all) { + setup_pager(); git_config(git_help_config, NULL); if (verbose) { - setup_pager(); list_all_cmds_help(); return 0; } @@ -460,8 +460,10 @@ int cmd_help(int argc, const char **argv, const char *prefix) return 0; } - if (show_guides) + if (show_guides) { + setup_pager(); list_common_guides_help(); + } if (show_all || show_guides) { printf("%s\n", _(git_more_info_string));
Quoted 2 lines
Or is there a good reason we shouldn't invoke the pager for e.g. -g when the terminal is too small (per our default less config)?
Different pagers may behave differently (and so far "help -a" still fits in my screen). So I don't think we should invoke pager more than necessary.
Signature · 1 line
Duy
Quoted 7 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
I agree that "help -av" is likely to be more friendly. I kind of wonder if it should just be the default for "-a". Do we have any obligation not to change the format of that output?
Assuming we want to keep "-a" and "-av" as-is, your patch seems quite sensible to me.
-Peff
Quoted 6 lines · Jeff King
Quoted 4 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
Quoted 7 lines
Quoted 3 lines
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
I agree that "help -av" is likely to be more friendly. I kind of wonder if it should just be the default for "-a". Do we have any obligation not to change the format of that output?
I agree, though I'd like to clarify what you said before doing so wholeheartedly.
Did you mean that all existing uses of 'git help -a' should instead mean 'git help -av' (i.e., that '-a' after your proposed patch means the same as '-av' in revisions prior to this one?)
If so, I agree. I can't imagine a case where I'd like to provide '-a' and _not_ '-v', so certainly the later should come as a two-for-one deal. Less, more well-intentioned knobs seems a positive trend to me, so I am for this idea.
Thanks,
Taylor
Quoted 15 lines · Taylor Blau
Quoted 6 lines · Jeff King
Quoted 4 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
Quoted 7 lines
Quoted 3 lines
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
I agree that "help -av" is likely to be more friendly. I kind of wonder if it should just be the default for "-a". Do we have any obligation not to change the format of that output?
Quoted 6 lines
I agree, though I'd like to clarify what you said before doing so wholeheartedly.
Did you mean that all existing uses of 'git help -a' should instead mean 'git help -av' (i.e., that '-a' after your proposed patch means the same as '-av' in revisions prior to this one?)
Yes, exactly. I think the vast majority of uses would prefer the categorized list.
The obvious exceptions are:
- you can't remember the name of the command so an alphabetized list is easier for sifting through (without having to re-sift for each category).
- you need a machine-readable version of the list (e.g., for programmable completion). We have "git --list-cmds", but we may need to advertise it better and mark it non-experimental.
I dunno. Maybe it is not worth the effort. Duy's existing patch is an easy one liner. ;)
-Peff
Quoted 3 lines · Jeff King
I agree that "help -av" is likely to be more friendly. I kind of wonder if it should just be the default for "-a". Do we have any obligation not to change the format of that output?
I know that at least older versions of git-completion.bash (I think it was up to 2.17.x series, but do not quote me on that) have parsed "git help -a" output to obtain the list of commands. So such a change would impact those minority users who keep stale completion script in their $HOME/.bashrc without ever update it, thinking it is good enough.
I personally find "help -av" a bit too loud to my taste than plain "-a", and more importantly, I look at "help -a" primarily to check the last section "avaialble from elsewhere on your $PATH" to find things like "clang-format", which I do not think is available anywhere in "help -av", so I do not think "-av" can be promoted as an upward-compatible replacement in its current form.
I probably am not a part of the target audience, though.
Quoted 6 lines · Junio C Hamano
I personally find "help -av" a bit too loud to my taste than plain "-a", and more importantly, I look at "help -a" primarily to check the last section "avaialble from elsewhere on your $PATH" to find things like "clang-format", which I do not think is available anywhere in "help -av", so I do not think "-av" can be promoted as an upward-compatible replacement in its current form.
Yep. I also thought "help -a" was denser but wasn't sure if it actually helps or not. Whenever I look at that block of commands, I end up searching anyway. For my use case, "help -a" could be better served with something like "git apropos".
I think adding another section about external commands in "help -av" would address the "clang-format" stuff. With that, it's probably good enough to completely replace "help -a". It may also be good to list aliases there too in a separate section so you have "all you can type" in one (big) list.
--
Duy
Quoted 13 lines · Duy Nguyen
Quoted 6 lines · Junio C Hamano
I personally find "help -av" a bit too loud to my taste than plain "-a", and more importantly, I look at "help -a" primarily to check the last section "avaialble from elsewhere on your $PATH" to find things like "clang-format", which I do not think is available anywhere in "help -av", so I do not think "-av" can be promoted as an upward-compatible replacement in its current form.
Yep. I also thought "help -a" was denser but wasn't sure if it actually helps or not. Whenever I look at that block of commands, I end up searching anyway. For my use case, "help -a" could be better served with something like "git apropos".
Quoted 5 lines
I think adding another section about external commands in "help -av" would address the "clang-format" stuff. With that, it's probably good enough to completely replace "help -a". It may also be good to list aliases there too in a separate section so you have "all you can type" in one (big) list.
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
-- 8< --
builtin/help.c +3 -10
@@ -38,7 +38,6 @@ static const char *html_path;static int show_all =0 ;static int show_guides =0 ;static int show_config; -static int verbose;static unsigned int colopts;static enum help_format help_format =HELP_FORMAT_NONE ;static int exclude_guides;
@@ -53,7 +52,6 @@ static struct option builtin_help_options[] = { HELP_FORMAT_WEB),OPT_SET_INT ('i' ,"info" , &help_format,N_ ("show info page" ),HELP_FORMAT_INFO ), -OPT__VERBOSE (&verbose,N_ ("print command description" )), OPT_END(), };
@@ -437,14 +435,9 @@ int cmd_help(int argc, const char **argv, const char *prefix)if (show_all) {git_config (git_help_config,NULL ); -if (verbose) { -setup_pager (); -list_all_cmds_help (); -return 0 ; - } -printf (_ ("usage: %s%s" ),_ (git_usage_string),"\n\n" ); -load_command_list ("git-" , &main_cmds, &other_cmds); -list_commands (colopts, &main_cmds, &other_cmds); +setup_pager (); +list_all_cmds_help (); +return 0 ; }if (show_config) {
help.c +46 -43
130 lines not on this page · raw message
help.h +0 -1
@@ -37,7 +37,6 @@ extern void add_cmdname(struct cmdnames *cmds, const char *name, int len);/* Here we require that excludes is a sorted list. */ extern void exclude_cmds (struct cmdnames *cmds,struct cmdnames *excludes);extern int is_in_cmdlist (struct cmdnames *cmds,const char *name); -extern void list_commands (unsigned int colopts,struct cmdnames *main_cmds,struct cmdnames *other_cmds);/* * call this to die(), when it is suspected that the user mistyped a
t/t0012-help.sh +1 -2
@@ -30,8 +30,7 @@ test_expect_success "setup" ' test_expect_success 'basic help commands' ' git help >/dev/null && git help -a >/dev/null && - git help -g >/dev/null && - git help -av >/dev/null + git help -g >/dev/null ' test_expect_success "works for commands and guides by default" '
-- 8< --
--
Duy
Quoted 10 lines · Duy Nguyen
Quoted 5 lines
I think adding another section about external commands in "help -av" would address the "clang-format" stuff. With that, it's probably good enough to completely replace "help -a". It may also be good to list aliases there too in a separate section so you have "all you can type" in one (big) list.
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
Just eyeballing the output, it looks pretty reasonable to me. The lack of explanation for external commands really stands out, but there's not much we can do.
That part of the output is not very compact, and we _could_ put it in columns, but that might be confusing since the rest of the output is one-per-line.
Mentioning aliases seems reasonable to me. The definitions of some of mine are pretty nasty bits of shell, but I guess that people either don't have any ugly aliases, or are comfortable enough with them that they won't be scared away. :)
builtin/help.c static struct option builtin_help_options[] = { · line 56
Quoted 8 lines
-- 8< --
builtin/help.c +0
-1@@ -53,7 +52,6 @@ static struct option builtin_help_options[] = { HELP_FORMAT_WEB),OPT_SET_INT ('i' ,"info" , &help_format,N_ ("show info page" ),HELP_FORMAT_INFO ), -OPT__VERBOSE (&verbose,N_ ("print command description" )), OPT_END(), };
Would we want to continue respecting "-v" as a noop? I admit I did not even know it existed until this thread, but if people have trained themselves to run "git help -av", we should probably continue to give them this output.
-Peff
Quoted 4 lines · Jeff King
Mentioning aliases seems reasonable to me. The definitions of some of mine are pretty nasty bits of shell, but I guess that people either don't have any ugly aliases, or are comfortable enough with them that they won't be scared away. :)
I have one with a very long pretty format for git-log. Well, you wrote your aliases you learn to live with them :) We could certainly cut too long aliased commands to keep the listing pretty, but I don't think we should do that until somebody asks for it.
Quoted 5 lines
Quoted 5 lines
-- 8< --
builtin/help.c +0
-0@@ -53,7 +52,6 @@ static struct option builtin_help_options[] = { HELP_FORMAT_WEB),OPT_SET_INT ('i' ,"info" , &help_format,N_ ("show info page" ), HELP_FORMAT_INFO),
Quoted 8 lines
builtin/help.c static struct option builtin_help_options[] = { · line 56
Quoted 3 lines
builtin/help.c +0
-1-OPT__VERBOSE (&verbose,N_ ("print command description" )), OPT_END(), };Would we want to continue respecting "-v" as a noop? I admit I did not even know it existed until this thread, but if people have trained themselves to run "git help -av", we should probably continue to give them this output.
-v was recently added just for the new "help -a" in May 2018. I think it's ok to get rid of it. Memory muscles probably take a couple more months to kick in.
Signature · 1 line
Duy
Quoted 3 lines · Duy Nguyen
-v was recently added just for the new "help -a" in May 2018. I think it's ok to get rid of it. Memory muscles probably take a couple more months to kick in.
If it is not hurting, keeping it lets people say "--no-verbose" to get a less verbose output to help those who do not like the new default.
Unless you are removing code to show the current "help -a" output, that is.
Quoted 4 lines · Duy Nguyen
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
I didn't apply this (so I didn't try running it), but a quick eyeballing tells me that the listing of external commands in -av output done in this patch seems reasonable.
I do not think removing "-v" and making the current "help -a" output unavailable is a wise idea, though.
Quoted 7 lines · Junio C Hamano
Quoted 4 lines · Duy Nguyen
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
Quoted 6 lines
I didn't apply this (so I didn't try running it), but a quick eyeballing tells me that the listing of external commands in -av output done in this patch seems reasonable.
I do not think removing "-v" and making the current "help -a" output unavailable is a wise idea, though.
I think that your point about having to react in a split-second in order to ^C before we open the manual page for a command is a good one. So, I agree with this.
Thanks,
Taylor
Quoted 12 lines · Taylor Blau
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · Duy Nguyen
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
I didn't apply this (so I didn't try running it), but a quick eyeballing tells me that the listing of external commands in -av output done in this patch seems reasonable.
Quoted 6 lines
Quoted 2 lines
I do not think removing "-v" and making the current "help -a" output unavailable is a wise idea, though.
I think that your point about having to react in a split-second in order to ^C before we open the manual page for a command is a good one. So, I agree with this.
Responding to a wrong thread?
I thought "now I need ^C within a handful of deciseconds if I want only alias?" was not about the change to make "-v" default when "help -a" is asked, but about what to do with "git foo --help" that only gives "foo is aliased to ...".
Quoted 14 lines · Junio C Hamano
Quoted 12 lines · Taylor Blau
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · Duy Nguyen
Here's the patch that adds that external commands and aliases sections. I feel that external commands section is definitely good to have even if we don't replace "help -a". Aliases are more subjective...
I didn't apply this (so I didn't try running it), but a quick eyeballing tells me that the listing of external commands in -av output done in this patch seems reasonable.
Quoted 8 lines
Quoted 6 lines
Quoted 2 lines
I do not think removing "-v" and making the current "help -a" output unavailable is a wise idea, though.
I think that your point about having to react in a split-second in order to ^C before we open the manual page for a command is a good one. So, I agree with this.
Responding to a wrong thread?
Ah, I certainly am. Thanks for catching my mistake :-).
Quoted 4 lines
I thought "now I need ^C within a handful of deciseconds if I want only alias?" was not about the change to make "-v" default when "help -a" is asked, but about what to do with "git foo --help" that only gives "foo is aliased to ...".
Thanks,
Taylor
PATCH v2 1/1 help -a: improve and make --verbose default
In reply to Nguyễn Thái Ngọc DuyWhen you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
"help -av" does not show everything "help -a" shows though. Add external command section in "help -av" for this. While at there, add a section for aliases as well (until now aliases have no UI, just "git config").
---
v2 makes 'help -av' default and the user would need to type 'help -a --no-verbose' to get the old printout back. 'help -av' also has external commands and aliases.
Documentation/git-help.txt | 8 +++--- builtin/help.c | 2 +- help.c | 50 +++++++++++++++++++++++++++++++++++--- t/t0012-help.sh | 4 +-- 4 files changed, 54 insertions(+), 10 deletions(-)
Documentation/git-help.txt +5 -3
@@ -8,7 +8,7 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--verbose]] [-g|--guide] +'git help' [-a|--all [--[no-]verbose]] [-g|--guide] [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] DESCRIPTION
@@ -42,8 +42,10 @@ OPTIONS --all:: Prints all the available commands on the standard output. This option overrides any given command or guide name. - When used with `--verbose` print description for all recognized - commands. + +--verbose:: + When used with `--all` print description for all recognized + commands. This is the default. -c:: --config::
builtin/help.c +1 -1
@@ -38,7 +38,7 @@ static const char *html_path;static int show_all =0 ;static int show_guides =0 ;static int show_config; -static int verbose; +static int verbose =1 ;static unsigned int colopts;static enum help_format help_format =HELP_FORMAT_NONE ;static int exclude_guides;
help.c +46 -4
82 lines not on this page · raw message
t/t0012-help.sh +2 -2
@@ -29,9 +29,9 @@ test_expect_success "setup" ' # to verify test_expect_success 'basic help commands' ' git help >/dev/null && - git help -a >/dev/null && + git help -a --no-verbose >/dev/null && git help -g >/dev/null && - git help -av >/dev/null + git help -a >/dev/null ' test_expect_success "works for commands and guides by default" '
Signature · 1 line
2.19.0.341.g3acb95d729
Re: [PATCH v2] help -a: improve and make --verbose default
Quoted 13 lines · Nguyễn Thái Ngọc Duy
When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.
"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.
"help -av" does not show everything "help -a" shows though. Add external command section in "help -av" for this. While at there, add a section for aliases as well (until now aliases have no UI, just "git config").
Quoted 5 lines
Signed-off-by Nguyễn Thái Ngọc Duy <[email protected]>---
v2 makes 'help -av' default and the user would need to type 'help -a --no-verbose' to get the old printout back. 'help -av' also has external commands and aliases.
Thanks. This looks like what I would have expected based on my recollection of the discussion earlier on v1, so this has my:
Thanks,
Taylor