rev-parse --parseopt: option argument name hints

Built-in commands can specify names for option arguments when usage text
is generated for a command.  sh based commands should be able to do the
same.

Option argument name hint is any text that comes after [*=?!] after the
argument name up to the first whitespace.

Signed-off-by: Ilya Bobyr <ilya.bobyr@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 0d2cdcde556662d9d858dc282a9fced469814337..e05e6b35939326caa5fa2658d875b0d099216d9f 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -284,13 +284,13 @@ Input Format
 
 'git rev-parse --parseopt' input format is fully text based. It has two parts,
 separated by a line that contains only `--`. The lines before the separator
 
 'git rev-parse --parseopt' input format is fully text based. It has two parts,
 separated by a line that contains only `--`. The lines before the separator

-(should be more than one) are used for the usage.
+(should be one or more) are used for the usage.

 The lines after the separator describe the options.
 
 Each line of options has this format:
 
 ------------
 The lines after the separator describe the options.
 
 Each line of options has this format:
 
 ------------

-<opt_spec><flags>* SP+ help LF
+<opt_spec><flags>*<arg_hint>? SP+ help LF

 ------------
 
 `<opt_spec>`::
 ------------
 
 `<opt_spec>`::


@@ -313,6 +313,12 @@ Each line of options has this format:
 
        * Use `!` to not make the corresponding negated long option available.
 
 
        * Use `!` to not make the corresponding negated long option available.
 

+`<arg_hint>`::
+       `<arg_hint>`, if specified, is used as a name of the argument in the
+       help output, for options that take arguments. `<arg_hint>` is
+       terminated by the first whitespace. When you need to use space in the
+       argument hint use dash instead.
+

 The remainder of the line, after stripping the spaces, is used
 as the help associated to the option.
 
 The remainder of the line, after stripping the spaces, is used
 as the help associated to the option.
 


@@ -333,6 +339,8 @@ h,help    show the help
 
 foo       some nifty option --foo
 bar=      some cool option --bar with an argument
 
 foo       some nifty option --foo
 bar=      some cool option --bar with an argument

+baz=arg   another cool option --baz with a named argument
+qux?path  qux may take a path argument but has meaning by itself

 
   An option group Header
 C?        option C with an optional argument"
 
   An option group Header
 C?        option C with an optional argument"


@@ -340,6 +348,28 @@ C?        option C with an optional argument"
 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
 ------------
 
 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
 ------------
 

+
+Usage text
+~~~~~~~~~~
+
+When `"$@"` is `-h` or `--help` in the above example, the following
+usage text would be shown:
+
+------------
+usage: some-command [options] <args>...
+
+    some-command does foo and bar!
+
+    -h, --help            show the help
+    --foo                 some nifty option --foo
+    --bar ...             some cool option --bar with an argument
+    --bar <arg>           another cool option --baz with a named argument
+    --qux[=<path>]        qux may take a path argument but has meaning by itself
+
+An option group Header
+    -C[...]               option C with an optional argument
+------------
+

 SQ-QUOTE
 --------
 
 SQ-QUOTE
 --------
 

diff --git a/builtin/rev-parse.c b/builtin/rev-parse.c
index 45901df37103f37418d7558adb8ace36c8b56aeb..1a6122d3ae29609c30c26959fbb1ff799e13a4b2 100644 (file)
--- a/builtin/rev-parse.c
+++ b/builtin/rev-parse.c
@@ -395,9 +395,10 @@ static int cmd_parseopt(int argc, const char **argv, const char *prefix)
                usage[unb++] = strbuf_detach(&sb, NULL);
        }
 
                usage[unb++] = strbuf_detach(&sb, NULL);
        }
 

-       /* parse: (<short>|<short>,<long>|<long>)[=?]? SP+ <help> */
+       /* parse: (<short>|<short>,<long>|<long>)[*=?!]*<arghint>? SP+ <help> */

        while (strbuf_getline(&sb, stdin, '\n') != EOF) {
                const char *s;
        while (strbuf_getline(&sb, stdin, '\n') != EOF) {
                const char *s;

+               const char *end;

                struct option *o;
 
                if (!sb.len)
                struct option *o;
 
                if (!sb.len)


@@ -419,6 +420,16 @@ static int cmd_parseopt(int argc, const char **argv, const char *prefix)
                o->value = &parsed;
                o->flags = PARSE_OPT_NOARG;
                o->callback = &parseopt_dump;
                o->value = &parsed;
                o->flags = PARSE_OPT_NOARG;
                o->callback = &parseopt_dump;

+
+               /* Possible argument name hint */
+               end = s;
+               while (s > sb.buf && strchr("*=?!", s[-1]) == NULL)
+                       --s;
+               if (s != sb.buf && s != end)
+                       o->argh = xmemdupz(s, end - s);
+               if (s == sb.buf)
+                       s = end;
+

                while (s > sb.buf && strchr("*=?!", s[-1])) {
                        switch (*--s) {
                        case '=':
                while (s > sb.buf && strchr("*=?!", s[-1])) {
                        switch (*--s) {
                        case '=':

diff --git a/t/t1502-rev-parse-parseopt.sh b/t/t1502-rev-parse-parseopt.sh
index 83b1300cef91c2a13ef58af4ab7a42618388bd01..960adf56af0bd740435356bf76189e65e00ac63c 100755 (executable)
--- a/t/t1502-rev-parse-parseopt.sh
+++ b/t/t1502-rev-parse-parseopt.sh
@@ -18,6 +18,17 @@ An option group Header
     -C[...]               option C with an optional argument
     -d, --data[=...]      short and long option with an optional argument
 
     -C[...]               option C with an optional argument
     -d, --data[=...]      short and long option with an optional argument
 

+Argument hints
+    -b <arg>              short option required argument
+    --bar2 <arg>          long option required argument
+    -e, --fuz <with-space>
+                         short and long option required argument
+    -s[<some>]            short option optional argument
+    --long[=<data>]       long option optional argument
+    -g, --fluf[=<path>]   short and long option optional argument
+    --longest <very-long-argument-hint>
+                         a very long argument hint
+

 Extras
     --extra1              line above used to cause a segfault but no longer does
 
 Extras
     --extra1              line above used to cause a segfault but no longer does
 


@@ -39,6 +50,15 @@ b,baz     a short and long option
 C?        option C with an optional argument
 d,data?   short and long option with an optional argument
 
 C?        option C with an optional argument
 d,data?   short and long option with an optional argument
 

+ Argument hints
+b=arg     short option required argument
+bar2=arg  long option required argument
+e,fuz=with-space  short and long option required argument
+s?some    short option optional argument
+long?data long option optional argument
+g,fluf?path     short and long option optional argument
+longest=very-long-argument-hint  a very long argument hint
+

 Extras
 extra1    line above used to cause a segfault but no longer does
 EOF
 Extras
 extra1    line above used to cause a segfault but no longer does
 EOF