Send help text from "git cmd -h" to stdout
v3 cover Send help text from "git cmd -h" to stdout
Jonas Konrad noticed[*] that "git branch -h" started showing the help text to the standard error stream. It turns out that we are fairly inconsistent in our implementation of "git cmd -h". The users of parse-options API will get "If -h is the only option on the command line, give the help text to the standard output" for free, but some commands manually check for the condition and then call the usage_with_options() function, which gives the identical help text to the standard error stream. And "git branch -h" Jonas noticed was one of them.
Older commands written before parse-options API became dominant show the help text by calling the usage() function, which is meant to be used when they fail to parse their command line arguments, which has the same problem. An explicit request for help text "git cmd -h" should be fulfilled by showing the help on the standard output.
This series teachs "git $cmd -h" to send its help text to the standard output stream consistently for built-in commands.
[Reference]
https://lore.kernel.org/git/[email protected]/
Jeff King (1):
t0012: optionally check that "-h" output goes to stdout
Junio C Hamano (5):
parse-options: add show_usage_help_and_exit_if_asked()
builtins: send usage_with_options() help text to standard output
usage: add show_usage_and_exit_if_asked()
builtin: send usage() help text to standard output
builtin: send usage() help text to standard output
builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/check-ref-format.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/credential.c | 3 ++- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/fetch-pack.c | 3 +++ builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/ls-files.c | 4 ++-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/merge.c | 4 ++-- builtin/pack-redundant.c | 3 +-- builtin/rebase.c | 6 +++--- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-file.c | 8 ++++++-- builtin/unpack-objects.c | 2 ++ builtin/update-index.c | 4 ++-- builtin/upload-archive.c | 6 +++--- builtin/var.c | 1 + git-compat-util.h | 2 ++ parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ t/helper/test-simple-ipc.c | 4 ++-- t/t0012-help.sh | 3 ++- t/t7600-merge.sh | 2 +- usage.c | 28 +++++++++++++++++++++++++--- 41 files changed, 123 insertions(+), 64 deletions(-)
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v3 1/6 parse-options: add show_usage_help_and_exit_if_asked()
Many commands call usage_with_options() when they are asked to give the help message, but it incorrectly sends the help text to the standard error stream. When the user asked for it with "git cmd -h", the help message is the primary output from the command, hence we should send it to the standard output stream.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage_with_options(usage, options);
and replaces it with
show_usage_help_and_exit_if_asked(argc, argv, usage, options);
to help correct code paths (there are 40 or so of them).
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
--- parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ 2 files changed, 14 insertions(+)
parse-options.c +10 -0
@@ -1282,6 +1282,16 @@ void NORETURN usage_with_options(const char * const *usagestr,exit (129 ); } +void show_usage_help_and_exit_if_asked (int ac,const char **av, +const char *const *usagestr, +const struct option *opts) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) { +usage_with_options_internal (NULL , usagestr, opts,0 ,0 ); +exit (129 ); + } +} + void NORETURN usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options)
parse-options.h +4 -0
@@ -402,6 +402,10 @@ int parse_options(int argc, const char **argv, const char *prefix, NORETURN void usage_with_options(const char * const *usagestr,const struct option *options); +void show_usage_help_and_exit_if_asked (int ac,const char **av, +const char *const *usage, +const struct option *options); + NORETURN void usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options);
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v3 2/6 t0012: optionally check that "-h" output goes to stdout
In reply to Junio C HamanoFrom: Jeff King <[email protected]>
For most commands, "git foo -h" will send the help output to stdout, as this is what parse-options.c does. But some commands send it to stderr instead. This is usually because they call usage_with_options(), and should be switched to show_usage_help_and_exit_if_asked().
Currently t0012 is permissive and allows either behavior. We'd like it to eventually enforce that help goes to stdout, and teaching it to do so identifies the commands that need to be changed. But during the transition period, we don't want to enforce that for most test runs.
So let's introduce a flag that will let most test runs use the permissive behavior, and people interested in converting commands can run:
GIT_TEST_HELP_MUST_BE_STDOUT=1 ./t0012-help.sh
to see the failures. Eventually (when all builtins have been converted) we'll remove this flag entirely and always check the strict behavior.
--- t/t0012-help.sh | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
t/t0012-help.sh +9 -2
@@ -255,9 +255,16 @@ do ( GIT_CEILING_DIRECTORIES=$(pwd) && export GIT_CEILING_DIRECTORIES && - test_expect_code 129 git -C sub $builtin -h >output 2>&1 + test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - test_grep usage output + if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" + then + test_must_be_empty err && + test_grep usage output + else + test_grep usage output || + test_grep usage err + fi ' done <builtins
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v3 3/6 builtins: send usage_with_options() help text to standard output
In reply to Junio C HamanoUsing the show_usage_help_and_exit_if_asked() helper we introduced earlier, fix callers of usage_with_options() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The test in t7600 for "git merge -h" may want to be retired, as the same is covered by t0012 already. It would be even more true if we later consider changing the exit status from 129 to 0.
--- builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/ls-files.c | 4 ++-- builtin/merge.c | 4 ++-- builtin/rebase.c | 6 +++--- builtin/update-index.c | 4 ++-- t/t7600-merge.sh | 2 +- 13 files changed, 29 insertions(+), 30 deletions(-)
builtin/am.c +1 -2
@@ -2427,8 +2427,7 @@ int cmd_am(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (usage, options); +show_usage_help_and_exit_if_asked (argc, argv, usage, options);git_config (git_default_config,NULL );
builtin/branch.c +2 -2
@@ -784,8 +784,8 @@ int cmd_branch(int argc, filter.kind =FILTER_REFS_BRANCHES ; filter.abbrev =-1 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_branch_usage, options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_branch_usage, options);/* * Try to set sort keys from config. If config does not set any,
builtin/checkout--worker.c +3 -3
@@ -128,9 +128,9 @@ int cmd_checkout__worker(int argc,OPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (checkout_worker_usage, - checkout_worker_options); +show_usage_help_and_exit_if_asked (argc, argv, + checkout_worker_usage, + checkout_worker_options);git_config (git_default_config,NULL ); argc = parse_options(argc, argv, prefix, checkout_worker_options,
builtin/checkout-index.c +3 -3
@@ -250,9 +250,9 @@ int cmd_checkout_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_checkout_index_usage, - builtin_checkout_index_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_checkout_index_usage, + builtin_checkout_index_options);git_config (git_default_config,NULL ); prefix_length = prefix ?strlen (prefix) :0 ;
builtin/commit-tree.c +2 -2
@@ -119,8 +119,8 @@ int cmd_commit_tree(int argc,git_config (git_default_config,NULL ); -if (argc <2 || !strcmp (argv[1 ],"-h" )) -usage_with_options (commit_tree_usage, options); +show_usage_help_and_exit_if_asked (argc, argv, + commit_tree_usage, options); argc =parse_options (argc, argv, prefix, options, commit_tree_usage,0 );
builtin/commit.c +4 -4
@@ -1559,8 +1559,8 @@ struct repository *repo UNUSED) OPT_END(), }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_status_usage, builtin_status_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_status_usage, builtin_status_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
@@ -1736,8 +1736,8 @@ int cmd_commit(int argc,struct strbuf err =STRBUF_INIT ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_commit_usage, builtin_commit_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_commit_usage, builtin_commit_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/fsmonitor--daemon.c +2 -2
@@ -1598,8 +1598,8 @@ int cmd_fsmonitor__daemon(int argc, const char **argv, const char *prefix UNUSEDOPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_fsmonitor__daemon_usage, options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_fsmonitor__daemon_usage, options);die (_ ("fsmonitor--daemon not supported on this platform" )); }
builtin/gc.c +2 -2
@@ -710,8 +710,8 @@ struct repository *repo UNUSED) OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_gc_usage, builtin_gc_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_gc_usage, builtin_gc_options);strvec_pushl (&reflog,"reflog" ,"expire" ,"--all" ,NULL );strvec_pushl (&repack,"repack" ,"-d" ,"-l" ,NULL );
builtin/ls-files.c +2 -2
@@ -644,8 +644,8 @@ int cmd_ls_files(int argc, };int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (ls_files_usage, builtin_ls_files_options); +show_usage_help_and_exit_if_asked (argc, argv, + ls_files_usage, builtin_ls_files_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/merge.c +2 -2
@@ -1300,8 +1300,8 @@ int cmd_merge(int argc,void *branch_to_free;int orig_argc = argc; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_merge_usage, builtin_merge_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_merge_usage, builtin_merge_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/rebase.c +3 -3
@@ -1223,9 +1223,9 @@ int cmd_rebase(int argc, };int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_rebase_usage, - builtin_rebase_options); +show_usage_help_and_exit_if_asked (argc, argv, + builtin_rebase_usage, + builtin_rebase_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/update-index.c +2 -2
@@ -1045,8 +1045,8 @@ int cmd_update_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (update_index_usage, options); +show_usage_help_and_exit_if_asked (argc, argv, + update_index_usage, options);git_config (git_default_config,NULL );
t/t7600-merge.sh +1 -1
@@ -173,7 +173,7 @@ test_expect_success 'merge -h with invalid index' ' cd broken && git init && >.git/index && - test_expect_code 129 git merge -h 2>usage + test_expect_code 129 git merge -h >usage ) && test_grep "[Uu]sage: git merge" broken/usage '
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v3 4/6 usage: add show_usage_and_exit_if_asked()
In reply to Junio C HamanoSome commands call usage() when they are asked to give the help message with "git cmd -h", but this has the same problem as we fixed with callers of usage_with_options() for the same purpose.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage(usage);
and replaces it with
show_usage_and_exit_if_asked(argc, argv, usage);
to help correct these code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
--- git-compat-util.h | 2 ++ usage.c | 28 +++++++++++++++++++++++++--- 2 files changed, 27 insertions(+), 3 deletions(-)
git-compat-util.h +2 -0
@@ -701,6 +701,8 @@ int error_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));void warning (const char *err, ...) __attribute__((format (printf,1 ,2 )));void warning_errno (const char *err, ...) __attribute__((format (printf,1 ,2 ))); +void show_usage_and_exit_if_asked (int ac,const char **av,const char *err); +#ifndef NO_OPENSSL #ifdef APPLE_COMMON_CRYPTO #include "compat/apple-common-crypto.h"
usage.c +25 -3
@@ -8,7 +8,7 @@#include "gettext.h" #include "trace2.h" -static void vreportf (const char *prefix,const char *err,va_list params) +static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
@@ -32,8 +32,14 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +if (fd ==2 ) +fflush (stderr); +write_in_full (fd, msg, p - msg); +} + +static void vreportf (const char *prefix,const char *err,va_list params) +{ +vfdreportf (2 , prefix, err, params); } static NORETURN void usage_builtin(const char *err, va_list params)
@@ -173,6 +179,22 @@ void NORETURN usage(const char *err)usagef ("%s" , err); } +static void show_usage_and_exit_if_asked_helper (const char *err, ...) +{ +va_list params; + +va_start (params, err); +vfdreportf (1 ,_ ("usage: " ), err, params); +va_end (params); +exit (129 ); +} + +void show_usage_and_exit_if_asked (int ac,const char **av,const char *err) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) +show_usage_and_exit_if_asked_helper (err); +} + void NORETURN die(const char *err, ...) {va_list params;
Signature · 1 line
2.48.1-191-gafe818080f
Re: [PATCH v3 4/6] usage: add show_usage_and_exit_if_asked()
Quoted 10 lines · Junio C Hamano
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage(usage);and replaces it with
show_usage_and_exit_if_asked(argc, argv, usage);to help correct these code paths.
I found the name hard to distinguish from the earlier helper, show_usage_help_and_exit_if_asked(). The difference is that one takes only a usage string, and the other takes the usage string along with options. Maybe the other should be:
show_usage_and_exit_if_asked_with_options();
? It just keeps getting longer and longer...
I think the "and_exit" could probably be implied, since showing the usage is always a final thing (just like in usage() and usage_with_options()). So:
show_usage_if_asked(); show_usage_with_options_if_asked();
? I dunno. We are in deep bikeshed territory. I otherwise like what the patch is doing. ;)
Quoted 6 lines
usage.c +1
-1-static void vreportf (const char *prefix,const char *err,va_list params) +static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
usage.c static void vreportf(const char *prefix, const char *err, va_list params) · line 38
Quoted 9 lines
usage.c +4
-2@@ -32,8 +32,14 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +if (fd ==2 ) +fflush (stderr); +write_in_full (fd, msg, p - msg); +}
Gross. :) I think the existing code is conceptually:
write_in_full(fileno(stderr), msg, p - msg);
In which case vfreportf() could just take a FILE*, flush it and then write.
My main motivation is being less ugly, but I think it would also potentially prevent a bug. If there was unflushed data in stdout as we go into vdreportf(), then we'd get an out of order write. That's why the fflush() is there in the first place (it's of course weird that we are using write() in the first place, but IIRC it's for avoiding sheared writes of error messages).
-Peff
Re: [PATCH v3 4/6] usage: add show_usage_and_exit_if_asked()
Quoted 8 lines · Jeff King
Quoted 8 lines
usage.c +1
-1-static void vreportf (const char *prefix,const char *err,va_list params) +static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);@@ -32,8 +32,14 @@ static void vreportf(const char *prefix, const char *err, va_list params) }
Quoted 7 lines
usage.c static void vreportf(const char *prefix, const char *err, va_list params) · line 38
Quoted 7 lines
usage.c +4
-2*(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +if (fd ==2 ) +fflush (stderr); +write_in_full (fd, msg, p - msg); +}
Oh, I meant to mention also: I wondered about the other references to stderr in this function. But we hit those only when we fail to format the error message that was asked for, so continuing to send them to stderr is the right thing (i.e., your patch is right but I wanted to help out other reviewers).
-Peff
Re: [PATCH v3 4/6] usage: add show_usage_and_exit_if_asked()
In reply to Jeff KingQuoted 5 lines · Jeff King
Quoted 3 lines
show_usage_and_exit_if_asked(argc, argv, usage);to help correct these code paths.
I found the name hard to distinguish from the earlier helper,
As we all know that usage_with_options() and usage() exits,
show_usage_with_options_if_asked()
show_usage_if_asked()
may be good enough, I wonder? "show" -> "help" may give us better names.
Quoted 6 lines
I think the "
and_exit" could probably be implied, since showing the usage is always a final thing (just like inusage()andusage_with_options()). So:show_usage_if_asked(); show_usage_with_options_if_asked();
Ah, We came to the same conclusion. The only thing we haven't made it obvious is that "show" implies the output goes to the standard output stream, while without "show", the output goes to the standard error stream. I wonder if these help better:
show_help_if_asked();
show_help_with_options_if_asked()"show help" explains the output goes to where the "help" message would go ;-)
But probably "if-asked" is clear enough indication that the output is made in response to an explicit end-user request, so let's take the show_(usage|usage_with_options)_if_asked as the final names.
Quoted 18 lines
Quoted 6 lines
usage.c +1
-1-static void vreportf (const char *prefix,const char *err,va_list params) +static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);usage.c static void vreportf(const char *prefix, const char *err, va_list params) · line 38
Quoted 9 lines
usage.c +4
-2@@ -32,8 +32,14 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +if (fd ==2 ) +fflush (stderr); +write_in_full (fd, msg, p - msg); +}Gross. :) I think the existing code is conceptually:
Quoted 4 lines
write_in_full(fileno(stderr), msg, p - msg);In which case
vfreportf()could just take a FILE*, flush it and then write.
Sure, but these "stderr" are real error reporting that need to stay to be stderr, and flush needs to be done only when our true payload goes to fd#2 and I do not think these fflush() are about stdio calls made by the caller _before_ it called this function. It may become a bit tricky to read the resulting code if we pass "FILE *".
Re: [PATCH v3 4/6] usage: add show_usage_and_exit_if_asked()
Quoted 11 lines · Junio C Hamano
Quoted 11 lines
Review
Quoted 6 lines
(quoted diff) +4
-2- fflush(stderr); - write_in_full(2, msg, p - msg); + if (fd == 2) + fflush(stderr); + write_in_full(fd, msg, p - msg); +}Gross. :) I think the existing code is conceptually:
write_in_full(fileno(stderr), msg, p - msg);
Quoted 8 lines
Quoted 2 lines
In which case
vfreportf()could just take a FILE*, flush it and then write.Sure, but these "stderr" are real error reporting that need to stay to be stderr, and flush needs to be done only when our true payload goes to fd#2 and I do not think these
fflush()are about stdio calls made by the caller _before_ it called this function. It may become a bit tricky to read the resulting code if we pass "FILE *".
I think the flush _is_ about earlier stdio calls in the process; that's what 116d1fa6c6 (vreportf(): avoid relying on stdio buffering, 2019-10-30) says. I do think it's unlikely for the process to write to stdout() before processing "-h", but it seems like we should do the safer thing as a general principle, unless it ends up hard to do so.
You said "may become a bit tricky" above, but unless I'm missing something, it's just:
--- usage.c | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-)
usage.c +5 -6
@@ -8,7 +8,7 @@#include "gettext.h" #include "trace2.h" -static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) +static void vfreportf (FILE *fh,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
@@ -32,14 +32,13 @@ static void vfdreportf(int fd, const char *prefix, const char *err, va_list para } *(p++) ='\n' ;/* we no longer need a NUL */ -if (fd ==2 ) -fflush (stderr); -write_in_full (fd, msg, p - msg); +fflush (fh); +write_in_full (fileno (fh), msg, p - msg); }static void vreportf (const char *prefix,const char *err,va_list params) { -vfdreportf (2 , prefix, err, params); +vfreportf (stderr, prefix, err, params); } static NORETURN void usage_builtin(const char *err, va_list params)
@@ -184,7 +183,7 @@ static void show_usage_if_asked_helper(const char *err, ...)va_list params;va_start (params, err); -vfdreportf (1 ,_ ("usage: " ), err, params); +vfreportf (stdout,_ ("usage: " ), err, params);va_end (params);exit (129 ); }
Re: [PATCH v3 4/6] usage: add show_usage_and_exit_if_asked()
Quoted 2 lines · Jeff King
You said "may become a bit tricky" above, but unless I'm missing something, it's just:
I didn't mean "tricky to write". I meant it would become tricky to reason about while reading the resulting code why we flush only when fh is stderr.
Quoted 3 lines
I think the flush _is_ about earlier stdio calls in the process; that's what
116d1fa6c6(vreportf(): avoid relying on stdio buffering, 2019-10-30) says.
But as vreportf() has always been about stderr, when that old commit talks about "stdio", it is talking about stderr, isn't it?
Quoted 3 lines
I do think it's unlikely for the process to write to
stdout()before processing "-h", but it seems like we should do the safer thing as a general principle, unless it ends up hard to do so.
We are going to exit immediately at the end of this function, so there is no point in avoiding an fflush() call that may not be needed. So I am not fundamentally opposed to unconditionally flushing before doing the write().
Thanks.
PATCH v3 5/6 oddballs: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_and_exit_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The callers in this step are oddballs in that their invocations of usage() are *not* guarded by
if (argc == 2 && !strcmp(argv[1], "-h") usage(...);
They are (unnecessarily) being clever and do things like
if (argc != 2 || !strcmp(argv[1], "-h") usage(...);
to say "I know I take only one argument, so argc != 2 is always an error regardless of what is in argv[]. Ah, by the way, even if argc is 2, "-h" is a request for usage text, so we do the same". Some just do not treat "-h" any specially, and let it take the same error code paths as a parameter error.
Now we cannot do the same, so these callers are rewrittin to do the show_usage_and_exit_if_asked() first and then handle the usage error the way they used to.
--- builtin/credential.c | 3 ++- builtin/unpack-file.c | 8 ++++++-- builtin/upload-archive.c | 3 ++- builtin/var.c | 1 + 4 files changed, 11 insertions(+), 4 deletions(-)
builtin/credential.c +2 -1
@@ -18,7 +18,8 @@ int cmd_credential(int argc,git_config (git_default_config,NULL ); -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_and_exit_if_asked (argc, argv, usage_msg); +if (argc !=2 )usage (usage_msg); op = argv[1 ];
builtin/unpack-file.c +6 -2
@@ -26,6 +26,9 @@ static char *create_temp_file(struct object_id *oid)return path; } +static const char usage_msg[] = +"git unpack-file <blob>" ; + int cmd_unpack_file(int argc, const char **argv, const char *prefix UNUSED,
@@ -33,8 +36,9 @@ int cmd_unpack_file(int argc, {struct object_id oid; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) -usage ("git unpack-file <blob>" ); +show_usage_and_exit_if_asked (argc, argv, usage_msg); +if (argc !=2 ) +usage (usage_msg);if (repo_get_oid (the_repository, argv[1 ], &oid))die ("Not a valid object name %s" , argv[1 ]);
builtin/upload-archive.c +2 -1
@@ -27,7 +27,8 @@ int cmd_upload_archive_writer(int argc,const char *arg_cmd ="argument " ;int ret; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_and_exit_if_asked (argc, argv, upload_archive_usage); +if (argc !=2 )usage (upload_archive_usage);if (!enter_repo (argv[1 ],0 ))
builtin/var.c +1 -0
@@ -221,6 +221,7 @@ int cmd_var(int argc,const struct git_var *git_var;char *val; +show_usage_and_exit_if_asked (argc, argv, var_usage);if (argc !=2 )usage (var_usage);
Signature · 1 line
2.48.1-191-gafe818080f
Re: [PATCH v3 5/6] oddballs: send usage() help text to standard output
Quoted 13 lines · Junio C Hamano
Using the
show_usage_and_exit_if_asked()helper we introduced earlier, fix callers ofusage()that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.The callers in this step are oddballs in that their invocations of
usage()are *not* guarded byif (argc == 2 && !strcmp(argv[1], "-h") usage(...);They are (unnecessarily) being clever and do things like
Quoted 8 lines
if (argc != 2 || !strcmp(argv[1], "-h") usage(...);to say "I know I take only one argument, so argc != 2 is always an error regardless of what is in argv[]. Ah, by the way, even if argc is 2, "-h" is a request for usage text, so we do the same". Some just do not treat "-h" any specially, and let it take the same error code paths as a parameter error.
As the author of at least one of these, I feel judged. :)
But yes, untangling this is obviously good (especially if we change the exit code later!). And pulling these into their own commit made reviewing much easier.
builtin/var.c int cmd_var(int argc, · line 226
Quoted 11 lines
builtin/var.c +1
-0@@ -221,6 +221,7 @@ int cmd_var(int argc,const struct git_var *git_var;char *val; +show_usage_and_exit_if_asked (argc, argv, var_usage);if (argc !=2 )usage (var_usage);
Hmm, what's going on in this one? It does not check "-h" at all.
Ah, I see. It simply hits the get_git_var() call, sees there is no var called "-h", and exits with an error. So checking for "-h" up front is correct. It is an oddball, though not quite the same as the others (the oddest ball?).
-Peff
Re: [PATCH v3 5/6] oddballs: send usage() help text to standard output
Quoted 9 lines · Jeff King
Quoted 3 lines
.... Some
just do not treat "-h" any specially, and let it take the same error code paths as a parameter error....
builtin/var.c int cmd_var(int argc, · line 226
Quoted 3 lines
builtin/var.c +1
-0+show_usage_and_exit_if_asked (argc, argv, var_usage);if (argc !=2 )usage (var_usage);Hmm, what's going on in this one? It does not check "-h" at all.
Yes, this is the one that let the usual error code paths to treat it as a mere parameter error.
PATCH v3 6/6 builtin: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_and_exit_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
These are the bog standard "if we got only '-h', then that is a request for help" callers. Their
if (argc == 2 && !strcmp(argv[1], "-h")) usage(message);
are simply replaced with
show_usage_and_exit_if_asked(argc, argv, message);
With this, the built-ins tested by t0012 all send their help text to their standard output stream, so the check in t0012 that was half tightened earlier is now fully tightened to insist on standard error stream being empty.
--- builtin/check-ref-format.c | 4 ++-- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/fetch-pack.c | 3 +++ builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/pack-redundant.c | 3 +-- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-objects.c | 2 ++ builtin/upload-archive.c | 3 +-- t/helper/test-simple-ipc.c | 4 ++-- t/t0012-help.sh | 10 ++-------- 21 files changed, 42 insertions(+), 34 deletions(-)
builtin/check-ref-format.c +2 -2
@@ -64,8 +64,8 @@ int cmd_check_ref_format(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (builtin_check_ref_format_usage); +show_usage_and_exit_if_asked (argc, argv, + builtin_check_ref_format_usage);if (argc ==3 && !strcmp (argv[1 ],"--branch" ))return check_ref_format_branch (argv[2 ]);
builtin/diff-files.c +1 -2
@@ -29,8 +29,7 @@ int cmd_diff_files(int argc,int result;unsigned options =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_files_usage); +show_usage_and_exit_if_asked (argc, argv, diff_files_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-index.c +1 -2
@@ -26,8 +26,7 @@ int cmd_diff_index(int argc,int i;int result; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_cache_usage); +show_usage_and_exit_if_asked (argc, argv, diff_cache_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-tree.c +1 -2
@@ -122,8 +122,7 @@ int cmd_diff_tree(int argc,int read_stdin =0 ;int merge_base =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_tree_usage); +show_usage_and_exit_if_asked (argc, argv, diff_tree_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/fast-import.c +1 -2
@@ -3565,8 +3565,7 @@ int cmd_fast_import(int argc, {unsigned int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (fast_import_usage); +show_usage_and_exit_if_asked (argc, argv, fast_import_usage);reset_pack_idx_option (&pack_idx_opts);git_pack_config ();
builtin/fetch-pack.c +3 -0
@@ -176,6 +176,9 @@ int cmd_fetch_pack(int argc,list_objects_filter_set_no_filter (&args.filter_options);continue ; } + +if (!strcmp (arg,"-h" )) +show_usage_and_exit_if_asked (2 , &arg -1 , fetch_pack_usage);usage (fetch_pack_usage); }if (deepen_not.nr)
builtin/get-tar-commit-id.c +3 -1
@@ -13,7 +13,7 @@ static const char builtin_get_tar_commit_id_usage[] =#define HEADERSIZE (2 * RECORDSIZE)int cmd_get_tar_commit_id (int argc, - const char **argv UNUSED, +const char **argv,const char *prefix, struct repository *repo UNUSED) {
@@ -27,6 +27,8 @@ int cmd_get_tar_commit_id(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_and_exit_if_asked (argc, argv, builtin_get_tar_commit_id_usage); +if (argc !=1 )usage (builtin_get_tar_commit_id_usage);
builtin/index-pack.c +1 -2
@@ -1897,8 +1897,7 @@ int cmd_index_pack(int argc,*/ fetch_if_missing =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (index_pack_usage); +show_usage_and_exit_if_asked (argc, argv, index_pack_usage);disable_replace_refs (); fsck_options.walk = mark_link;
builtin/mailsplit.c +2 -2
@@ -284,6 +284,8 @@ int cmd_mailsplit(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_and_exit_if_asked (argc, argv, git_mailsplit_usage); +for (argp = argv+1 ; *argp; argp++) {const char *arg = *argp;
@@ -297,8 +299,6 @@ int cmd_mailsplit(int argc,continue ; }else if ( arg[1 ] =='f' ) { nr =strtol (arg+2 ,NULL ,10 ); - }else if ( arg[1 ] =='h' ) { -usage (git_mailsplit_usage); }else if ( arg[1 ] =='b' && !arg[2 ] ) { allow_bare =1 ; }else if (!strcmp (arg,"--keep-cr" )) {
builtin/merge-index.c +6 -1
@@ -75,6 +75,9 @@ static void merge_all(void) } } +static const char usage_string[] = +"git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ; + int cmd_merge_index(int argc, const char **argv, const char *prefix UNUSED,
@@ -87,8 +90,10 @@ int cmd_merge_index(int argc,*/ signal (SIGCHLD ,SIG_DFL ); +show_usage_and_exit_if_asked (argc, argv, usage_string); +if (argc <3 ) -usage ("git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ); +usage (usage_string);repo_read_index (the_repository);
builtin/merge-ours.c +1 -2
@@ -23,8 +23,7 @@ int cmd_merge_ours(int argc, const char *prefix UNUSED, struct repository *repo UNUSED) { - if (argc == 2 && !strcmp(argv[1], "-h")) -usage (builtin_merge_ours_usage); +show_usage_and_exit_if_asked (argc ,argv ,builtin_merge_ours_usage );/* * The contents of the current index becomes the tree we
builtin/merge-recursive.c +6 -0
@@ -38,6 +38,12 @@ int cmd_merge_recursive(int argc,if (argv[0 ] &&ends_with (argv[0 ],"-subtree" )) o.subtree_shift ="" ; +if (argc ==2 && !strcmp (argv[1 ],"-h" )) { +struct strbuf msg =STRBUF_INIT ; +strbuf_addf (&msg, builtin_merge_recursive_usage, argv[0 ]); +show_usage_and_exit_if_asked (argc, argv, msg.buf); + } +if (argc <4 )usagef (builtin_merge_recursive_usage, argv[0 ]);
builtin/pack-redundant.c +1 -2
@@ -595,8 +595,7 @@ int cmd_pack_redundant(int argc, const char **argv, const char *prefix UNUSED, sstruct strbuf idx_name =STRBUF_INIT ;char buf[GIT_MAX_HEXSZ +2 ];/* hex hash + \n + \0 */ -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (pack_redundant_usage); +show_usage_and_exit_if_asked (argc, argv, pack_redundant_usage);for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/remote-ext.c +2 -0
@@ -202,6 +202,8 @@ int cmd_remote_ext(int argc, {BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_and_exit_if_asked (argc, argv, usage_msg); +if (argc !=3 )usage (usage_msg);
builtin/remote-fd.c +1 -0
@@ -64,6 +64,7 @@ int cmd_remote_fd(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_and_exit_if_asked (argc, argv, usage_msg);if (argc !=3 )usage (usage_msg);
builtin/rev-list.c +1 -2
@@ -542,8 +542,7 @@ int cmd_rev_list(int argc,const char *show_progress =NULL ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (rev_list_usage); +show_usage_and_exit_if_asked (argc, argv, rev_list_usage);git_config (git_default_config,NULL );repo_init_revisions (the_repository, &revs, prefix);
builtin/rev-parse.c +2 -0
@@ -713,6 +713,8 @@ int cmd_rev_parse(int argc,int seen_end_of_options =0 ;enum format_type format =FORMAT_DEFAULT ; +show_usage_and_exit_if_asked (argc, argv, builtin_rev_parse_usage); +if (argc >1 && !strcmp ("--parseopt" , argv[1 ]))return cmd_parseopt (argc -1 , argv +1 , prefix);
builtin/unpack-objects.c +2 -0
@@ -619,6 +619,8 @@ int cmd_unpack_objects(int argc, quiet = !isatty (2 ); +show_usage_and_exit_if_asked (argc, argv, unpack_usage); +for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/upload-archive.c +1 -2
@@ -93,8 +93,7 @@ struct repository *repo UNUSED)BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (upload_archive_usage); +show_usage_and_exit_if_asked (argc, argv, upload_archive_usage);/* * Set up sideband subprocess.
t/helper/test-simple-ipc.c +2 -2
@@ -612,8 +612,8 @@ int cmd__simple_ipc(int argc, const char **argv)if (argc <2 )usage_with_options (simple_ipc_usage, options); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (simple_ipc_usage, options); +show_usage_help_and_exit_if_asked (argc, argv, + simple_ipc_usage, options);if (argc ==2 && !strcmp (argv[1 ],"SUPPORTS_SIMPLE_IPC" ))return 0 ;
t/t0012-help.sh +2 -8
@@ -257,14 +257,8 @@ do export GIT_CEILING_DIRECTORIES && test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" - then - test_must_be_empty err && - test_grep usage output - else - test_grep usage output || - test_grep usage err - fi + test_must_be_empty err && + test_grep usage output ' done <builtins
Signature · 1 line
2.48.1-191-gafe818080f
Re: [PATCH v3 6/6] builtin: send usage() help text to standard output
Quoted 8 lines · Junio C Hamano
Using the
show_usage_and_exit_if_asked()helper we introduced earlier, fix callers ofusage()that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.These are the bog standard "if we got only '-h', then that is a request for help" callers. Their
Quoted 7 lines
if (argc == 2 && !strcmp(argv[1], "-h")) usage(message);are simply replaced with
show_usage_and_exit_if_asked(argc, argv, message);...
The above is a bit of a lie. There is one strange thing I did, which needs to be redone.
Quoted 5 lines
builtin/fetch-pack.c +0
-0
builtin/fetch-pack.c int cmd_fetch_pack(int argc, · line 184
Quoted 9 lines
builtin/fetch-pack.c +3
-0@@ -176,6 +176,9 @@ int cmd_fetch_pack(int argc,list_objects_filter_set_no_filter (&args.filter_options);continue ; } + +if (!strcmp (arg,"-h" )) +show_usage_and_exit_if_asked (2 , &arg -1 , fetch_pack_usage);usage (fetch_pack_usage); }if (deepen_not.nr)
I think we should just call show_usage_and_exit_if_asked() before entering the loop without changing anything else.
Re: [PATCH v3 6/6] builtin: send usage() help text to standard output
Quoted 12 lines · Junio C Hamano
The above is a bit of a lie. There is one strange thing I did, which needs to be redone.
Quoted 9 lines
builtin/fetch-pack.c +1
-0@@ -176,6 +176,9 @@ int cmd_fetch_pack(int argc,list_objects_filter_set_no_filter (&args.filter_options);continue ; } +
Quoted 8 lines
builtin/fetch-pack.c int cmd_fetch_pack(int argc, · line 184
Quoted 5 lines
builtin/fetch-pack.c +2
-0+if (!strcmp (arg,"-h" )) +show_usage_and_exit_if_asked (2 , &arg -1 , fetch_pack_usage);usage (fetch_pack_usage); }if (deepen_not.nr)I think we should just call
show_usage_and_exit_if_asked()before entering the loop without changing anything else.
I have worked on a reroll and moved this piece to the "oddball" pile.
Quoted 10 lines · Junio C Hamano
Jonas Konrad noticed[*] that "git branch -h" started showing the help text to the standard error stream. It turns out that we are fairly inconsistent in our implementation of "git cmd -h". The users of parse-options API will get "If -h is the only option on the command line, give the help text to the standard output" for free, but some commands manually check for the condition and then call the
usage_with_options()function, which gives the identical help text to the standard error stream. And "git branch -h" Jonas noticed was one of them.
Quoted 8 lines
Older commands written before parse-options API became dominant show the help text by calling the
usage()function, which is meant to be used when they fail to parse their command line arguments, which has the same problem. An explicit request for help text "git cmd -h" should be fulfilled by showing the help on the standard output.This series teachs "git $cmd -h" to send its help text to the standard output stream consistently for built-in commands.
I had a small complaint in patch 4, but otherwise this looks good to me.
If we want to switch the exit code for this case from 129 to 0, I think we could easily do so on top (it would need modifications in three places, but now that you've untangled all of the individual builtins, that would get all of them).
I guess there may be non-builtins that would need to be handled individually, though. We don't have too many of them these days, but they are not covered by t0012.
-Peff
Quoted 4 lines · Jeff King
If we want to switch the exit code for this case from 129 to 0, I think we could easily do so on top (it would need modifications in three places, but now that you've untangled all of the individual builtins, that would get all of them).
Yes, I consider it pretty much an orthogonal issue to update the exit status.
Quoted 3 lines
I guess there may be non-builtins that would need to be handled individually, though. We don't have too many of them these days, but they are not covered by t0012.
Yes. We can probably leave them as they are, as we have established our expectation with this series (i.e. an explicit end user request for help text should emit to the standard output stream), so any bug report can be handled without needing any policy discussion. "Hey, I noticed 'git cmd -h' writes to stderr, not stdout"---"Thanks, cmd need to be fixed".
v4 cover Send help text from "git cmd -h" to stdout
In reply to Junio C HamanoJonas Konrad noticed[*] that "git branch -h" started showing the help text to the standard error stream. It turns out that we are fairly inconsistent in our implementation of "git cmd -h". The users of parse-options API will get "If -h is the only option on the command line, give the help text to the standard output" for free, but some commands manually check for the condition and then call the usage_with_options() function, which gives the identical help text to the standard error stream. And "git branch -h" Jonas noticed was one of them.
Older commands written before parse-options API became dominant show the help text by calling the usage() function, which is meant to be used when they fail to parse their command line arguments, which has the same problem. An explicit request for help text "git cmd -h" should be fulfilled by showing the help on the standard output.
This series teachs "git $cmd -h" to send its help text to the standard output stream consistently for built-in commands.
There is a related "what status should these command exit with?" question, and an argument can be made to switch them to exit with 0, instead of historical 129, but it is left outside of the series for now.
Changes since v3:
- The helper functions for usage_with_options() and usage() are renamed to show_usage_with_options_if_asked() and show_usage_if_asked(), respectively.
- The call to usage() in builtin/fetch-pack.c turns out to be the same class as builtin/var.c that simply treats "-h" as an unrecognised command line option. The fix was rewritten to follow the pattern taken to fix "git var -h" and moved to the "oddball" step.
- The patches are reordered; the first three patches prepare the new helper functions and ways to test their effect, and the remaining patches convert the commands to use the new helper functions.
[Reference]
https://lore.kernel.org/git/[email protected]/
Jeff King (1):
t0012: optionally check that "-h" output goes to stdout
Junio C Hamano (5):
parse-options: add show_usage_with_options_if_asked()
usage: add show_usage_if_asked()
builtins: send usage_with_options() help text to standard output
oddballs: send usage() help text to standard output
builtin: send usage() help text to standard output
builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/check-ref-format.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/credential.c | 3 ++- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/fetch-pack.c | 2 ++ builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/ls-files.c | 4 ++-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/merge.c | 4 ++-- builtin/pack-redundant.c | 3 +-- builtin/rebase.c | 6 +++--- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-file.c | 8 ++++++-- builtin/unpack-objects.c | 2 ++ builtin/update-index.c | 4 ++-- builtin/upload-archive.c | 6 +++--- builtin/var.c | 1 + git-compat-util.h | 2 ++ parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ t/helper/test-simple-ipc.c | 4 ++-- t/t0012-help.sh | 3 ++- t/t7600-merge.sh | 2 +- usage.c | 28 +++++++++++++++++++++++++--- 41 files changed, 122 insertions(+), 64 deletions(-)
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v4 1/6 t0012: optionally check that "-h" output goes to stdout
From: Jeff King <[email protected]>
For most commands, "git foo -h" will send the help output to stdout, as this is what parse-options.c does. But some commands send it to stderr instead. This is usually because they call usage_with_options(), and should be switched to show_usage_help_and_exit_if_asked().
Currently t0012 is permissive and allows either behavior. We'd like it to eventually enforce that help goes to stdout, and teaching it to do so identifies the commands that need to be changed. But during the transition period, we don't want to enforce that for most test runs.
So let's introduce a flag that will let most test runs use the permissive behavior, and people interested in converting commands can run:
GIT_TEST_HELP_MUST_BE_STDOUT=1 ./t0012-help.sh
to see the failures. Eventually (when all builtins have been converted) we'll remove this flag entirely and always check the strict behavior.
---
* Same as before.
t/t0012-help.sh | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
t/t0012-help.sh +9 -2
@@ -255,9 +255,16 @@ do ( GIT_CEILING_DIRECTORIES=$(pwd) && export GIT_CEILING_DIRECTORIES && - test_expect_code 129 git -C sub $builtin -h >output 2>&1 + test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - test_grep usage output + if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" + then + test_must_be_empty err && + test_grep usage output + else + test_grep usage output || + test_grep usage err + fi ' done <builtins
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v4 2/6 parse-options: add show_usage_with_options_if_asked()
In reply to Junio C HamanoMany commands call usage_with_options() when they are asked to give the help message, but it sends the help text to the standard error stream. When the user asked for it with "git cmd -h", the help message is the primary output from the command, hence we should send it to the standard output stream, instead.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage_with_options(usage, options);
and replaces it with
show_usage_with_options_if_asked(argc, argv, usage, options);
to help correct code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
---
* Helper function renamed.
parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ 2 files changed, 14 insertions(+)
parse-options.c +10 -0
@@ -1282,6 +1282,16 @@ void NORETURN usage_with_options(const char * const *usagestr,exit (129 ); } +void show_usage_with_options_if_asked (int ac,const char **av, +const char *const *usagestr, +const struct option *opts) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) { +usage_with_options_internal (NULL , usagestr, opts,0 ,0 ); +exit (129 ); + } +} + void NORETURN usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options)
parse-options.h +4 -0
@@ -402,6 +402,10 @@ int parse_options(int argc, const char **argv, const char *prefix, NORETURN void usage_with_options(const char * const *usagestr,const struct option *options); +void show_usage_with_options_if_asked (int ac,const char **av, +const char *const *usage, +const struct option *options); + NORETURN void usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options);
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v4 3/6 usage: add show_usage_if_asked()
In reply to Junio C HamanoSome commands call usage() when they are asked to give the help message with "git cmd -h", but this has the same problem as we fixed with callers of usage_with_options() for the same purpose.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage(usage);
and replaces it with
show_usage_if_asked(argc, argv, usage);
to help correct these code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
---
* Helper function renamed.
git-compat-util.h | 2 ++ usage.c | 28 +++++++++++++++++++++++++--- 2 files changed, 27 insertions(+), 3 deletions(-)
git-compat-util.h +2 -0
@@ -701,6 +701,8 @@ int error_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));void warning (const char *err, ...) __attribute__((format (printf,1 ,2 )));void warning_errno (const char *err, ...) __attribute__((format (printf,1 ,2 ))); +void show_usage_if_asked (int ac,const char **av,const char *err); +#ifndef NO_OPENSSL #ifdef APPLE_COMMON_CRYPTO #include "compat/apple-common-crypto.h"
usage.c +25 -3
@@ -8,7 +8,7 @@#include "gettext.h" #include "trace2.h" -static void vreportf (const char *prefix,const char *err,va_list params) +static void vfdreportf (int fd,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
@@ -32,8 +32,14 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +if (fd ==2 ) +fflush (stderr); +write_in_full (fd, msg, p - msg); +} + +static void vreportf (const char *prefix,const char *err,va_list params) +{ +vfdreportf (2 , prefix, err, params); } static NORETURN void usage_builtin(const char *err, va_list params)
@@ -173,6 +179,22 @@ void NORETURN usage(const char *err)usagef ("%s" , err); } +static void show_usage_if_asked_helper (const char *err, ...) +{ +va_list params; + +va_start (params, err); +vfdreportf (1 ,_ ("usage: " ), err, params); +va_end (params); +exit (129 ); +} + +void show_usage_if_asked (int ac,const char **av,const char *err) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) +show_usage_if_asked_helper (err); +} + void NORETURN die(const char *err, ...) {va_list params;
Signature · 1 line
2.48.1-191-gafe818080f
Re: [PATCH v4 3/6] usage: add show_usage_if_asked()
So here is a replacement for this step. Everything else is unaffected, so I'll wait for other comments until sending a full reroll.
Thanks.
--- >8 ---
Subject: [PATCH v5 3/6] usage: add show_usage_if_asked()
Some commands call usage() when they are asked to give the help message with "git cmd -h", but this has the same problem as we fixed with callers of usage_with_options() for the same purpose.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage(usage);
and replaces it with
show_usage_if_asked(argc, argv, usage);
to help correct these code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
---
1: 2b57538eab ! 1: 94a6fdf72f usage: add show_usage_if_asked()
@@ Commit message
doing exactly as asked, so there is no reason to exit with non-zero
status.
+ Helped-by: Jeff King <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>
## git-compat-util.h ##
@@ usage.c
#include "trace2.h"
-static void vreportf(const char *prefix, const char *err, va_list params)
-+static void vfdreportf(int fd, const char *prefix, const char *err, va_list params)
++static void vfreportf(FILE *f, const char *prefix, const char *err, va_list params)
{
char msg[4096];
char *p, *pend = msg + sizeof(msg);
@@ usage.c: static void vreportf(const char *prefix, const char *err, va_list param
*(p++) = '\n'; /* we no longer need a NUL */
- fflush(stderr);
- write_in_full(2, msg, p - msg);
-+ if (fd == 2)
-+ fflush(stderr);
-+ write_in_full(fd, msg, p - msg);
++ fflush(f);
++ write_in_full(fileno(f), msg, p - msg);
+}
+
+static void vreportf(const char *prefix, const char *err, va_list params)
+{
-+ vfdreportf(2, prefix, err, params);
++ vfreportf(stderr, prefix, err, params);
}
static NORETURN void usage_builtin(const char *err, va_list params)
@@ usage.c: void NORETURN usage(const char *err)
+ va_list params;
+
+ va_start(params, err);
-+ vfdreportf(1, _("usage: "), err, params);
++ vfreportf(stdout, _("usage: "), err, params);
+ va_end(params);
+ exit(129);
+}git-compat-util.h | 2 ++ usage.c | 27 ++++++++++++++++++++++++--- 2 files changed, 26 insertions(+), 3 deletions(-)
git-compat-util.h +2 -0
@@ -701,6 +701,8 @@ int error_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));void warning (const char *err, ...) __attribute__((format (printf,1 ,2 )));void warning_errno (const char *err, ...) __attribute__((format (printf,1 ,2 ))); +void show_usage_if_asked (int ac,const char **av,const char *err); +#ifndef NO_OPENSSL #ifdef APPLE_COMMON_CRYPTO #include "compat/apple-common-crypto.h"
usage.c +24 -3
@@ -8,7 +8,7 @@#include "gettext.h" #include "trace2.h" -static void vreportf (const char *prefix,const char *err,va_list params) +static void vfreportf (FILE *f,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
@@ -32,8 +32,13 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +fflush (f); +write_in_full (fileno (f), msg, p - msg); +} + +static void vreportf (const char *prefix,const char *err,va_list params) +{ +vfreportf (stderr, prefix, err, params); } static NORETURN void usage_builtin(const char *err, va_list params)
@@ -173,6 +178,22 @@ void NORETURN usage(const char *err)usagef ("%s" , err); } +static void show_usage_if_asked_helper (const char *err, ...) +{ +va_list params; + +va_start (params, err); +vfreportf (stdout,_ ("usage: " ), err, params); +va_end (params); +exit (129 ); +} + +void show_usage_if_asked (int ac,const char **av,const char *err) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) +show_usage_if_asked_helper (err); +} + void NORETURN die(const char *err, ...) {va_list params;
Signature · 1 line
2.48.1-210-gaa1682cadd
Re: [PATCH v4 3/6] usage: add show_usage_if_asked()
Quoted 3 lines · Junio C Hamano
So here is a replacement for this step. Everything else is unaffected, so I'll wait for other comments until sending a full reroll.
Thanks, with this replacement patch the whole series looks good to me.
-Peff
PATCH v4 4/6 builtins: send usage_with_options() help text to standard output
In reply to Junio C HamanoUsing the show_usage_with_options_if_asked() helper we introduced earlier, fix callers of usage_with_options() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The test in t7600 for "git merge -h" may want to be retired, as the same is covered by t0012 already, but it is specifically testing that the "-h" option gets a response even with a corrupt index file, so for now let's leave it there.
---
* Helper function renamed.
builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/ls-files.c | 4 ++-- builtin/merge.c | 4 ++-- builtin/rebase.c | 6 +++--- builtin/update-index.c | 4 ++-- t/helper/test-simple-ipc.c | 4 ++-- t/t7600-merge.sh | 2 +- 14 files changed, 31 insertions(+), 32 deletions(-)
builtin/am.c +1 -2
@@ -2427,8 +2427,7 @@ int cmd_am(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (usage, options); +show_usage_with_options_if_asked (argc, argv, usage, options);git_config (git_default_config,NULL );
builtin/branch.c +2 -2
@@ -784,8 +784,8 @@ int cmd_branch(int argc, filter.kind =FILTER_REFS_BRANCHES ; filter.abbrev =-1 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_branch_usage, options); +show_usage_with_options_if_asked (argc, argv, + builtin_branch_usage, options);/* * Try to set sort keys from config. If config does not set any,
builtin/checkout--worker.c +3 -3
@@ -128,9 +128,9 @@ int cmd_checkout__worker(int argc,OPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (checkout_worker_usage, - checkout_worker_options); +show_usage_with_options_if_asked (argc, argv, + checkout_worker_usage, + checkout_worker_options);git_config (git_default_config,NULL ); argc = parse_options(argc, argv, prefix, checkout_worker_options,
builtin/checkout-index.c +3 -3
@@ -250,9 +250,9 @@ int cmd_checkout_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_checkout_index_usage, - builtin_checkout_index_options); +show_usage_with_options_if_asked (argc, argv, + builtin_checkout_index_usage, + builtin_checkout_index_options);git_config (git_default_config,NULL ); prefix_length = prefix ?strlen (prefix) :0 ;
builtin/commit-tree.c +2 -2
@@ -119,8 +119,8 @@ int cmd_commit_tree(int argc,git_config (git_default_config,NULL ); -if (argc <2 || !strcmp (argv[1 ],"-h" )) -usage_with_options (commit_tree_usage, options); +show_usage_with_options_if_asked (argc, argv, + commit_tree_usage, options); argc =parse_options (argc, argv, prefix, options, commit_tree_usage,0 );
builtin/commit.c +4 -4
@@ -1559,8 +1559,8 @@ struct repository *repo UNUSED) OPT_END(), }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_status_usage, builtin_status_options); +show_usage_with_options_if_asked (argc, argv, + builtin_status_usage, builtin_status_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
@@ -1736,8 +1736,8 @@ int cmd_commit(int argc,struct strbuf err =STRBUF_INIT ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_commit_usage, builtin_commit_options); +show_usage_with_options_if_asked (argc, argv, + builtin_commit_usage, builtin_commit_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/fsmonitor--daemon.c +2 -2
@@ -1598,8 +1598,8 @@ int cmd_fsmonitor__daemon(int argc, const char **argv, const char *prefix UNUSEDOPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_fsmonitor__daemon_usage, options); +show_usage_with_options_if_asked (argc, argv, + builtin_fsmonitor__daemon_usage, options);die (_ ("fsmonitor--daemon not supported on this platform" )); }
builtin/gc.c +2 -2
@@ -710,8 +710,8 @@ struct repository *repo UNUSED) OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_gc_usage, builtin_gc_options); +show_usage_with_options_if_asked (argc, argv, + builtin_gc_usage, builtin_gc_options);strvec_pushl (&reflog,"reflog" ,"expire" ,"--all" ,NULL );strvec_pushl (&repack,"repack" ,"-d" ,"-l" ,NULL );
builtin/ls-files.c +2 -2
@@ -644,8 +644,8 @@ int cmd_ls_files(int argc, };int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (ls_files_usage, builtin_ls_files_options); +show_usage_with_options_if_asked (argc, argv, + ls_files_usage, builtin_ls_files_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/merge.c +2 -2
@@ -1300,8 +1300,8 @@ int cmd_merge(int argc,void *branch_to_free;int orig_argc = argc; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_merge_usage, builtin_merge_options); +show_usage_with_options_if_asked (argc, argv, + builtin_merge_usage, builtin_merge_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/rebase.c +3 -3
@@ -1223,9 +1223,9 @@ int cmd_rebase(int argc, };int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_rebase_usage, - builtin_rebase_options); +show_usage_with_options_if_asked (argc, argv, + builtin_rebase_usage, + builtin_rebase_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/update-index.c +2 -2
@@ -1045,8 +1045,8 @@ int cmd_update_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (update_index_usage, options); +show_usage_with_options_if_asked (argc, argv, + update_index_usage, options);git_config (git_default_config,NULL );
t/helper/test-simple-ipc.c +2 -2
@@ -612,8 +612,8 @@ int cmd__simple_ipc(int argc, const char **argv)if (argc <2 )usage_with_options (simple_ipc_usage, options); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (simple_ipc_usage, options); +show_usage_with_options_if_asked (argc, argv, + simple_ipc_usage, options);if (argc ==2 && !strcmp (argv[1 ],"SUPPORTS_SIMPLE_IPC" ))return 0 ;
t/t7600-merge.sh +1 -1
@@ -173,7 +173,7 @@ test_expect_success 'merge -h with invalid index' ' cd broken && git init && >.git/index && - test_expect_code 129 git merge -h 2>usage + test_expect_code 129 git merge -h >usage ) && test_grep "[Uu]sage: git merge" broken/usage '
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v4 5/6 oddballs: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The callers in this step are oddballs in that their invocations of usage() are *not* guarded by
if (argc == 2 && !strcmp(argv[1], "-h") usage(...);
There are (unnecessarily) being clever ones that do things like
if (argc != 2 || !strcmp(argv[1], "-h") usage(...);
to say "I know I take only one argument, so argc != 2 is always an error regardless of what is in argv[]. Ah, by the way, even if argc is 2, "-h" is a request for usage text, so we do the same".
Some like "git var -h" just do not treat "-h" any specially, and let it take the same error code paths as a parameter error.
Now we cannot do the same, so these callers are rewrittin to do the show_usage_and_exit_if_asked() first and then handle the usage error the way they used to.
---
* Helper function renamed.
Fix fo fetch-pack.c moved from the next step and redone.
builtin/credential.c | 3 ++- builtin/fetch-pack.c | 2 ++ builtin/unpack-file.c | 8 ++++++-- builtin/upload-archive.c | 3 ++- builtin/var.c | 1 + 5 files changed, 13 insertions(+), 4 deletions(-)
builtin/credential.c +2 -1
@@ -18,7 +18,8 @@ int cmd_credential(int argc,git_config (git_default_config,NULL ); -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=2 )usage (usage_msg); op = argv[1 ];
builtin/fetch-pack.c +2 -0
@@ -75,6 +75,8 @@ int cmd_fetch_pack(int argc,list_objects_filter_init (&args.filter_options); args.uploadpack ="git-upload-pack" ; +show_usage_if_asked (argc, argv, fetch_pack_usage); +for (i =1 ; i < argc && *argv[i] =='-' ; i++) {const char *arg = argv[i];
builtin/unpack-file.c +6 -2
@@ -26,6 +26,9 @@ static char *create_temp_file(struct object_id *oid)return path; } +static const char usage_msg[] = +"git unpack-file <blob>" ; + int cmd_unpack_file(int argc, const char **argv, const char *prefix UNUSED,
@@ -33,8 +36,9 @@ int cmd_unpack_file(int argc, {struct object_id oid; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) -usage ("git unpack-file <blob>" ); +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=2 ) +usage (usage_msg);if (repo_get_oid (the_repository, argv[1 ], &oid))die ("Not a valid object name %s" , argv[1 ]);
builtin/upload-archive.c +2 -1
@@ -27,7 +27,8 @@ int cmd_upload_archive_writer(int argc,const char *arg_cmd ="argument " ;int ret; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_if_asked (argc, argv, upload_archive_usage); +if (argc !=2 )usage (upload_archive_usage);if (!enter_repo (argv[1 ],0 ))
builtin/var.c +1 -0
@@ -221,6 +221,7 @@ int cmd_var(int argc,const struct git_var *git_var;char *val; +show_usage_if_asked (argc, argv, var_usage);if (argc !=2 )usage (var_usage);
Signature · 1 line
2.48.1-191-gafe818080f
PATCH v4 6/6 builtin: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_and_exit_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
These are the bog standard "if we got only '-h', then that is a request for help" callers. Their
if (argc == 2 && !strcmp(argv[1], "-h")) usage(message);
are simply replaced with
show_usage_and_exit_if_asked(argc, argv, message);
With this, the built-ins tested by t0012 all send their help text to their standard output stream, so the check in t0012 that was half tightened earlier is now fully tightened to insist on standard error stream being empty.
---
* Helper function renamed.
builtin/check-ref-format.c | 4 ++-- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/pack-redundant.c | 3 +-- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-objects.c | 2 ++ builtin/upload-archive.c | 3 +-- t/t0012-help.sh | 10 ++-------- 19 files changed, 37 insertions(+), 32 deletions(-)
builtin/check-ref-format.c +2 -2
@@ -64,8 +64,8 @@ int cmd_check_ref_format(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (builtin_check_ref_format_usage); +show_usage_if_asked (argc, argv, + builtin_check_ref_format_usage);if (argc ==3 && !strcmp (argv[1 ],"--branch" ))return check_ref_format_branch (argv[2 ]);
builtin/diff-files.c +1 -2
@@ -29,8 +29,7 @@ int cmd_diff_files(int argc,int result;unsigned options =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_files_usage); +show_usage_if_asked (argc, argv, diff_files_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-index.c +1 -2
@@ -26,8 +26,7 @@ int cmd_diff_index(int argc,int i;int result; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_cache_usage); +show_usage_if_asked (argc, argv, diff_cache_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-tree.c +1 -2
@@ -122,8 +122,7 @@ int cmd_diff_tree(int argc,int read_stdin =0 ;int merge_base =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_tree_usage); +show_usage_if_asked (argc, argv, diff_tree_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/fast-import.c +1 -2
@@ -3565,8 +3565,7 @@ int cmd_fast_import(int argc, {unsigned int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (fast_import_usage); +show_usage_if_asked (argc, argv, fast_import_usage);reset_pack_idx_option (&pack_idx_opts);git_pack_config ();
builtin/get-tar-commit-id.c +3 -1
@@ -13,7 +13,7 @@ static const char builtin_get_tar_commit_id_usage[] =#define HEADERSIZE (2 * RECORDSIZE)int cmd_get_tar_commit_id (int argc, - const char **argv UNUSED, +const char **argv,const char *prefix, struct repository *repo UNUSED) {
@@ -27,6 +27,8 @@ int cmd_get_tar_commit_id(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, builtin_get_tar_commit_id_usage); +if (argc !=1 )usage (builtin_get_tar_commit_id_usage);
builtin/index-pack.c +1 -2
@@ -1897,8 +1897,7 @@ int cmd_index_pack(int argc,*/ fetch_if_missing =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (index_pack_usage); +show_usage_if_asked (argc, argv, index_pack_usage);disable_replace_refs (); fsck_options.walk = mark_link;
builtin/mailsplit.c +2 -2
@@ -284,6 +284,8 @@ int cmd_mailsplit(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, git_mailsplit_usage); +for (argp = argv+1 ; *argp; argp++) {const char *arg = *argp;
@@ -297,8 +299,6 @@ int cmd_mailsplit(int argc,continue ; }else if ( arg[1 ] =='f' ) { nr =strtol (arg+2 ,NULL ,10 ); - }else if ( arg[1 ] =='h' ) { -usage (git_mailsplit_usage); }else if ( arg[1 ] =='b' && !arg[2 ] ) { allow_bare =1 ; }else if (!strcmp (arg,"--keep-cr" )) {
builtin/merge-index.c +6 -1
@@ -75,6 +75,9 @@ static void merge_all(void) } } +static const char usage_string[] = +"git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ; + int cmd_merge_index(int argc, const char **argv, const char *prefix UNUSED,
@@ -87,8 +90,10 @@ int cmd_merge_index(int argc,*/ signal (SIGCHLD ,SIG_DFL ); +show_usage_if_asked (argc, argv, usage_string); +if (argc <3 ) -usage ("git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ); +usage (usage_string);repo_read_index (the_repository);
builtin/merge-ours.c +1 -2
@@ -23,8 +23,7 @@ int cmd_merge_ours(int argc, const char *prefix UNUSED, struct repository *repo UNUSED) { - if (argc == 2 && !strcmp(argv[1], "-h")) -usage (builtin_merge_ours_usage); +show_usage_if_asked (argc ,argv ,builtin_merge_ours_usage );/* * The contents of the current index becomes the tree we
builtin/merge-recursive.c +6 -0
@@ -38,6 +38,12 @@ int cmd_merge_recursive(int argc,if (argv[0 ] &&ends_with (argv[0 ],"-subtree" )) o.subtree_shift ="" ; +if (argc ==2 && !strcmp (argv[1 ],"-h" )) { +struct strbuf msg =STRBUF_INIT ; +strbuf_addf (&msg, builtin_merge_recursive_usage, argv[0 ]); +show_usage_if_asked (argc, argv, msg.buf); + } +if (argc <4 )usagef (builtin_merge_recursive_usage, argv[0 ]);
builtin/pack-redundant.c +1 -2
@@ -595,8 +595,7 @@ int cmd_pack_redundant(int argc, const char **argv, const char *prefix UNUSED, sstruct strbuf idx_name =STRBUF_INIT ;char buf[GIT_MAX_HEXSZ +2 ];/* hex hash + \n + \0 */ -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (pack_redundant_usage); +show_usage_if_asked (argc, argv, pack_redundant_usage);for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/remote-ext.c +2 -0
@@ -202,6 +202,8 @@ int cmd_remote_ext(int argc, {BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=3 )usage (usage_msg);
builtin/remote-fd.c +1 -0
@@ -64,6 +64,7 @@ int cmd_remote_fd(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, usage_msg);if (argc !=3 )usage (usage_msg);
builtin/rev-list.c +1 -2
@@ -542,8 +542,7 @@ int cmd_rev_list(int argc,const char *show_progress =NULL ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (rev_list_usage); +show_usage_if_asked (argc, argv, rev_list_usage);git_config (git_default_config,NULL );repo_init_revisions (the_repository, &revs, prefix);
builtin/rev-parse.c +2 -0
@@ -713,6 +713,8 @@ int cmd_rev_parse(int argc,int seen_end_of_options =0 ;enum format_type format =FORMAT_DEFAULT ; +show_usage_if_asked (argc, argv, builtin_rev_parse_usage); +if (argc >1 && !strcmp ("--parseopt" , argv[1 ]))return cmd_parseopt (argc -1 , argv +1 , prefix);
builtin/unpack-objects.c +2 -0
@@ -619,6 +619,8 @@ int cmd_unpack_objects(int argc, quiet = !isatty (2 ); +show_usage_if_asked (argc, argv, unpack_usage); +for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/upload-archive.c +1 -2
@@ -93,8 +93,7 @@ struct repository *repo UNUSED)BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (upload_archive_usage); +show_usage_if_asked (argc, argv, upload_archive_usage);/* * Set up sideband subprocess.
t/t0012-help.sh +2 -8
@@ -257,14 +257,8 @@ do export GIT_CEILING_DIRECTORIES && test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" - then - test_must_be_empty err && - test_grep usage output - else - test_grep usage output || - test_grep usage err - fi + test_must_be_empty err && + test_grep usage output ' done <builtins
Signature · 1 line
2.48.1-191-gafe818080f
Re: [PATCH v4 6/6] builtin: send usage() help text to standard output
Quoted 7 lines · Junio C Hamano
t/t0012-help.sh +0
-1@@ -257,14 +257,8 @@ do export GIT_CEILING_DIRECTORIES && test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT"
t/t0012-help.sh do · line 262
Quoted 10 lines
t/t0012-help.sh +2
-7- then - test_must_be_empty err && - test_grep usage output - else - test_grep usage output || - test_grep usage err - fi + test_must_be_empty err && + test_grep usage output '
Just a side note for the future: you wondered if we might ever get bitten by insisting on an empty stderr here (since it might catch warnings, etc).
If we do, I think it would be OK to just drop the test_must_be_empty line. Now that we are capturing only stdout in "output", checking that the usage message is there is probably sufficient.
In the meantime, I think I prefer keeping the slightly more strict form above.
-Peff
Re: [PATCH v4 6/6] builtin: send usage() help text to standard output
Quoted 3 lines · Jeff King
If we do, I think it would be OK to just drop the
test_must_be_emptyline. Now that we are capturing only stdout in "output", checking that the usage message is there is probably sufficient.
Yes.
Quoted 2 lines
In the meantime, I think I prefer keeping the slightly more strict form above.
I am also in favor of keeping it, if only to learn why we do not want the overly strict check when the time comes. That would mean we would be loosening with a concrete reason why we would want to loose it at that time, instead of guessing that it might be overly strict without seeing the fallout before seeing any.
Thanks.
v5 cover Send help text from "git cmd -h" to stdout
In reply to Junio C HamanoJonas Konrad noticed[*] that "git branch -h" started showing the help text to the standard error stream. It turns out that we are fairly inconsistent in our implementation of "git cmd -h". The users of parse-options API will get "If -h is the only option on the command line, give the help text to the standard output" for free, but some commands manually check for the condition and then call the usage_with_options() function, which gives the identical help text to the standard error stream. And "git branch -h" Jonas noticed was one of them.
Older commands written before parse-options API became dominant show the help text by calling the usage() function, which is meant to be used when they fail to parse their command line arguments, which has the same problem. An explicit request for help text "git cmd -h" should be fulfilled by showing the help on the standard output.
This series teachs "git $cmd -h" to send its help text to the standard output stream consistently for built-in commands.
There is a related "what status should these command exit with?" question, and an argument can be made to switch them to exit with 0, instead of historical 129, but it is left outside of the series for now.
Changes since v4:
- vfdreportf() helper that took a file descriptor has been replaced with vfreportf() that takes a FILE * instead, with Peff's help.
[Reference]
https://lore.kernel.org/git/[email protected]/
Jeff King (1):
t0012: optionally check that "-h" output goes to stdout
Junio C Hamano (5):
parse-options: add show_usage_with_options_if_asked()
usage: add show_usage_if_asked()
builtins: send usage_with_options() help text to standard output
oddballs: send usage() help text to standard output
builtin: send usage() help text to standard output
builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/check-ref-format.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/credential.c | 3 ++- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/fetch-pack.c | 2 ++ builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/ls-files.c | 4 ++-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/merge.c | 4 ++-- builtin/pack-redundant.c | 3 +-- builtin/rebase.c | 6 +++--- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-file.c | 8 ++++++-- builtin/unpack-objects.c | 2 ++ builtin/update-index.c | 4 ++-- builtin/upload-archive.c | 6 +++--- builtin/var.c | 1 + git-compat-util.h | 2 ++ parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ t/helper/test-simple-ipc.c | 4 ++-- t/t0012-help.sh | 3 ++- t/t7600-merge.sh | 2 +- usage.c | 27 ++++++++++++++++++++++++--- 41 files changed, 121 insertions(+), 64 deletions(-)
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 1/6 t0012: optionally check that "-h" output goes to stdout
From: Jeff King <[email protected]>
For most commands, "git foo -h" will send the help output to stdout, as this is what parse-options.c does. But some commands send it to stderr instead. This is usually because they call usage_with_options(), and should be switched to show_usage_help_and_exit_if_asked().
Currently t0012 is permissive and allows either behavior. We'd like it to eventually enforce that help goes to stdout, and teaching it to do so identifies the commands that need to be changed. But during the transition period, we don't want to enforce that for most test runs.
So let's introduce a flag that will let most test runs use the permissive behavior, and people interested in converting commands can run:
GIT_TEST_HELP_MUST_BE_STDOUT=1 ./t0012-help.sh
to see the failures. Eventually (when all builtins have been converted) we'll remove this flag entirely and always check the strict behavior.
--- t/t0012-help.sh | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
t/t0012-help.sh +9 -2
@@ -255,9 +255,16 @@ do ( GIT_CEILING_DIRECTORIES=$(pwd) && export GIT_CEILING_DIRECTORIES && - test_expect_code 129 git -C sub $builtin -h >output 2>&1 + test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - test_grep usage output + if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" + then + test_must_be_empty err && + test_grep usage output + else + test_grep usage output || + test_grep usage err + fi ' done <builtins
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 2/6 parse-options: add show_usage_with_options_if_asked()
In reply to Junio C HamanoMany commands call usage_with_options() when they are asked to give the help message, but it sends the help text to the standard error stream. When the user asked for it with "git cmd -h", the help message is the primary output from the command, hence we should send it to the standard output stream, instead.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage_with_options(usage, options);
and replaces it with
show_usage_with_options_if_asked(argc, argv, usage, options);
to help correct code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
--- parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ 2 files changed, 14 insertions(+)
parse-options.c +10 -0
@@ -1282,6 +1282,16 @@ void NORETURN usage_with_options(const char * const *usagestr,exit (129 ); } +void show_usage_with_options_if_asked (int ac,const char **av, +const char *const *usagestr, +const struct option *opts) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) { +usage_with_options_internal (NULL , usagestr, opts,0 ,0 ); +exit (129 ); + } +} + void NORETURN usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options)
parse-options.h +4 -0
@@ -402,6 +402,10 @@ int parse_options(int argc, const char **argv, const char *prefix, NORETURN void usage_with_options(const char * const *usagestr,const struct option *options); +void show_usage_with_options_if_asked (int ac,const char **av, +const char *const *usage, +const struct option *options); + NORETURN void usage_msg_opt(const char *msg,const char *const *usagestr,const struct option *options);
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 3/6 usage: add show_usage_if_asked()
In reply to Junio C HamanoSome commands call usage() when they are asked to give the help message with "git cmd -h", but this has the same problem as we fixed with callers of usage_with_options() for the same purpose.
Introduce a helper function that captures the common pattern
if (argc == 2 && !strcmp(argv[1], "-h")) usage(usage);
and replaces it with
show_usage_if_asked(argc, argv, usage);
to help correct these code paths.
Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status.
--- git-compat-util.h | 2 ++ usage.c | 27 ++++++++++++++++++++++++--- 2 files changed, 26 insertions(+), 3 deletions(-)
git-compat-util.h +2 -0
@@ -701,6 +701,8 @@ int error_errno(const char *err, ...) __attribute__((format (printf, 1, 2)));void warning (const char *err, ...) __attribute__((format (printf,1 ,2 )));void warning_errno (const char *err, ...) __attribute__((format (printf,1 ,2 ))); +void show_usage_if_asked (int ac,const char **av,const char *err); +#ifndef NO_OPENSSL #ifdef APPLE_COMMON_CRYPTO #include "compat/apple-common-crypto.h"
usage.c +24 -3
@@ -8,7 +8,7 @@#include "gettext.h" #include "trace2.h" -static void vreportf (const char *prefix,const char *err,va_list params) +static void vfreportf (FILE *f,const char *prefix,const char *err,va_list params) {char msg[4096 ];char *p, *pend = msg +sizeof (msg);
@@ -32,8 +32,13 @@ static void vreportf(const char *prefix, const char *err, va_list params) } *(p++) ='\n' ;/* we no longer need a NUL */ -fflush (stderr); -write_in_full (2 , msg, p - msg); +fflush (f); +write_in_full (fileno (f), msg, p - msg); +} + +static void vreportf (const char *prefix,const char *err,va_list params) +{ +vfreportf (stderr, prefix, err, params); } static NORETURN void usage_builtin(const char *err, va_list params)
@@ -173,6 +178,22 @@ void NORETURN usage(const char *err)usagef ("%s" , err); } +static void show_usage_if_asked_helper (const char *err, ...) +{ +va_list params; + +va_start (params, err); +vfreportf (stdout,_ ("usage: " ), err, params); +va_end (params); +exit (129 ); +} + +void show_usage_if_asked (int ac,const char **av,const char *err) +{ +if (ac ==2 && !strcmp (av[1 ],"-h" )) +show_usage_if_asked_helper (err); +} + void NORETURN die(const char *err, ...) {va_list params;
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 4/6 builtins: send usage_with_options() help text to standard output
In reply to Junio C HamanoUsing the show_usage_with_options_if_asked() helper we introduced earlier, fix callers of usage_with_options() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The test in t7600 for "git merge -h" may want to be retired, as the same is covered by t0012 already, but it is specifically testing that the "-h" option gets a response even with a corrupt index file, so for now let's leave it there.
--- builtin/am.c | 3 +-- builtin/branch.c | 4 ++-- builtin/checkout--worker.c | 6 +++--- builtin/checkout-index.c | 6 +++--- builtin/commit-tree.c | 4 ++-- builtin/commit.c | 8 ++++---- builtin/fsmonitor--daemon.c | 4 ++-- builtin/gc.c | 4 ++-- builtin/ls-files.c | 4 ++-- builtin/merge.c | 4 ++-- builtin/rebase.c | 6 +++--- builtin/update-index.c | 4 ++-- t/helper/test-simple-ipc.c | 4 ++-- t/t7600-merge.sh | 2 +- 14 files changed, 31 insertions(+), 32 deletions(-)
builtin/am.c +1 -2
@@ -2427,8 +2427,7 @@ int cmd_am(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (usage, options); +show_usage_with_options_if_asked (argc, argv, usage, options);git_config (git_default_config,NULL );
builtin/branch.c +2 -2
@@ -784,8 +784,8 @@ int cmd_branch(int argc, filter.kind =FILTER_REFS_BRANCHES ; filter.abbrev =-1 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_branch_usage, options); +show_usage_with_options_if_asked (argc, argv, + builtin_branch_usage, options);/* * Try to set sort keys from config. If config does not set any,
builtin/checkout--worker.c +3 -3
@@ -128,9 +128,9 @@ int cmd_checkout__worker(int argc,OPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (checkout_worker_usage, - checkout_worker_options); +show_usage_with_options_if_asked (argc, argv, + checkout_worker_usage, + checkout_worker_options);git_config (git_default_config,NULL ); argc = parse_options(argc, argv, prefix, checkout_worker_options,
builtin/checkout-index.c +3 -3
@@ -250,9 +250,9 @@ int cmd_checkout_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_checkout_index_usage, - builtin_checkout_index_options); +show_usage_with_options_if_asked (argc, argv, + builtin_checkout_index_usage, + builtin_checkout_index_options);git_config (git_default_config,NULL ); prefix_length = prefix ?strlen (prefix) :0 ;
builtin/commit-tree.c +2 -2
@@ -119,8 +119,8 @@ int cmd_commit_tree(int argc,git_config (git_default_config,NULL ); -if (argc <2 || !strcmp (argv[1 ],"-h" )) -usage_with_options (commit_tree_usage, options); +show_usage_with_options_if_asked (argc, argv, + commit_tree_usage, options); argc =parse_options (argc, argv, prefix, options, commit_tree_usage,0 );
builtin/commit.c +4 -4
@@ -1559,8 +1559,8 @@ struct repository *repo UNUSED) OPT_END(), }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_status_usage, builtin_status_options); +show_usage_with_options_if_asked (argc, argv, + builtin_status_usage, builtin_status_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
@@ -1736,8 +1736,8 @@ int cmd_commit(int argc,struct strbuf err =STRBUF_INIT ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_commit_usage, builtin_commit_options); +show_usage_with_options_if_asked (argc, argv, + builtin_commit_usage, builtin_commit_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/fsmonitor--daemon.c +2 -2
@@ -1598,8 +1598,8 @@ int cmd_fsmonitor__daemon(int argc, const char **argv, const char *prefix UNUSEDOPT_END () }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_fsmonitor__daemon_usage, options); +show_usage_with_options_if_asked (argc, argv, + builtin_fsmonitor__daemon_usage, options);die (_ ("fsmonitor--daemon not supported on this platform" )); }
builtin/gc.c +2 -2
@@ -710,8 +710,8 @@ struct repository *repo UNUSED) OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_gc_usage, builtin_gc_options); +show_usage_with_options_if_asked (argc, argv, + builtin_gc_usage, builtin_gc_options);strvec_pushl (&reflog,"reflog" ,"expire" ,"--all" ,NULL );strvec_pushl (&repack,"repack" ,"-d" ,"-l" ,NULL );
builtin/ls-files.c +2 -2
@@ -644,8 +644,8 @@ int cmd_ls_files(int argc, };int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (ls_files_usage, builtin_ls_files_options); +show_usage_with_options_if_asked (argc, argv, + ls_files_usage, builtin_ls_files_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/merge.c +2 -2
@@ -1300,8 +1300,8 @@ int cmd_merge(int argc,void *branch_to_free;int orig_argc = argc; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_merge_usage, builtin_merge_options); +show_usage_with_options_if_asked (argc, argv, + builtin_merge_usage, builtin_merge_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/rebase.c +3 -3
@@ -1223,9 +1223,9 @@ int cmd_rebase(int argc, };int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (builtin_rebase_usage, - builtin_rebase_options); +show_usage_with_options_if_asked (argc, argv, + builtin_rebase_usage, + builtin_rebase_options);prepare_repo_settings (the_repository); the_repository->settings.command_requires_full_index =0 ;
builtin/update-index.c +2 -2
@@ -1045,8 +1045,8 @@ int cmd_update_index(int argc, OPT_END() }; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (update_index_usage, options); +show_usage_with_options_if_asked (argc, argv, + update_index_usage, options);git_config (git_default_config,NULL );
t/helper/test-simple-ipc.c +2 -2
@@ -612,8 +612,8 @@ int cmd__simple_ipc(int argc, const char **argv)if (argc <2 )usage_with_options (simple_ipc_usage, options); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage_with_options (simple_ipc_usage, options); +show_usage_with_options_if_asked (argc, argv, + simple_ipc_usage, options);if (argc ==2 && !strcmp (argv[1 ],"SUPPORTS_SIMPLE_IPC" ))return 0 ;
t/t7600-merge.sh +1 -1
@@ -173,7 +173,7 @@ test_expect_success 'merge -h with invalid index' ' cd broken && git init && >.git/index && - test_expect_code 129 git merge -h 2>usage + test_expect_code 129 git merge -h >usage ) && test_grep "[Uu]sage: git merge" broken/usage '
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 5/6 oddballs: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
The callers in this step are oddballs in that their invocations of usage() are *not* guarded by
if (argc == 2 && !strcmp(argv[1], "-h") usage(...);
There are (unnecessarily) being clever ones that do things like
if (argc != 2 || !strcmp(argv[1], "-h") usage(...);
to say "I know I take only one argument, so argc != 2 is always an error regardless of what is in argv[]. Ah, by the way, even if argc is 2, "-h" is a request for usage text, so we do the same".
Some like "git var -h" just do not treat "-h" any specially, and let it take the same error code paths as a parameter error.
Now we cannot do the same, so these callers are rewrittin to do the show_usage_and_exit_if_asked() first and then handle the usage error the way they used to.
--- builtin/credential.c | 3 ++- builtin/fetch-pack.c | 2 ++ builtin/unpack-file.c | 8 ++++++-- builtin/upload-archive.c | 3 ++- builtin/var.c | 1 + 5 files changed, 13 insertions(+), 4 deletions(-)
builtin/credential.c +2 -1
@@ -18,7 +18,8 @@ int cmd_credential(int argc,git_config (git_default_config,NULL ); -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=2 )usage (usage_msg); op = argv[1 ];
builtin/fetch-pack.c +2 -0
@@ -75,6 +75,8 @@ int cmd_fetch_pack(int argc,list_objects_filter_init (&args.filter_options); args.uploadpack ="git-upload-pack" ; +show_usage_if_asked (argc, argv, fetch_pack_usage); +for (i =1 ; i < argc && *argv[i] =='-' ; i++) {const char *arg = argv[i];
builtin/unpack-file.c +6 -2
@@ -26,6 +26,9 @@ static char *create_temp_file(struct object_id *oid)return path; } +static const char usage_msg[] = +"git unpack-file <blob>" ; + int cmd_unpack_file(int argc, const char **argv, const char *prefix UNUSED,
@@ -33,8 +36,9 @@ int cmd_unpack_file(int argc, {struct object_id oid; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) -usage ("git unpack-file <blob>" ); +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=2 ) +usage (usage_msg);if (repo_get_oid (the_repository, argv[1 ], &oid))die ("Not a valid object name %s" , argv[1 ]);
builtin/upload-archive.c +2 -1
@@ -27,7 +27,8 @@ int cmd_upload_archive_writer(int argc,const char *arg_cmd ="argument " ;int ret; -if (argc !=2 || !strcmp (argv[1 ],"-h" )) +show_usage_if_asked (argc, argv, upload_archive_usage); +if (argc !=2 )usage (upload_archive_usage);if (!enter_repo (argv[1 ],0 ))
builtin/var.c +1 -0
@@ -221,6 +221,7 @@ int cmd_var(int argc,const struct git_var *git_var;char *val; +show_usage_if_asked (argc, argv, var_usage);if (argc !=2 )usage (var_usage);
Signature · 1 line
2.48.1-218-gc7e8be6a8f
PATCH v5 6/6 builtin: send usage() help text to standard output
In reply to Junio C HamanoUsing the show_usage_and_exit_if_asked() helper we introduced earlier, fix callers of usage() that want to show the help text when explicitly asked by the end-user. The help text now goes to the standard output stream for them.
These are the bog standard "if we got only '-h', then that is a request for help" callers. Their
if (argc == 2 && !strcmp(argv[1], "-h")) usage(message);
are simply replaced with
show_usage_and_exit_if_asked(argc, argv, message);
With this, the built-ins tested by t0012 all send their help text to their standard output stream, so the check in t0012 that was half tightened earlier is now fully tightened to insist on standard error stream being empty.
--- builtin/check-ref-format.c | 4 ++-- builtin/diff-files.c | 3 +-- builtin/diff-index.c | 3 +-- builtin/diff-tree.c | 3 +-- builtin/fast-import.c | 3 +-- builtin/get-tar-commit-id.c | 4 +++- builtin/index-pack.c | 3 +-- builtin/mailsplit.c | 4 ++-- builtin/merge-index.c | 7 ++++++- builtin/merge-ours.c | 3 +-- builtin/merge-recursive.c | 6 ++++++ builtin/pack-redundant.c | 3 +-- builtin/remote-ext.c | 2 ++ builtin/remote-fd.c | 1 + builtin/rev-list.c | 3 +-- builtin/rev-parse.c | 2 ++ builtin/unpack-objects.c | 2 ++ builtin/upload-archive.c | 3 +-- t/t0012-help.sh | 10 ++-------- 19 files changed, 37 insertions(+), 32 deletions(-)
builtin/check-ref-format.c +2 -2
@@ -64,8 +64,8 @@ int cmd_check_ref_format(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (builtin_check_ref_format_usage); +show_usage_if_asked (argc, argv, + builtin_check_ref_format_usage);if (argc ==3 && !strcmp (argv[1 ],"--branch" ))return check_ref_format_branch (argv[2 ]);
builtin/diff-files.c +1 -2
@@ -29,8 +29,7 @@ int cmd_diff_files(int argc,int result;unsigned options =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_files_usage); +show_usage_if_asked (argc, argv, diff_files_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-index.c +1 -2
@@ -26,8 +26,7 @@ int cmd_diff_index(int argc,int i;int result; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_cache_usage); +show_usage_if_asked (argc, argv, diff_cache_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/diff-tree.c +1 -2
@@ -122,8 +122,7 @@ int cmd_diff_tree(int argc,int read_stdin =0 ;int merge_base =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (diff_tree_usage); +show_usage_if_asked (argc, argv, diff_tree_usage);git_config (git_diff_basic_config,NULL );/* no "diff" UI options */
builtin/fast-import.c +1 -2
@@ -3565,8 +3565,7 @@ int cmd_fast_import(int argc, {unsigned int i; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (fast_import_usage); +show_usage_if_asked (argc, argv, fast_import_usage);reset_pack_idx_option (&pack_idx_opts);git_pack_config ();
builtin/get-tar-commit-id.c +3 -1
@@ -13,7 +13,7 @@ static const char builtin_get_tar_commit_id_usage[] =#define HEADERSIZE (2 * RECORDSIZE)int cmd_get_tar_commit_id (int argc, - const char **argv UNUSED, +const char **argv,const char *prefix, struct repository *repo UNUSED) {
@@ -27,6 +27,8 @@ int cmd_get_tar_commit_id(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, builtin_get_tar_commit_id_usage); +if (argc !=1 )usage (builtin_get_tar_commit_id_usage);
builtin/index-pack.c +1 -2
@@ -1897,8 +1897,7 @@ int cmd_index_pack(int argc,*/ fetch_if_missing =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (index_pack_usage); +show_usage_if_asked (argc, argv, index_pack_usage);disable_replace_refs (); fsck_options.walk = mark_link;
builtin/mailsplit.c +2 -2
@@ -284,6 +284,8 @@ int cmd_mailsplit(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, git_mailsplit_usage); +for (argp = argv+1 ; *argp; argp++) {const char *arg = *argp;
@@ -297,8 +299,6 @@ int cmd_mailsplit(int argc,continue ; }else if ( arg[1 ] =='f' ) { nr =strtol (arg+2 ,NULL ,10 ); - }else if ( arg[1 ] =='h' ) { -usage (git_mailsplit_usage); }else if ( arg[1 ] =='b' && !arg[2 ] ) { allow_bare =1 ; }else if (!strcmp (arg,"--keep-cr" )) {
builtin/merge-index.c +6 -1
@@ -75,6 +75,9 @@ static void merge_all(void) } } +static const char usage_string[] = +"git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ; + int cmd_merge_index(int argc, const char **argv, const char *prefix UNUSED,
@@ -87,8 +90,10 @@ int cmd_merge_index(int argc,*/ signal (SIGCHLD ,SIG_DFL ); +show_usage_if_asked (argc, argv, usage_string); +if (argc <3 ) -usage ("git merge-index [-o] [-q] <merge-program> (-a | [--] [<filename>...])" ); +usage (usage_string);repo_read_index (the_repository);
builtin/merge-ours.c +1 -2
@@ -23,8 +23,7 @@ int cmd_merge_ours(int argc, const char *prefix UNUSED, struct repository *repo UNUSED) { - if (argc == 2 && !strcmp(argv[1], "-h")) -usage (builtin_merge_ours_usage); +show_usage_if_asked (argc ,argv ,builtin_merge_ours_usage );/* * The contents of the current index becomes the tree we
builtin/merge-recursive.c +6 -0
@@ -38,6 +38,12 @@ int cmd_merge_recursive(int argc,if (argv[0 ] &&ends_with (argv[0 ],"-subtree" )) o.subtree_shift ="" ; +if (argc ==2 && !strcmp (argv[1 ],"-h" )) { +struct strbuf msg =STRBUF_INIT ; +strbuf_addf (&msg, builtin_merge_recursive_usage, argv[0 ]); +show_usage_if_asked (argc, argv, msg.buf); + } +if (argc <4 )usagef (builtin_merge_recursive_usage, argv[0 ]);
builtin/pack-redundant.c +1 -2
@@ -595,8 +595,7 @@ int cmd_pack_redundant(int argc, const char **argv, const char *prefix UNUSED, sstruct strbuf idx_name =STRBUF_INIT ;char buf[GIT_MAX_HEXSZ +2 ];/* hex hash + \n + \0 */ -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (pack_redundant_usage); +show_usage_if_asked (argc, argv, pack_redundant_usage);for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/remote-ext.c +2 -0
@@ -202,6 +202,8 @@ int cmd_remote_ext(int argc, {BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, usage_msg); +if (argc !=3 )usage (usage_msg);
builtin/remote-fd.c +1 -0
@@ -64,6 +64,7 @@ int cmd_remote_fd(int argc,BUG_ON_NON_EMPTY_PREFIX (prefix); +show_usage_if_asked (argc, argv, usage_msg);if (argc !=3 )usage (usage_msg);
builtin/rev-list.c +1 -2
@@ -542,8 +542,7 @@ int cmd_rev_list(int argc,const char *show_progress =NULL ;int ret =0 ; -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (rev_list_usage); +show_usage_if_asked (argc, argv, rev_list_usage);git_config (git_default_config,NULL );repo_init_revisions (the_repository, &revs, prefix);
builtin/rev-parse.c +2 -0
@@ -713,6 +713,8 @@ int cmd_rev_parse(int argc,int seen_end_of_options =0 ;enum format_type format =FORMAT_DEFAULT ; +show_usage_if_asked (argc, argv, builtin_rev_parse_usage); +if (argc >1 && !strcmp ("--parseopt" , argv[1 ]))return cmd_parseopt (argc -1 , argv +1 , prefix);
builtin/unpack-objects.c +2 -0
@@ -619,6 +619,8 @@ int cmd_unpack_objects(int argc, quiet = !isatty (2 ); +show_usage_if_asked (argc, argv, unpack_usage); +for (i =1 ; i < argc; i++) {const char *arg = argv[i];
builtin/upload-archive.c +1 -2
@@ -93,8 +93,7 @@ struct repository *repo UNUSED)BUG_ON_NON_EMPTY_PREFIX (prefix); -if (argc ==2 && !strcmp (argv[1 ],"-h" )) -usage (upload_archive_usage); +show_usage_if_asked (argc, argv, upload_archive_usage);/* * Set up sideband subprocess.
t/t0012-help.sh +2 -8
@@ -257,14 +257,8 @@ do export GIT_CEILING_DIRECTORIES && test_expect_code 129 git -C sub $builtin -h >output 2>err ) && - if test -n "$GIT_TEST_HELP_MUST_BE_STDOUT" - then - test_must_be_empty err && - test_grep usage output - else - test_grep usage output || - test_grep usage err - fi + test_must_be_empty err && + test_grep usage output ' done <builtins
Signature · 1 line
2.48.1-218-gc7e8be6a8f
Quoted 4 lines · Junio C Hamano
Changes since v4:
-
vfdreportf()helper that took a file descriptor has been replaced withvfreportf()that takes a FILE * instead, with Peff's help.
Thanks, this all looks good to me.
-Peff