From: Alban Gruin <hidden> Date: 2021-09-13 19:14:27
This adds the --recursive option, an alias of --recurse-submodule, to
git-clone's manual page.
Signed-off-by: Alban Gruin <redacted>
---
I found this out when a friend told me he could not remember how to
fetch submodules with git-clone, and when another one suggested
`--recurse-submodule'. I checked the man page, and I was surprised to
find out that `--recursive' is not mentionned at all.
I did not modify the synopsis. So, this alias, although shorter than
the "real" option, would still be somewhat hidden in the man page.
Documentation/git-clone.txt | 1 +
1 file changed, 1 insertion(+)
@@ -270,6 +270,7 @@ branch. This is useful e.g. to maintain minimal clones of the default branch of some repository for search indexing. --recurse-submodules[=<pathspec>]::+--recursive[=<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.
From: Eric Sunshine <hidden> Date: 2021-09-13 19:26:39
On Mon, Sep 13, 2021 at 3:14 PM Alban Gruin [off-list ref] wrote:
This adds the --recursive option, an alias of --recurse-submodule, to
git-clone's manual page.
Signed-off-by: Alban Gruin <redacted>
---
I found this out when a friend told me he could not remember how to
fetch submodules with git-clone, and when another one suggested
`--recurse-submodule'. I checked the man page, and I was surprised to
find out that `--recursive' is not mentionned at all.
I did not modify the synopsis. So, this alias, although shorter than
the "real" option, would still be somewhat hidden in the man 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.
From: Alban Gruin <hidden> Date: 2021-09-13 20:42:47
Hi Eric,
Le 13/09/2021 à 21:26, Eric Sunshine a écrit :
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.
Signed-off-by: Alban Gruin <redacted>
---
I found this out when a friend told me he could not remember how to
fetch submodules with git-clone, and when another one suggested
`--recurse-submodule'. I checked the man page, and I was surprised to
find out that `--recursive' is not mentionned at all.
I did not modify the synopsis. So, this alias, although shorter than
the "real" option, would still be somewhat hidden in the man 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.
Alban
From: Eric Sunshine <hidden> Date: 2021-09-13 21:57:49
On Mon, Sep 13, 2021 at 4:42 PM Alban Gruin [off-list ref] wrote:
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`.
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.
From: Alban Gruin <hidden> Date: 2021-09-14 10:28:14
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.