| Message ID | 20200320213729.571924-5-damien.olivier.robert+git@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: --recurse-submodules | expand |
> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt > index f11940280f..8778a99fa6 100644 > --- a/Documentation/config/fetch.txt > +++ b/Documentation/config/fetch.txt > @@ -1,11 +1,13 @@ > fetch.recurseSubmodules:: > - This option can be either set to a boolean value or to 'on-demand'. > + This option can be set either to a boolean value or to 'on-demand'. > Setting it to a boolean changes the behavior of fetch and pull to I think in the context of patch 5 maybe it would be good to be careful here, and state that this only affects the underlying "fetch" in "pull", and not the whole pull ? > - unconditionally recurse into submodules when set to true or to not > - recurse at all when set to false. When set to 'on-demand' (the default > - value), fetch and pull will only recurse into a populated submodule > + recurse unconditionally into submodules when set to true or to not > + recurse at all when set to false. When set to 'on-demand', > + fetch and pull will only recurse into a populated submodule > when its superproject retrieves a commit that updates the submodule's > reference. > + If not set, 'on-demand' is used by default, unless > + 'submodule.recurse' is set. I know Junio seems to think otherwise, but to me it would be clearer if this would be clearly spelled out: Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
Philippe Blain <levraiphilippeblain@gmail.com> writes: >> - This option can be either set to a boolean value or to 'on-demand'. >> + This option can be set either to a boolean value or to 'on-demand'. >> Setting it to a boolean changes the behavior of fetch and pull to > > I think in the context of patch 5 maybe it would be good to be > careful here, and state that this only affects the underlying > "fetch" in "pull", and not the whole pull ? Meaning that sub(sub)*modules are fetched but the merge is done only for the top-level superproject? I guess it does not hurt to spell it out. Good suggestion. >> + If not set, 'on-demand' is used by default, unless >> + 'submodule.recurse' is set. > > I know Junio seems to think otherwise, but to me it would be > clearer if this would be clearly spelled out: > > Defaults to 'on-demand', or to the value of 'submodule.recurse' if set. Well, between the above two, I'd actually have slight preference to yours, but they both look clear enough to almost the same degree, at least to me. Thanks.
> Le 22 mars 2020 à 19:01, Junio C Hamano <gitster@pobox.com> a écrit : > > Philippe Blain <levraiphilippeblain@gmail.com> writes: > >>> - This option can be either set to a boolean value or to 'on-demand'. >>> + This option can be set either to a boolean value or to 'on-demand'. >>> Setting it to a boolean changes the behavior of fetch and pull to >> >> I think in the context of patch 5 maybe it would be good to be >> careful here, and state that this only affects the underlying >> "fetch" in "pull", and not the whole pull ? > > Meaning that sub(sub)*modules are fetched but the merge is done only > for the top-level superproject? I guess it does not hurt to spell > it out. Good suggestion. I simply meant that since this option is 'fetch.recurseSubmodules', it applies to the fetching operation done by 'git pull' under the hood, and not to the "updating the working tree" operation that is also done by git pull if '--recurse-submodules' is passed to it. Regarding nested submodules, both operations would recurse down the hierarchy: the fetching fetches all (nested) populated submodules because of the call to submodule.c::fetch_populated_submodules near the end of builtin/fetch.c::cmd_fetch and the "updating the working tree", which is controlled by the '--recurse-submodules' flag of 'git pull', updates all active submodules because it spawns 'git submodule update --recursive', (as per rebase_submodules and update_submodules in builtin/pull.c).
diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..8778a99fa6 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -1,11 +1,13 @@ fetch.recurseSubmodules:: - This option can be either set to a boolean value or to 'on-demand'. + This option can be set either to a boolean value or to 'on-demand'. Setting it to a boolean changes the behavior of fetch and pull to - unconditionally recurse into submodules when set to true or to not - recurse at all when set to false. When set to 'on-demand' (the default - value), fetch and pull will only recurse into a populated submodule + recurse unconditionally into submodules when set to true or to not + recurse at all when set to false. When set to 'on-demand', + fetch and pull will only recurse into a populated submodule when its superproject retrieves a commit that updates the submodule's reference. + If not set, 'on-demand' is used by default, unless + 'submodule.recurse' is set. fetch.fsckObjects:: If it is set to true, git-fetch-pack will check all fetched diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index 0a7aa322a9..f5e5b38c68 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -112,3 +112,5 @@ push.recurseSubmodules:: is 'no' then default behavior of ignoring submodules when pushing is retained. You may override this configuration at time of push by specifying '--recurse-submodules=check|on-demand|no'. + If not set, 'no' is used by default, unless 'submodule.recurse' is + set (in which case a 'true' value means 'on-demand'). diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a115a1ae0e..b1058d63bc 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -163,7 +163,8 @@ ifndef::git-pull[] value. Use 'on-demand' to only recurse into a populated submodule when the superproject retrieves a commit that updates the submodule's reference to a commit that isn't already in the local submodule - clone. + clone. By default, 'on-demand' is used, unless + `fetch.recurseSubmodules` is set (see linkgit:git-config[1]). -j:: --jobs=<n>:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index dfb901f8b8..47bc4a7061 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -86,8 +86,7 @@ OPTIONS --[no-]recurse-submodules[=yes|on-demand|no]:: This option controls if new commits of all populated submodules should - be fetched and updated, too (see linkgit:git-config[1] and - linkgit:gitmodules[5]). + be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). + If the checkout is done via rebase, local submodule commits are rebased as well. +
The default value also depends on the value of submodule.recurse. Use this opportunity to correct some grammar mistakes in Documentation/config/fetch.txt signaled by Robert P. J. Day. Also mention `fetch.recurseSubmodules` in fetch-options.txt. In git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by explaining how to disable it), so no need to add it there. Lastly add a link to `git-fetch` in `git-pull.txt` to explain the meaning of `--recurse-submodules` there. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/fetch.txt | 10 ++++++---- Documentation/config/push.txt | 2 ++ Documentation/fetch-options.txt | 3 ++- Documentation/git-pull.txt | 3 +-- 4 files changed, 11 insertions(+), 7 deletions(-)