Re: [PATCH v2] usage: clarify --recurse-submodules as a boolean

[Junio C Hamano <gitster@pobox.com>]

Emily Shaffer <nasamuffin@google.com> writes:

> `git switch` `git checkout`, `git reset`, and `git read-tree` allow a

Missing comma?

> user to choose to recurse into submodules. All four of these commands'
> short usage seems to indicate that `--recurse-submodules` should take an
> argument. In practice, though, all four of these commands parse through
> the same callback path:
>
>   option_parse_recurse_submodules_worktree_updater(...) checks for
>   set/unset, or passes off to...
>   parse_update_recurse_submodules_arg(...), which is a straight handoff
>   to...
>   parse_update_recurse(...), which only accepts true or false.

"true or false" -> "various forms of 'true' (e.g. on/1/yes) or 'false'"

> So ultimately, it can only be true or false, unlike `git push

Likewise.  Here is a minimally touched up version I queued.

Thanks.

    usage: clarify --recurse-submodules as a boolean
    
    `git switch`, `git checkout`, `git reset`, and `git read-tree` allow a
    user to choose to recurse into submodules. All four of these commands'
    short usage seems to indicate that `--recurse-submodules` should take an
    argument. In practice, though, all four of these commands parse through
    the same callback path:
    
      option_parse_recurse_submodules_worktree_updater(...) checks for
      set/unset, or passes off to...
      parse_update_recurse_submodules_arg(...), which is a straight handoff
      to...
      parse_update_recurse(...), which only accepts various ways to
      spell a Boolean
    
    So ultimately, it can only be true or false (or yes/no/on/off/etc),
    unlike `git push --recurse-submodules=<enum>`. A user could provide
    `--recurse-submodules=true`, but we don't typically suggest that for
    boolean arguments.
    
    Documentation/git-(switch|checkout|reset|read-tree).txt suggests
    --[no-]recurse-submodules, too.
    
    In fact, these four commands are the only ones that use this codepath -
    so there's not any reason for it to be so meandering. However, because
    option_parse_recurse_submodules_worktree_updater() modifies static state
    in submodule.c, we still need to get a handle to that static state
    through a function call.
    
    To preserve the behavior of --recurse-submodules=true and clarify the
    usage string simultaneously, get rid of the OPT_CALLBACK_F in favor of a
    simple OPT_BOOL, and call a setter in submodule.c for the static state
    instead. Also, remove the now-unused
    option_parse_recurse_submodules_worktree_updater(),
    parse_update_recurse_submodules_arg(), and parse_update_recurse() calls.
    
    Signed-off-by: Emily Shaffer <nasamuffin@google.com>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>