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

[Eric Sunshine <sunshine@sunshineco.com>]

On Mon, Sep 13, 2021 at 4:42 PM Alban Gruin <alban.gruin@gmail.com> wrote:
> Le 13/09/2021 à 21:26, Eric Sunshine a écrit :
> > On Mon, Sep 13, 2021 at 3:14 PM Alban Gruin <alban.gruin@gmail.com> wrote:
> >> 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`.

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.