| Message ID | 20200303170740.1879432-5-damien.olivier.robert+git@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: --recurse-submodules | expand |
Damien Robert <damien.olivier.robert@gmail.com> writes: > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt > index f11940280f..8f716809f9 100644 > --- a/Documentation/config/fetch.txt > +++ b/Documentation/config/fetch.txt > @@ -2,10 +2,12 @@ fetch.recurseSubmodules:: > This option can be either set 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 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, it fallbacks to the value of `submodule.recurse`, and > + if both are not set the default value is 'on-demand'. I do not think "fallback" is a single-word verb. If you must use the phrase, "it falls back to the value of ...", but I personally prefer to give the simplest case first and then its variants second (i.e. if you do not do anything, this is what you get, and then if you do this thing, this other thing happens). In other words: If not set, 'on-demand' is used by default, unless 'submodule.recurse' is set, in which case it is used. But in this case it is so obvious that it would not be necessary to add ", in which case it is used" at the end. > diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt > index 54871f8213..2a5250cf5c 100644 > --- a/Documentation/config/push.txt > +++ b/Documentation/config/push.txt > @@ -112,3 +112,6 @@ 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, it fallbacks to the value of `submodule.recurse` (where > + a 'true' value means 'on-demand'), and if both are not set the > + default value is 'no'. Likewise. > diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt > index a115a1ae0e..58972b1a05 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 this uses the fetch.recurseSubmodules value (see > + linkgit:git-config), and the default value is 'on-demand'. By default, 'on-demand' is used, unless `fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
On Tue, 3 Mar 2020, Junio C Hamano wrote: > Damien Robert <damien.olivier.robert@gmail.com> writes: > > > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt > > index f11940280f..8f716809f9 100644 > > --- a/Documentation/config/fetch.txt > > +++ b/Documentation/config/fetch.txt > > @@ -2,10 +2,12 @@ fetch.recurseSubmodules:: > > This option can be either set 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 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, it fallbacks to the value of `submodule.recurse`, and > > + if both are not set the default value is 'on-demand'. missed earlier post ... "either set" should be "set either." also, adverbs technically *follow* what they qualify, so "unconditionally recusrse" should be "recurse unconditionally" and so on. it has always been thus. rday p.s. avoid use of the word "it" if it's potentially unclear what it refers to. in the above, one reads, "If not set, it falls back ..." *what* falls back?
diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..8f716809f9 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -2,10 +2,12 @@ fetch.recurseSubmodules:: This option can be either set 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 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, it fallbacks to the value of `submodule.recurse`, and + if both are not set the default value is 'on-demand'. 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 54871f8213..2a5250cf5c 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -112,3 +112,6 @@ 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, it fallbacks to the value of `submodule.recurse` (where + a 'true' value means 'on-demand'), and if both are not set the + default value is 'no'. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a115a1ae0e..58972b1a05 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 this uses the fetch.recurseSubmodules value (see + linkgit:git-config), and the default value is 'on-demand'. -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. 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 | 6 ++++-- Documentation/config/push.txt | 3 +++ Documentation/fetch-options.txt | 3 ++- Documentation/git-pull.txt | 3 +-- 4 files changed, 10 insertions(+), 5 deletions(-)