Slightly confusing documentation for "git clone --recursive"

From: Keith Thompson <keith.s.thompson@gmail.com>
Date: May 21, 2019, 21:25 UTC
Message-ID: <CAAHpriPYxFv=vET92DonRb=kV_NWEDFe0nRnNH2wxcwP78BDdA@mail.gmail.com>

In builtin/clone.c, the handling of "--recursive" as an alias for "--recurse-submodules" changed between v2.22.0-rc0 and v2.22.0-rc1. This report refers to the way it's documented in the newest version and suggests some improvements.

The short help (git clone -h) says:

    --recursive[=<pathspec>]
                          initialize submodules in the clone
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone

It repeats the same description, but doesn't explicitly say that they're equivalent. I can imagine this causing some confusion. I might have wondered if there's some subtle difference between them. Suggested change:

    --recursive[=<pathspec>]
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone

The long help ("git clone --help") says:

       --recurse-submodules[=<pathspec]
           After the clone is created, initialize and clone submodules within
           based on the provided pathspec. If no pathspec is provided, all
           submodules are initialized and cloned. This option can be given
           multiple times for pathspecs consisting of multiple entries. The
           resulting clone has submodule.active set to the provided pathspec,
           or "." (meaning all submodules) if no pathspec is provided.

           Submodules are initialized and cloned using their default settings.
           This is equivalent to running git submodule update --init
           --recursive <pathspec> immediately after the clone is finished.
           This option is ignored if the cloned repository does not have a
           worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or
           --mirror is given)

The "--recursive" spelling is not documented, but is used in an example in the documentation for "--recursive-submodules". Suggested change:

       --recursive=<pathspec]
       --recurse-submodules[=<pathspec]
           After the clone is created, initialize and clone submodules within
           [... rest of description as before]