short help: allow a gap smaller than USAGE_GAP

The parse-options API responds to "git cmd -h" by listing the option flag (padded to the USAGE_OPTS_WIDTH column), followed by USAGE_GAP (set to 2) whitespaces, followed by the help text. If the flags part does not fit within the USAGE_OPTS_WIDTH, the help text is given on its own line. Imagine that "@" below depicts the USAGE_OPTS_WIDTH'th column, and "#" are for the usage help text, the output may look like this: @@@@@@@@@@@@@ ######################################## -f description of the flag '-f' comes here --short=<num> description of the flag '--short' --very-long-option=<number> description of the flag '--very-long-option' This is all good and nice in principle, but it becomes awkward when the flags part is just one column over the limit and forces a line break. See the description of the "--almost" option below: @@@@@@@@@@@@@ ######################################## -f description of the flag '-f' comes here --short=<num> description of the flag '--short' --almost=<num> description of the flag '--almost' --very-long-option=<number> description of the flag '--very-long-option' If we allow shrinking the gap to a single whitespace only in such a case, we would instead get: @@@@@@@@@@@@@ ######################################## -f description of the flag '-f' comes here --short=<num> description of the flag '--short' --almost=<num> description of the flag '--almost' --very-long-option=<number> description of the flag '--very-long-option' and the boundary between the flags and their descriptions does not become any harder to see, while saving precious vertical screen real estate. Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Jul 18, 2023 at 15:58 UTC c512643e67d33673933fa3d245be28b08b974755
2 files changed +4 -3
parse-options.c
+3 -1
@@ -1146,7 +1146,9 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
1146 !(opts->flags & PARSE_OPT_NOARG))
1147 pos += usage_argh(opts, outfile);
1148
1149 - if (pos <= USAGE_OPTS_WIDTH)
1149 + if (pos == USAGE_OPTS_WIDTH + 1)
1150 + pad = -1;
1151 + else if (pos <= USAGE_OPTS_WIDTH)
1152 pad = USAGE_OPTS_WIDTH - pos;
1153 else {
1154 fputc('\n', outfile);
t/t0040-parse-options.sh
+1 -2
@@ -30,8 +30,7 @@ usage: test-tool parse-options <options>
30 -F, --file <file> set file to <file>
31
32 String options
33 - -s, --string <string>
34 - get a string
33 + -s, --string <string> get a string
34 --string2 <str> get another string
35 --st <st> get another string (pervert ordering)
36 -o <str> get another string