Re: [PATCH v1] git-clone.txt: add the --recursive option

Hi Eric,

Le 13/09/2021 à 23:57, Eric Sunshine a écrit :

On Mon, Sep 13, 2021 at 4:42 PM Alban Gruin [off-list ref] wrote:

quoted

Le 13/09/2021 à 21:26, Eric Sunshine a écrit :

quoted

On Mon, Sep 13, 2021 at 3:14 PM Alban Gruin [off-list ref] wrote:

quoted

This adds the --recursive option, an alias of --recurse-submodule, to
git-clone's manual page.

Considering that the `--recursive` option was intentionally removed
from `git-clone.txt` by bb62e0a99f (clone: teach --recurse-submodules
to optionally take a pathspec, 2017-03-17), it's not clear that this
change helps the situation.

The patch you mention also hides --recursive from the option array, but
that was reverted with 5c387428f1 (parse-options: don't emit "ambiguous
option" for aliases, 2019-04-29).  The option should be re-hidden, or
even removed.

I don't quite follow. As far as I understand both by reading
5c387428f1 and by testing, 5c387428f1 fixed tab-completion so it would
_not_ show `--recursive`.

bb62e0a99f hid --recursive from `git clone -h' with PARSE_OPT_HIDDEN,
but 5c387428f1 reverted that:

$ git checkout 5c387428f1~
$ make
$ bin-wrappers/git clone -h
...
    -s, --shared          setup as shared repository
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone
    -j, --jobs <n>        number of submodules cloned in parallel
...

$ git checkout 5c387428f1
$ make
$ bin-wrappers/git clone -h
...
    --recursive[=<pathspec>]
                          initialize submodules in the clone
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone
...

The two options were then reordered by c28b036fe3 (clone: reorder
--recursive/--recurse-submodules, 2020-03-16), and this is where we are
today:

$ git clone -h
...
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone
    --recursive[=<pathspec>]
                          alias of --recurse-submodules
...

Junio did mention[0] that --recursive was no longer in the manual, but
not that it was once hidden from the option list.

Anyhow, another approach which we've used elsewhere is to mention the
option in the documentation but indicate clearly that it's deprecated.
That way, people who run across the option in existing scripts or old
blogs can at least find out what it means. Something like:

    --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.
        (`--recursive` is a deprecated synonym.)

I don't have an opinion as to whether or not we'd want to do that in this case.

[0] https://lore.kernel.org/git/20200316212857.259093-3-gitster@pobox.com/ (local)

Alban