From: Keith Thompson <keith.s.thompson@gmail.com>
Date: Tue, 21 May 2019 21:25:57 GMT
Subject: Slightly confusing documentation for "git clone --recursive"
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]