* [PATCH 0/4] doc: --recurse-submodules @ 2020-02-28 10:35 Damien Robert 2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert ` (7 more replies) 0 siblings, 8 replies; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:35 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert This series add some extra documentation on --recurse-submodules. Damien Robert (4): doc: list all commands affected by recurse.submodule doc: document --recurse-submodules for reset and restore doc: explain how to deactivate recurse.submodule completely doc: be more precise on (fetch|pull).recurseSubmodules Documentation/config/fetch.txt | 6 ++++-- Documentation/config/push.txt | 3 +++ Documentation/config/submodule.txt | 11 +++++++++-- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 9 +++++++++ 5 files changed, 31 insertions(+), 4 deletions(-) -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH 1/4] doc: list all commands affected by recurse.submodule 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert @ 2020-02-28 10:35 ` Damien Robert 2020-03-02 4:43 ` Philippe Blain 2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert ` (6 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:35 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule 2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert @ 2020-03-02 4:43 ` Philippe Blain 2020-03-03 17:09 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Philippe Blain @ 2020-03-02 4:43 UTC (permalink / raw) To: Damien Robert, git HI Damien, The commit title has the option name reversed: it’s submodule.recurse and not recurse.submodule > Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Note that `ls-files` is not affected, even though it has a > `--recurse-submodules` option, so list it as an exception too. Good find. > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/config/submodule.txt | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) I’d also add the same list to the "Implementation details" section of the gitsubmodules guide [1], which just mentions `checkout` at the moment. [1] https://git-scm.com/docs/gitsubmodules#_implementation_details > > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt > index b33177151c..5962f41ead 100644 > --- a/Documentation/config/submodule.txt > +++ b/Documentation/config/submodule.txt > @@ -59,8 +59,9 @@ submodule.active:: > > submodule.recurse:: > Specifies if commands recurse into submodules by default. This > - applies to all commands that have a `--recurse-submodules` option, > - except `clone`. > + applies to all commands that have a `--recurse-submodules` option > + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, > + `restore` and `switch`) except `clone` and `ls-files`. > Defaults to false. > > submodule.fetchJobs:: > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule 2020-03-02 4:43 ` Philippe Blain @ 2020-03-03 17:09 ` Damien Robert 0 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:09 UTC (permalink / raw) To: Philippe Blain; +Cc: git From Philippe Blain, Sun 01 Mar 2020 at 23:43:35 (-0500) : > I’d also add the same list to the "Implementation details" section of the gitsubmodules guide [1], which just mentions `checkout` > at the moment. The implementation details section really is about the behaviour of cloning and checkout. So I just added a link to git-config. ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH 2/4] doc: document --recurse-submodules for reset and restore 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert 2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert @ 2020-02-28 10:35 ` Damien Robert 2020-03-02 4:45 ` Philippe Blain 2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert ` (5 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:35 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 9 +++++++++ 2 files changed, 15 insertions(+) diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..838c0f1101 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the content of all active submodules + according to the commit recorded in the superproject, also setting + the submodules HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..b94b2559c7 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + Using `--recurse-submodules` will update the content of all + restored submodules according to the commit recorded in the + superproject. Local modifications in a restored submodule are + overwritten. If nothing (or `--no-recurse-submodules`) is used, the + work trees of submodules will not be updated. Just like + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore 2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-02 4:45 ` Philippe Blain 2020-03-03 17:26 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Philippe Blain @ 2020-03-02 4:45 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 9 +++++++++ > 2 files changed, 15 insertions(+) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 932080c55d..838c0f1101 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -87,6 +87,12 @@ but carries forward unmerged index entries. > different between `<commit>` and `HEAD`. > If a file that is different between `<commit>` and `HEAD` has local > changes, reset is aborted. > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > + also recursively reset the content of all active submodules > + according to the commit recorded in the superproject, also setting > + the submodules HEAD to be detached at that commit. > — From previous testing I had done, when the submodule is modified (either modified content, new commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed), the submodule is only touched if `--hard` or `--merge` is given, i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given. So this is in line with this option just coming into play "When the working tree is updated", as you wrote. However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though... > > See "Reset, restore and revert" in linkgit:git[1] for the differences > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt > index 5bf60d4943..b94b2559c7 100644 > --- a/Documentation/git-restore.txt > +++ b/Documentation/git-restore.txt > @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details. > patterns and unconditionally restores any files in > `<pathspec>`. > > +--recurse-submodules:: > +--no-recurse-submodules:: > + Using `--recurse-submodules` will update the content of all > + restored submodules according to the commit recorded in the > + superproject. I’d phrase it more like so : If `<pathspec>` names a submodule and the restore location includes the working tree, the submodule will only be updated if this option is given, in which case it’s working tree will be restored to the commit recorded in the superproject at the tree-ish given as the restore source. This makes it clearer that `git restore -- submodule` does nothing, and one has to say `git restore --recurse-submodules -- submodule` for the submodule working tree to be updated. > Local modifications in a restored submodule are > + overwritten. If nothing (or `--no-recurse-submodules`) is used, the > + work trees of submodules will not be updated. Just like > + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > + In fact `git submodule` does not unconditionally detach the submodules HEAD (if `git submodule update` is invoked and a branch is checked out in the submodule that points to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch stays checked out unless `--force` is given.) So I would instead link to `checkout`, which does unconditionally detach the submodules HEAD. > --overlay:: > --no-overlay:: > In overlay mode, the command never removes files when > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore 2020-03-02 4:45 ` Philippe Blain @ 2020-03-03 17:26 ` Damien Robert 2020-03-06 4:16 ` Philippe Blain 0 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:26 UTC (permalink / raw) To: Philippe Blain; +Cc: git From Philippe Blain, Sun 01 Mar 2020 at 23:45:02 (-0500) : > > From previous testing I had done, when the submodule is modified (either modified content, > new commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed), > the submodule is only touched if `--hard` or `--merge` is given, > i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given. > So this is in line with this option just coming into play "When the working tree is updated", as you wrote. Yes essentially reset.c only update the value of submodule.recurse according to --recurse-submodules. Then it is 'unpack-trees.c' that handle recursive submodules. > However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if > `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though... Good question... > > + work trees of submodules will not be updated. Just like > > + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > In fact `git submodule` does not unconditionally detach the submodules HEAD > (if `git submodule update` is invoked and a branch is checked out in the submodule that points > to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch > stays checked out unless `--force` is given.) So I would instead link to `checkout`, > which does unconditionally detach the submodules HEAD. Ok. I copied the above line from git-switch[1]. Should I also update it? git-checkout[1] also says that git-submodule will detach HEAD by the way. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore 2020-03-03 17:26 ` Damien Robert @ 2020-03-06 4:16 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-06 4:16 UTC (permalink / raw) To: Damien Robert; +Cc: git > Le 3 mars 2020 à 12:26, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > >>> + work trees of submodules will not be updated. Just like >>> + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > >> In fact `git submodule` does not unconditionally detach the submodules HEAD >> (if `git submodule update` is invoked and a branch is checked out in the submodule that points >> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch >> stays checked out unless `--force` is given.) So I would instead link to `checkout`, >> which does unconditionally detach the submodules HEAD. > > Ok. I copied the above line from git-switch[1]. Should I also update it? > git-checkout[1] also says that git-submodule will detach HEAD by the way. I would say yes: git-switch(1) should be updated to refer to git-checkout(1) instead of git-submodule(1), and git-checkout(1) should drop the reference to git-submodule(1) and just say that it will detach the submodule HEAD. Maybe in a separate patch before this one ? ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert 2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert 2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-02-28 10:35 ` Damien Robert 2020-03-02 4:45 ` Philippe Blain 2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert ` (4 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:35 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..f4edc6cad0 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -62,6 +62,12 @@ submodule.recurse:: applies to all commands that have a `--recurse-submodules` option (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. + When set to true, it can be deactivated by calling + `--no-recurse-submodules`. But note that since `submodule.recurse` + also applies to internal calls to git commands (issued by other git + commands), adding `--no-recurse-submodules` might not be enough to + completely turn off the effect of that config. A solution is to use + `git -c submodule.recurse=0` instead. Defaults to false. submodule.fetchJobs:: -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely 2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert @ 2020-03-02 4:45 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-02 4:45 UTC (permalink / raw) To: Damien Robert, git Again, the commit title has the option name backwards : s/recurse.submodule/submodule.recurse/ > Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> I think the commit message for this one could be more detailed (even if it would say something very similar to the text added to the doc). I think it could be made clearer, for example, that the `-c submodule.recurse=0` is especially useful to deactivate the config when calling commands that do *not* have a `--recurse-submodules` flag, but that internally call other commands that do support that flag. > --- > Documentation/config/submodule.txt | 6 ++++++ > 1 file changed, 6 insertions(+) > > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt > index 5962f41ead..f4edc6cad0 100644 > --- a/Documentation/config/submodule.txt > +++ b/Documentation/config/submodule.txt > @@ -62,6 +62,12 @@ submodule.recurse:: > applies to all commands that have a `--recurse-submodules` option > (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, > `restore` and `switch`) except `clone` and `ls-files`. > + When set to true, it can be deactivated by calling > + `--no-recurse-submodules`. I’d say "can be deactivated for a specific call by adding --no-recurse-submodules." > But note that since `submodule.recurse` > + also applies to internal calls to git commands (issued by other git > + commands), We tend to capitalize "Git" when talking about the system as a whole. > adding `--no-recurse-submodules` might not be enough to > + completely turn off the effect of that config. A solution is to use > + `git -c submodule.recurse=0` instead. > Defaults to false. Personally I’d let "Defaults to false" just after the list of affected commands. > > submodule.fetchJobs:: > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (2 preceding siblings ...) 2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert @ 2020-02-28 10:35 ` Damien Robert 2020-03-02 4:46 ` Philippe Blain 2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (3 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:35 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The default value also depends on the value of submodule.recurse Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/fetch.txt | 6 ++++-- Documentation/config/push.txt | 3 +++ 2 files changed, 7 insertions(+), 2 deletions(-) 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'. -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules 2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert @ 2020-03-02 4:46 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-02 4:46 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert The commit message title mentions fetch and pull but the patch also talks about push, maybe add that to the title ? > Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > The default value also depends on the value of submodule.recurse > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/config/fetch.txt | 6 ++++-- > Documentation/config/push.txt | 3 +++ > 2 files changed, 7 insertions(+), 2 deletions(-) > > 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’. For such a change to the doc, I’d expect the commit message to point to the relevant part of the code that supports the behaviour that is being described, or to the specific test that enforces this behaviour (I briefly looked at t5526 but couldn’t spot one). If such a test is missing it would be good to add it. > > 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’. Same thing here. Also, I do not think it’s good UI that setting ‘submodule,recurse’ to true will make ‘push' default to ‘on-demand’ but will make ‘fetch’ unconditionally fetch, but I guess that would be for another series... > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 0/4] doc: --recurse-submodules 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (3 preceding siblings ...) 2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert @ 2020-02-28 10:44 ` Damien Robert 2020-03-03 5:18 ` Philippe Blain 2020-03-02 4:47 ` Philippe Blain ` (2 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-02-28 10:44 UTC (permalink / raw) To: git, Philippe Blain Note that git-switch.txt states that Using `--recurse-submodules` will update the content of all initialized submodules according to the commit recorded in the superproject. but actually only 'active' submodules will be updated. Should I also update the doc? It is already stated in `gitsubmodules(7)` that only 'active' submodules are considered for recursion. -- Damien Robert http://www.normalesup.org/~robert/pro ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 0/4] doc: --recurse-submodules 2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert @ 2020-03-03 5:18 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-03 5:18 UTC (permalink / raw) To: Damien Robert; +Cc: git > Le 28 févr. 2020 à 05:44, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Note that git-switch.txt states that > Using `--recurse-submodules` will update the content of all > initialized submodules according to the commit recorded in the > superproject. > but actually only 'active' submodules will be updated. Technically that’s true, but I’d say that in a "simple" workflow (you clone a superproject then do `git submodule update --init`, then maybe set `submodule.recurse` to true), then being active and being initialized are equivalent. So I don’t think it’s that big of an issue. In any case, if such a change is made, the doc for all commands that have the flag should be revised, as both "initialized" (grep, checkout, switch, read-tree) and "populated" (fetch, pull) seems to be used currently. > > Should I also update the doc? It is already stated in `gitsubmodules(7)` > that only 'active' submodules are considered for recursion. > > -- > Damien Robert > http://www.normalesup.org/~robert/pro ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH 0/4] doc: --recurse-submodules 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (4 preceding siblings ...) 2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert @ 2020-03-02 4:47 ` Philippe Blain 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert 7 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-02 4:47 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert Hi Damien, > Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > This series add some extra documentation on --recurse-submodules. > > Damien Robert (4): > doc: list all commands affected by recurse.submodule > doc: document --recurse-submodules for reset and restore > doc: explain how to deactivate recurse.submodule completely > doc: be more precise on (fetch|pull).recurseSubmodules > > Documentation/config/fetch.txt | 6 ++++-- > Documentation/config/push.txt | 3 +++ > Documentation/config/submodule.txt | 11 +++++++++-- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 9 +++++++++ > 5 files changed, 31 insertions(+), 4 deletions(-) Thanks a lot for working on that! Cheers, Philippe. > > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v2 0/5] doc: --recurse-submodules 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (5 preceding siblings ...) 2020-03-02 4:47 ` Philippe Blain @ 2020-03-03 17:07 ` Damien Robert 2020-03-03 17:07 ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert ` (4 more replies) 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert 7 siblings, 5 replies; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Incorporated the comments of Philippe Blain. Other changes since v1: - Patch 4: also updated a little the man page of git fetch and git pull. - Added a new patch to refer to 'active' submodules. Damien Robert (5): doc: list all commands affected by submodule.recurse doc: document --recurse-submodules for reset and restore doc: explain how to deactivate recurse.submodule completely doc: be more precise on (fetch|push).recurseSubmodules doc: --recurse-submodules only apply to active submodules Documentation/config/fetch.txt | 6 ++++-- Documentation/config/push.txt | 3 +++ Documentation/config/submodule.txt | 12 ++++++++++-- Documentation/fetch-options.txt | 9 +++++---- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-pull.txt | 5 ++--- Documentation/git-read-tree.txt | 2 +- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 10 ++++++++++ Documentation/git-switch.txt | 2 +- Documentation/gitsubmodules.txt | 3 ++- 12 files changed, 46 insertions(+), 16 deletions(-) -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v2 1/5] doc: list all commands affected by submodule.recurse 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert @ 2020-03-03 17:07 ` Damien Robert 2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert ` (3 subsequent siblings) 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- Documentation/gitsubmodules.txt | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert 2020-03-03 17:07 ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert @ 2020-03-03 17:07 ` Damien Robert 2020-03-03 21:54 ` Junio C Hamano 2020-03-06 4:16 ` Philippe Blain 2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert ` (2 subsequent siblings) 4 siblings, 2 replies; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 10 ++++++++++ 2 files changed, 16 insertions(+) diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..838c0f1101 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the content of all active submodules + according to the commit recorded in the superproject, also setting + the submodules HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..5036f91132 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names a submodule and the restore location includes + the working tree, the submodule will only be updated if this option + is given, in which case it's working tree will be restored to the + commit recorded in the superproject, and it's local modifications + overwritten. If nothing (or `--no-recurse-submodules`) is used, + the work trees of submodules will not be updated. Just like + linkgit:git-checkout[1], this will detach `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore 2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-03 21:54 ` Junio C Hamano 2020-03-06 4:16 ` Philippe Blain 1 sibling, 0 replies; 69+ messages in thread From: Junio C Hamano @ 2020-03-03 21:54 UTC (permalink / raw) To: Damien Robert; +Cc: git, Philippe Blain, Damien Robert Damien Robert <damien.olivier.robert@gmail.com> writes: > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > +... > > +--recurse-submodules:: > +--no-recurse-submodules:: > + If `<pathspec>` names a submodule and the restore location includes > +... Hmph, this inconsistency across files is a bit unfortunate. I think (please somebody correct me from sideways) we have been moving towards using the "--[no-]option-name", so we would want to clean up the latter (together with the "--[no-]overlay" entry in the same file, with which the above tries to be consistent) sometime later when the dust settles, iow, not as a part of this series. > + is given, in which case it's working tree will be restored to the > + commit recorded in the superproject, and it's local modifications > + overwritten. If nothing (or `--no-recurse-submodules`) is used, > + the work trees of submodules will not be updated. Just like > + linkgit:git-checkout[1], this will detach `HEAD` of the submodule. > + > --overlay:: > --no-overlay:: > In overlay mode, the command never removes files when ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore 2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-03-03 21:54 ` Junio C Hamano @ 2020-03-06 4:16 ` Philippe Blain 1 sibling, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-06 4:16 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 3 mars 2020 à 12:07, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 10 ++++++++++ > 2 files changed, 16 insertions(+) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 932080c55d..838c0f1101 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -87,6 +87,12 @@ but carries forward unmerged index entries. > different between `<commit>` and `HEAD`. > If a file that is different between `<commit>` and `HEAD` has local > changes, reset is aborted. > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > + also recursively reset the content of all active submodules > + according to the commit recorded in the superproject, also setting > + the submodules HEAD to be detached at that commit. > — Maybe "working tree" instead of "content" ? > > See "Reset, restore and revert" in linkgit:git[1] for the differences > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt > index 5bf60d4943..5036f91132 100644 > --- a/Documentation/git-restore.txt > +++ b/Documentation/git-restore.txt > @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details. > patterns and unconditionally restores any files in > `<pathspec>`. > > +--recurse-submodules:: > +--no-recurse-submodules:: > + If `<pathspec>` names a submodule and the restore location includes > + the working tree, the submodule will only be updated if this option > + is given, in which case it's working tree will be restored to the > + commit recorded in the superproject, and it's local modifications > + overwritten. If nothing (or `--no-recurse-submodules`) is used, > + the work trees of submodules will not be updated. Just like > + linkgit:git-checkout[1], this will detach `HEAD` of the submodule. > + both "it's" should be "its". In fact I'd personally prefer "any local modifications" instead of "its local modifications" ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert 2020-03-03 17:07 ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-03 17:07 ` Damien Robert 2020-03-03 21:57 ` Junio C Hamano 2020-03-03 22:04 ` Damien Robert 2020-03-03 17:07 ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-03-03 17:07 ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert 4 siblings, 2 replies; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..74e691a487 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -63,6 +63,13 @@ submodule.recurse:: (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated by calling + `--no-recurse-submodules`. Note that some Git commands without this + option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + since `submodule.recurse`. In this case a solution is to temporary + change the configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely 2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert @ 2020-03-03 21:57 ` Junio C Hamano 2020-03-03 22:05 ` Robert P. J. Day 2020-03-03 22:04 ` Damien Robert 1 sibling, 1 reply; 69+ messages in thread From: Junio C Hamano @ 2020-03-03 21:57 UTC (permalink / raw) To: Damien Robert; +Cc: git, Philippe Blain, Damien Robert Damien Robert <damien.olivier.robert@gmail.com> writes: > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/config/submodule.txt | 7 +++++++ > 1 file changed, 7 insertions(+) > > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt > index 5962f41ead..74e691a487 100644 > --- a/Documentation/config/submodule.txt > +++ b/Documentation/config/submodule.txt > @@ -63,6 +63,13 @@ submodule.recurse:: > (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, > `restore` and `switch`) except `clone` and `ls-files`. > Defaults to false. > + When set to true, it can be deactivated by calling > + `--no-recurse-submodules`. Note that some Git commands without this You do not "call" an option [*1*]. Perhaps "... can be overriden by passing the `--no-recurse-submodules` option from the command line." > + option may call some of the above commands affected by > + `submodule.recurse`; for instance `git remote update` will call > + `git fetch` but does not have a `--no-recurse-submodules` option. > + since `submodule.recurse`. In this case a solution is to temporary > + change the configuration value by using `git -c submodule.recurse=0`. A good piece of advice. [Footnote] *1* ... unless you are in a different business, that is ;-). ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely 2020-03-03 21:57 ` Junio C Hamano @ 2020-03-03 22:05 ` Robert P. J. Day 0 siblings, 0 replies; 69+ messages in thread From: Robert P. J. Day @ 2020-03-03 22:05 UTC (permalink / raw) To: Junio C Hamano; +Cc: Damien Robert, git, Philippe Blain, Damien Robert On Tue, 3 Mar 2020, Junio C Hamano wrote: > Damien Robert <damien.olivier.robert@gmail.com> writes: > > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > > --- > > Documentation/config/submodule.txt | 7 +++++++ > > 1 file changed, 7 insertions(+) > > > > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt > > index 5962f41ead..74e691a487 100644 > > --- a/Documentation/config/submodule.txt > > +++ b/Documentation/config/submodule.txt > > @@ -63,6 +63,13 @@ submodule.recurse:: > > (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, > > `restore` and `switch`) except `clone` and `ls-files`. > > Defaults to false. > > + When set to true, it can be deactivated by calling > > + `--no-recurse-submodules`. Note that some Git commands without this > > You do not "call" an option [*1*]. Perhaps "... can be overriden by > passing the `--no-recurse-submodules` option from the command line." nooooooo ... my biggest gripe with documentation is the unnecessary use of superfluous words. :-) simply, "can be deactivated via the '--no-recurse-submodules' option." no one here's getting paid by the word. rday ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely 2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert 2020-03-03 21:57 ` Junio C Hamano @ 2020-03-03 22:04 ` Damien Robert 2020-03-06 4:16 ` Philippe Blain 1 sibling, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-03 22:04 UTC (permalink / raw) To: git, Philippe Blain From Damien Robert, Tue 03 Mar 2020 at 18:07:38 (+0100) : > + When set to true, it can be deactivated by calling > + `--no-recurse-submodules`. Note that some Git commands without this > + option may call some of the above commands affected by > + `submodule.recurse`; for instance `git remote update` will call > + `git fetch` but does not have a `--no-recurse-submodules` option. > + since `submodule.recurse`. In this case a solution is to temporary ^^^^^^^^^^^^^^^^^^^^^^^^^^ Sorry this is a leftover from a previous formulation, I'll clean that up. > + change the configuration value by using `git -c submodule.recurse=0`. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely 2020-03-03 22:04 ` Damien Robert @ 2020-03-06 4:16 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-06 4:16 UTC (permalink / raw) To: Damien Robert; +Cc: git > Le 3 mars 2020 à 17:04, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > >> + since `submodule.recurse`. In this case a solution is to temporary > ^^^^^^^^^^^^^^^^^^^^^^^^^^ > Sorry this is a leftover from a previous formulation, I'll clean that up. Also, the commit title still has the option name reversed: s/recurse.submodule/submodule.recurse/ ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert ` (2 preceding siblings ...) 2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert @ 2020-03-03 17:07 ` Damien Robert 2020-03-03 22:05 ` Junio C Hamano 2020-03-03 17:07 ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert 4 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert 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(-) 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. + -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-03 17:07 ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-03 22:05 ` Junio C Hamano 2020-03-03 22:12 ` Robert P. J. Day 0 siblings, 1 reply; 69+ messages in thread From: Junio C Hamano @ 2020-03-03 22:05 UTC (permalink / raw) To: Damien Robert; +Cc: git, Philippe Blain, Damien Robert 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]). ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-03 22:05 ` Junio C Hamano @ 2020-03-03 22:12 ` Robert P. J. Day 0 siblings, 0 replies; 69+ messages in thread From: Robert P. J. Day @ 2020-03-03 22:12 UTC (permalink / raw) To: Junio C Hamano; +Cc: Damien Robert, git, Philippe Blain, Damien Robert 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? ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert ` (3 preceding siblings ...) 2020-03-03 17:07 ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-03 17:07 ` Damien Robert 2020-03-06 4:17 ` Philippe Blain 4 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-03 17:07 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/fetch-options.txt | 6 +++--- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-pull.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-switch.txt | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 58972b1a05..ba33009253 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -156,11 +156,11 @@ ifndef::git-pull[] --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of - populated submodules should be fetched too. It can be used as a + active submodules should be fetched too. It can be used as a boolean option to completely disable recursion when set to 'no' or to - unconditionally recurse into all populated submodules when set to + unconditionally recurse into all active submodules when set to 'yes', which is the default when this option is used without any - value. Use 'on-demand' to only recurse into a populated submodule + value. Use 'on-demand' to only recurse into a active 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. By default this uses the fetch.recurseSubmodules value (see diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..3be0a28284 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index ddb6acc025..cdf8e26b47 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -93,7 +93,7 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. This option has no effect diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 47bc4a7061..2285f3729d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,7 +85,7 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[no-]recurse-submodules[=yes|on-demand|no]:: - This option controls if new commits of all populated submodules should + This option controls if new commits of all active submodules should 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. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..aab6856341 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,7 +116,7 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules HEAD to be detached at that commit. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..337852d86b 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is used, the work trees of submodules will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the -- Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules 2020-03-03 17:07 ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert @ 2020-03-06 4:17 ` Philippe Blain 2020-03-20 22:23 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Philippe Blain @ 2020-03-06 4:17 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert In the commit title: s/apply/applies > Le 3 mars 2020 à 12:07, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > The documentation refers to "initialized" or "populated" submodules, > to explain which submodules are affected by '--recurse-submodules', but > the real terminology here is 'active' submodules. Update the > documentation accordingly. Initialized, active and populated, as far as I understand, are three different concepts. - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - My understanding is that "populated" means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - My understanding is that "initialized" (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/fetch-options.txt | 6 +++--- > Documentation/git-checkout.txt | 2 +- > Documentation/git-grep.txt | 2 +- > Documentation/git-pull.txt | 2 +- > Documentation/git-read-tree.txt | 2 +- > Documentation/git-switch.txt | 2 +- > 6 files changed, 8 insertions(+), 8 deletions(-) What about ls-files ? builtin/ls-files.c:231 indicates that it does call submodule.c::is_submodule_active, so its doc should also be updated. > > diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt > index 58972b1a05..ba33009253 100644 > --- a/Documentation/fetch-options.txt > +++ b/Documentation/fetch-options.txt > @@ -156,11 +156,11 @@ ifndef::git-pull[] From what I understand of the code, git-fetch really recurses into *populated* submodules, and does not consult the submodule.active or submodule.<name>.active config settings. If you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain. I tested that setting submodule.<name>.active to false and calling git fetch --recurse-submodules=yes still fetches in the submodule(s). So this should stay as "populated". > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index c8fb995fa7..3be0a28284 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also > > --recurse-submodules:: > --no-recurse-submodules:: > - Using `--recurse-submodules` will update the content of all initialized > + Using `--recurse-submodules` will update the content of all active > submodules according to the commit recorded in the superproject. If > local modifications in a submodule would be overwritten the checkout > will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) That's correct as checkout uses the unpack-trees machinery, which calls submodule_move_head, and submodule_move_head calls is_submodule_active (submodule.c:1894). > diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt > index ddb6acc025..cdf8e26b47 100644 > --- a/Documentation/git-grep.txt > +++ b/Documentation/git-grep.txt > @@ -93,7 +93,7 @@ OPTIONS > with `--no-index`. > > --recurse-submodules:: > - Recursively search in each submodule that has been initialized and > + Recursively search in each submodule that is active and > checked out in the repository. When used in combination with the > <tree> option the prefix of all submodule output will be the name of > the parent project's <tree> object. This option has no effect That's correct (builtin/grep.c:423). > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > index 47bc4a7061..2285f3729d 100644 > --- a/Documentation/git-pull.txt > +++ b/Documentation/git-pull.txt > @@ -85,7 +85,7 @@ OPTIONS > Pass --verbose to git-fetch and git-merge. > > --[no-]recurse-submodules[=yes|on-demand|no]:: > - This option controls if new commits of all populated submodules should > + This option controls if new commits of all active submodules should > 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. That's only partly correct: I tested setting submodule.<name>.active to false and doing git pull --recurse-submodules This does fetches the submodule but does not update its working tree, due to the call to is_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt > index da33f84f33..aab6856341 100644 > --- a/Documentation/git-read-tree.txt > +++ b/Documentation/git-read-tree.txt > @@ -116,7 +116,7 @@ OPTIONS > located in. > > --[no-]recurse-submodules:: > - Using --recurse-submodules will update the content of all initialized > + Using --recurse-submodules will update the content of all active > submodules according to the commit recorded in the superproject by > calling read-tree recursively, also setting the submodules HEAD to be > detached at that commit. `read-tree` is also in the unpack-trees machinery, so that's correct. > diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt > index 197900363b..337852d86b 100644 > --- a/Documentation/git-switch.txt > +++ b/Documentation/git-switch.txt > @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with > --recurse-submodules:: > --no-recurse-submodules:: > Using `--recurse-submodules` will update the content of all > - initialized submodules according to the commit recorded in the > + active submodules according to the commit recorded in the > superproject. If nothing (or `--no-recurse-submodules`) is > used, the work trees of submodules will not be updated. Just > like linkgit:git-submodule[1], this will detach `HEAD` of the `switch` is `checkout <branch>` under the hood, so that's also correct. In light of these facts, I think the commit title should be : doc: --recurse-submodules mostly applies to active submodules ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules 2020-03-06 4:17 ` Philippe Blain @ 2020-03-20 22:23 ` Damien Robert 0 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-20 22:23 UTC (permalink / raw) To: Philippe Blain; +Cc: git From Philippe Blain, Thu 05 Mar 2020 at 23:17:54 (-0500) : > In the commit title: s/apply/applies Oups, missed this one. > Initialized, active and populated, as far as I understand, are three different concepts. [...] > From what I understand of the code, git-fetch really recurses into *populated* submodules, > and does not consult the submodule.active or submodule.<name>.active config settings. > If you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain. > I tested that setting submodule.<name>.active to false and calling > > git fetch --recurse-submodules=yes > > still fetches in the submodule(s). So this should stay as "populated". Thanks for the thorough review! I had tested that `git-pull` was only updating the worktree of active submodules, but missed that it was still fetching non active submodules. In light of this I think this is even more important to mention which command affects which submodules in the doc. > That's only partly correct: I tested setting submodule.<name>.active to false and doing > > git pull --recurse-submodules > > This does fetches the submodule but does not update its working tree, due to the call to > is_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c I still left 'active submodule' here in order to not render the formulation too heavy. Since it is implicit that `pull` goes through fetch, I hope it is clear that the fetching still involves all populated submodules. -- Damien Robert http://www.normalesup.org/~robert/pro ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v3 0/5] doc: --recurse-submodules 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert ` (6 preceding siblings ...) 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-20 21:37 ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert ` (7 more replies) 7 siblings, 8 replies; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert This is v3, incorporating all remarks received: - The typos mistakes mentioned by Robert and Junio. - The main change is patch 5/5 where I incorporated the nice explanations of Philippe Blain. Damien Robert (5): doc: list all commands affected by submodule.recurse doc: document --recurse-submodules for reset and restore doc: explain how to deactivate submodule.recurse completely doc: be more precise on (fetch|push).recurseSubmodules doc: --recurse-submodules mostly only apply to active submodules Documentation/config/fetch.txt | 10 ++++++---- Documentation/config/push.txt | 2 ++ Documentation/config/submodule.txt | 12 ++++++++++-- Documentation/fetch-options.txt | 3 ++- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 5 ++--- Documentation/git-read-tree.txt | 2 +- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 10 ++++++++++ Documentation/git-switch.txt | 2 +- Documentation/gitsubmodules.txt | 3 ++- 13 files changed, 45 insertions(+), 16 deletions(-) -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v3 1/5] doc: list all commands affected by submodule.recurse 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-20 21:37 ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert ` (6 subsequent siblings) 7 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- Documentation/gitsubmodules.txt | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert 2020-03-20 21:37 ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-22 22:36 ` Philippe Blain 2020-03-20 21:37 ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert ` (5 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 10 ++++++++++ 2 files changed, 16 insertions(+) diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..c8623cfc34 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..47f31d4a0f 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names a submodule and the restore location includes + the working tree, the submodule will only be updated if this option + is given, in which case its working tree will be restored to the + commit recorded in the superproject, and any local modifications + overwritten. If nothing (or `--no-recurse-submodules`) is used, + the work trees of submodules will not be updated. Just like + linkgit:git-checkout[1], this will detach `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore 2020-03-20 21:37 ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-22 22:36 ` Philippe Blain 2020-03-25 21:05 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Philippe Blain @ 2020-03-22 22:36 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 10 ++++++++++ > 2 files changed, 16 insertions(+) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 932080c55d..c8623cfc34 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -87,6 +87,12 @@ but carries forward unmerged index entries. > different between `<commit>` and `HEAD`. > If a file that is different between `<commit>` and `HEAD` has local > changes, reset is aborted. > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > + also recursively reset the working tree of all active submodules > + according to the commit recorded in the superproject, also setting > + the submodules HEAD to be detached at that commit. I *think* that should be "the submodules' HEADs" but I'd prefer that a native speaker confirm. > -- > > See "Reset, restore and revert" in linkgit:git[1] for the differences > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt > index 5bf60d4943..47f31d4a0f 100644 > --- a/Documentation/git-restore.txt > +++ b/Documentation/git-restore.txt > @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details. > patterns and unconditionally restores any files in > `<pathspec>`. > > +--recurse-submodules:: > +--no-recurse-submodules:: > + If `<pathspec>` names a submodule and the restore location includes To be consistent with patch 5, I think that should be "names an active submodule". (restore is in the unpack-trees machinery so that would be correct; I checked this behaviour). > + the working tree, the submodule will only be updated if this option > + is given, in which case its working tree will be restored to the > + commit recorded in the superproject, and any local modifications > + overwritten. If nothing (or `--no-recurse-submodules`) is used, > + the work trees of submodules will not be updated. Just like For consistency I'd use "working trees" here also, as in the first sentence. In fact I think it would read better as "submodules working trees will not be updated". ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore 2020-03-22 22:36 ` Philippe Blain @ 2020-03-25 21:05 ` Damien Robert 0 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:05 UTC (permalink / raw) To: Philippe Blain; +Cc: git From Philippe Blain, Sun 22 Mar 2020 at 18:36:23 (-0400) : > > +--[no-]recurse-submodules:: > > + When the working tree is updated, using --recurse-submodules will > > + also recursively reset the working tree of all active submodules > > + according to the commit recorded in the superproject, also setting > > + the submodules HEAD to be detached at that commit. > I *think* that should be "the submodules' HEADs" but I'd prefer that a native speaker confirm. This was copied from read-tree. So I'll update it too in my next reroll. > > + the working tree, the submodule will only be updated if this option > > + is given, in which case its working tree will be restored to the > > + commit recorded in the superproject, and any local modifications > > + overwritten. If nothing (or `--no-recurse-submodules`) is used, > > + the work trees of submodules will not be updated. Just like > For consistency I'd use "working trees" here also, as in the first sentence. > In fact I think it would read better as "submodules working trees will not be updated". Likewise, this was copied from checkout (and switch). I'll update all of them. -- Damien Robert http://www.normalesup.org/~robert/pro ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert 2020-03-20 21:37 ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-20 21:37 ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-22 22:36 ` Philippe Blain 2020-03-20 21:37 ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert ` (4 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..900d374385 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -63,6 +63,13 @@ submodule.recurse:: (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated via the + `--no-recurse-submodules` option. Note that some Git commands + without this option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + In this case a solution is to temporary change the configuration + value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely 2020-03-20 21:37 ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert @ 2020-03-22 22:36 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-22 22:36 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > + When set to true, it can be deactivated via the > + `--no-recurse-submodules` option. Note that some Git commands > + without this option may call some of the above commands affected by For clarity I'd write "some Git commands lacking this option" instead, as "without this option" *could* be interpreted as "invoked without this option". > + `submodule.recurse`; for instance `git remote update` will call > + `git fetch` but does not have a `--no-recurse-submodules` option. > + In this case a solution I'm not sure "solution" is the best word here, maybe: "For these commands a workaround is to temporarily change the configuration..." Note: s/temporary/temporarily/ > is to temporary change the configuration > + value by using `git -c submodule.recurse=0`. ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert ` (2 preceding siblings ...) 2020-03-20 21:37 ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-22 22:37 ` Philippe Blain 2020-03-20 21:37 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert ` (3 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert 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(-) 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. + -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-20 21:37 ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-22 22:37 ` Philippe Blain 2020-03-22 23:01 ` Junio C Hamano 0 siblings, 1 reply; 69+ messages in thread From: Philippe Blain @ 2020-03-22 22:37 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert, Junio C Hamano > 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. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-22 22:37 ` Philippe Blain @ 2020-03-22 23:01 ` Junio C Hamano 2020-03-22 23:21 ` Philippe Blain 0 siblings, 1 reply; 69+ messages in thread From: Junio C Hamano @ 2020-03-22 23:01 UTC (permalink / raw) To: Philippe Blain; +Cc: Damien Robert, git, Damien Robert 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. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-22 23:01 ` Junio C Hamano @ 2020-03-22 23:21 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-22 23:21 UTC (permalink / raw) To: Junio C Hamano; +Cc: Damien Robert, git, Damien Robert > 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). ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert ` (3 preceding siblings ...) 2020-03-20 21:37 ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-20 21:37 ` Damien Robert 2020-03-22 22:38 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert ` (2 subsequent siblings) 7 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-20 21:37 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Some terminology: - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. The --recurse-submodules option mostly affects submodules. An exception is `git fetch` where the option affects populated submodules. As a consequence, in `git pull` the fetch affects populated submodules, but the resulting working tree update only affects active submodules. In the documentation of `git-pull` we only refer to active submodules, since it is implicit that the fetching behaviour is governed by the fetch command. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-switch.txt | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..3be0a28284 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index ddb6acc025..cdf8e26b47 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -93,7 +93,7 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. This option has no effect diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 8461c0e83e..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -148,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 47bc4a7061..2285f3729d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,7 +85,7 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[no-]recurse-submodules[=yes|on-demand|no]:: - This option controls if new commits of all populated submodules should + This option controls if new commits of all active submodules should 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. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..aab6856341 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,7 +116,7 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules HEAD to be detached at that commit. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..337852d86b 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is used, the work trees of submodules will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the -- Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules 2020-03-20 21:37 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert @ 2020-03-22 22:38 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-22 22:38 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit in the title, I'd drop the "only" "mostly only apply" -> "mostly applies" > : > > The documentation refers to "initialized" or "populated" submodules, > to explain which submodules are affected by '--recurse-submodules', but > the real terminology here is 'active' submodules. Update the > documentation accordingly. > > Some terminology: > - Active is defined in gitsubmodules(7), it only involves the > configuration variables 'submodule.active', 'submodule.<name>.active' > and 'submodule.<name>.url'. The function > submodule.c::is_submodule_active checks that a submodule is active. > - Populated means that the submodule's working tree is present (and the > gitfile correctly points to the submodule repository), i.e. either the > superproject was cloned with ` --recurse-submodules`, or the user ran > `git submodule update --init`, or `git submodule init [<path>]` and > `git submodule update [<path]` missing a closing '>' here (my mistake). > separately which populated the > submodule working tree. This does not involve the 3 configuration > variables above. > - Initialized (at least in the context of the man pages involved in this > patch) means both "populated" and "active" as defined above, i.e. what > `git submodule update --init` does. > > The --recurse-submodules option mostly affects submodules. I think you meant "mostly affects active submodules" here, right? > An exception > is `git fetch` where the option affects populated submodules. > As a consequence, in `git pull` the fetch affects populated submodules, > but the resulting working tree update only affects active submodules. > > In the documentation of `git-pull` we only refer to active submodules, > since it is implicit that the fetching behaviour is governed by the > fetch command. This last paragraph is not a description of the current state of the code base, but describes the changes introduced by this patch. As such, it's customary to write it in the imperative mode. A simple suggestion to fix that: s/we/let's/ > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > index 47bc4a7061..2285f3729d 100644 > --- a/Documentation/git-pull.txt > +++ b/Documentation/git-pull.txt > @@ -85,7 +85,7 @@ OPTIONS > Pass --verbose to git-fetch and git-merge. > > --[no-]recurse-submodules[=yes|on-demand|no]:: > - This option controls if new commits of all populated submodules should > + This option controls if new commits of all active submodules should > be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). I understand that the goal here is to make the formulation not too heavy, as you wrote in https://lore.kernel.org/git/20200320222328.lynvrgqc35pvxxnl@doriath/. However I think the formulation is awkward to begin with : commits are "fetched", but commits are not "updated", the submodules working tree are updated. So maybe: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v4 0/5] doc: --recurse-submodules 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert ` (4 preceding siblings ...) 2020-03-20 21:37 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert @ 2020-03-25 21:09 ` Damien Robert 2020-03-25 21:09 ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert ` (4 more replies) 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert 7 siblings, 5 replies; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert No big changes this time, I just incorporated the latest round of remarks. (A big thanks to Philippe Blain for these!) Damien Robert (5): doc: list all commands affected by submodule.recurse doc: document --recurse-submodules for reset and restore doc: explain how to deactivate submodule.recurse completely doc: be more precise on (fetch|push).recurseSubmodules doc: --recurse-submodules mostly applies to active submodules Documentation/config/fetch.txt | 9 +++++---- Documentation/config/push.txt | 2 ++ Documentation/config/submodule.txt | 12 ++++++++++-- Documentation/fetch-options.txt | 3 ++- Documentation/git-checkout.txt | 4 ++-- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 5 +++-- Documentation/git-read-tree.txt | 4 ++-- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 4 ++-- Documentation/gitsubmodules.txt | 3 ++- 13 files changed, 49 insertions(+), 18 deletions(-) -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v4 1/5] doc: list all commands affected by submodule.recurse 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert @ 2020-03-25 21:09 ` Damien Robert 2020-03-25 21:09 ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert ` (3 subsequent siblings) 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- Documentation/gitsubmodules.txt | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert 2020-03-25 21:09 ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert @ 2020-03-25 21:09 ` Damien Robert 2020-03-29 20:34 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert ` (2 subsequent siblings) 4 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Also unify the formulation about --no-submodules for checkout and switch, which we reuse for restore. And correct the formulation about submodules' HEAD in read-tree, which we reuse in reset. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 2 +- 5 files changed, 20 insertions(+), 3 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..140bd3eabb 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) - is used, the work trees of submodules will not be updated. + is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodule. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..807cad4691 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -118,7 +118,7 @@ OPTIONS --[no-]recurse-submodules:: Using --recurse-submodules will update the content of all initialized submodules according to the commit recorded in the superproject by - calling read-tree recursively, also setting the submodules HEAD to be + calling read-tree recursively, also setting the submodules' HEADs to be detached at that commit. --no-sparse-checkout:: diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..d7a09f11a0 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules' HEADs to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..8e3b339802 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names an active submodule and the restore location + includes the working tree, the submodule will only be updated if + this option is given, in which case its working tree will be + restored to the commit recorded in the superproject, and any local + modifications overwritten. If nothing (or + `--no-recurse-submodules`) is used, submodules working trees will + not be updated. Just like linkgit:git-checkout[1], this will detach + `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..79dbc9624d 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with Using `--recurse-submodules` will update the content of all initialized submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is - used, the work trees of submodules will not be updated. Just + used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodules. -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore 2020-03-25 21:09 ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-29 20:34 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-29 20:34 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 25 mars 2020 à 17:09, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Also unify the formulation about --no-submodules that should be '--no-recurse-submodules' > for checkout and > switch, which we reuse for restore. > > And correct the formulation about submodules' HEAD in read-tree, which > we reuse in reset. > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/git-checkout.txt | 2 +- > Documentation/git-read-tree.txt | 2 +- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 11 +++++++++++ > Documentation/git-switch.txt | 2 +- > 5 files changed, 20 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index c8fb995fa7..140bd3eabb 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also > submodules according to the commit recorded in the superproject. If > local modifications in a submodule would be overwritten the checkout > will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) > - is used, the work trees of submodules will not be updated. > + is used, submodules working trees will not be updated. > Just like linkgit:git-submodule[1], this will detach `HEAD` of the > submodule. > > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt > index da33f84f33..807cad4691 100644 > --- a/Documentation/git-read-tree.txt > +++ b/Documentation/git-read-tree.txt > @@ -118,7 +118,7 @@ OPTIONS > --[no-]recurse-submodules:: > Using --recurse-submodules will update the content of all initialized > submodules according to the commit recorded in the superproject by > - calling read-tree recursively, also setting the submodules HEAD to be > + calling read-tree recursively, also setting the submodules' HEADs to be I've rethought about that and I think it should be "submodules' HEAD" (sorry!) > detached at that commit. > > --no-sparse-checkout:: > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 932080c55d..d7a09f11a0 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -87,6 +87,12 @@ but carries forward unmerged index entries. > different between `<commit>` and `HEAD`. > If a file that is different between `<commit>` and `HEAD` has local > changes, reset is aborted. > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > + also recursively reset the working tree of all active submodules > + according to the commit recorded in the superproject, also setting > + the submodules' HEADs to be detached at that commit. same here > -- > > See "Reset, restore and revert" in linkgit:git[1] for the differences > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt > index 5bf60d4943..8e3b339802 100644 > --- a/Documentation/git-restore.txt > +++ b/Documentation/git-restore.txt > @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details. > patterns and unconditionally restores any files in > `<pathspec>`. > > +--recurse-submodules:: > +--no-recurse-submodules:: > + If `<pathspec>` names an active submodule and the restore location > + includes the working tree, the submodule will only be updated if > + this option is given, in which case its working tree will be > + restored to the commit recorded in the superproject, and any local > + modifications overwritten. If nothing (or > + `--no-recurse-submodules`) is used, submodules working trees will > + not be updated. Just like linkgit:git-checkout[1], this will detach > + `HEAD` of the submodule. > + > --overlay:: > --no-overlay:: > In overlay mode, the command never removes files when > diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt > index 197900363b..79dbc9624d 100644 > --- a/Documentation/git-switch.txt > +++ b/Documentation/git-switch.txt > @@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with > Using `--recurse-submodules` will update the content of all > initialized submodules according to the commit recorded in the > superproject. If nothing (or `--no-recurse-submodules`) is > - used, the work trees of submodules will not be updated. Just > + used, submodules working trees will not be updated. Just > like linkgit:git-submodule[1], this will detach `HEAD` of the > submodules. > > -- > Patched on top of v2.26.0 (git version 2.25.2) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert 2020-03-25 21:09 ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-25 21:09 ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-03-25 21:09 ` Damien Robert 2020-03-25 21:09 ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-03-25 21:09 ` [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..d7a63c8c12 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -63,6 +63,13 @@ submodule.recurse:: (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated via the + `--no-recurse-submodules` option. Note that some Git commands + lacking this option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + For these commands a workaround is to temporarily change the + configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert ` (2 preceding siblings ...) 2020-03-25 21:09 ` [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert @ 2020-03-25 21:09 ` Damien Robert 2020-03-29 20:49 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 4 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert 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 | 9 +++++---- Documentation/config/push.txt | 2 ++ Documentation/fetch-options.txt | 3 ++- Documentation/git-pull.txt | 3 +-- 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..cd5b1417c4 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -1,11 +1,12 @@ 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 fetching into a populated submodule when its superproject retrieves a commit that updates the submodule's reference. + Defaults to 'on-demand', or to the value of 'submodule.recurse' if 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. + -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-03-25 21:09 ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-29 20:49 ` Philippe Blain 0 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-03-29 20:49 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert > Le 25 mars 2020 à 17:09, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > 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 | 9 +++++---- > Documentation/config/push.txt | 2 ++ > Documentation/fetch-options.txt | 3 ++- > Documentation/git-pull.txt | 3 +-- > 4 files changed, 10 insertions(+), 7 deletions(-) > > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt > index f11940280f..cd5b1417c4 100644 > --- a/Documentation/config/fetch.txt > +++ b/Documentation/config/fetch.txt > @@ -1,11 +1,12 @@ > 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 fetching into a populated submodule The chosen formulation seems to imply that only for "on-demand" will fetch and pull recursively *fetch* in submodules, which is misleading. I think it might be clearer to just add a sentence at the start : This option controls whether `git fetch` (and the underlying fetch in `git pull`) will recursively fetch into populated submodules. 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 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. > when its superproject retrieves a commit that updates the submodule's > reference. > + Defaults to 'on-demand', or to the value of 'submodule.recurse' if 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. > + > -- > Patched on top of v2.26.0 (git version 2.25.2) > ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert ` (3 preceding siblings ...) 2020-03-25 21:09 ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-03-25 21:09 ` Damien Robert 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-03-25 21:09 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Some terminology: - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path>]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. The --recurse-submodules option mostly affects active submodules. An exception is `git fetch` where the option affects populated submodules. As a consequence, in `git pull --recurse-submodules` the fetch affects populated submodules, but the resulting working tree update only affects active submodules. In the documentation of `git-pull`, let's distinguish between the fetching part which affects populated submodules, and the updating of worktrees, which only affects active submodules. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 6 ++++-- Documentation/git-read-tree.txt | 2 +- Documentation/git-switch.txt | 2 +- 6 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 140bd3eabb..5b697eee1b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index ddb6acc025..cdf8e26b47 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -93,7 +93,7 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. This option has no effect diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 8461c0e83e..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -148,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 47bc4a7061..b336df00c7 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,8 +85,10 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[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-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). + This option controls if new commits of populated submodules should + be fetched, and if the working trees of active submodules should be + 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. + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 807cad4691..a2350994ee 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,7 +116,7 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEADs to be detached at that commit. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 79dbc9624d..3759c3a265 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the -- Patched on top of v2.26.0 (git version 2.25.2) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v5 0/5] doc: --recurse-submodules 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert ` (5 preceding siblings ...) 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert @ 2020-04-05 20:16 ` Damien Robert 2020-04-05 20:16 ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert ` (4 more replies) 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert 7 siblings, 5 replies; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Sorry it took me a while, I have been busy. I incorporated the two remarks by Philippe Blain on v4. We are converging! Damien Robert (5): doc: list all commands affected by submodule.recurse doc: document --recurse-submodules for reset and restore doc: explain how to deactivate submodule.recurse completely doc: be more precise on (fetch|push).recurseSubmodules doc: --recurse-submodules mostly applies to active submodules Documentation/config/fetch.txt | 13 ++++++++----- Documentation/config/push.txt | 2 ++ Documentation/config/submodule.txt | 12 ++++++++++-- Documentation/fetch-options.txt | 3 ++- Documentation/git-checkout.txt | 4 ++-- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 5 +++-- Documentation/git-read-tree.txt | 4 ++-- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 4 ++-- Documentation/gitsubmodules.txt | 3 ++- 13 files changed, 52 insertions(+), 19 deletions(-) -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v5 1/5] doc: list all commands affected by submodule.recurse 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert @ 2020-04-05 20:16 ` Damien Robert 2020-04-05 20:16 ` [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore Damien Robert ` (3 subsequent siblings) 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- Documentation/gitsubmodules.txt | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert 2020-04-05 20:16 ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert @ 2020-04-05 20:16 ` Damien Robert 2020-04-05 20:16 ` [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert ` (2 subsequent siblings) 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Also unify the formulation about --no-recurse-submodules for checkout and switch, which we reuse for restore. And correct the formulation about submodules' HEAD in read-tree, which we reuse in reset. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 2 +- 5 files changed, 20 insertions(+), 3 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..140bd3eabb 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) - is used, the work trees of submodules will not be updated. + is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodule. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..501f2ec375 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -118,7 +118,7 @@ OPTIONS --[no-]recurse-submodules:: Using --recurse-submodules will update the content of all initialized submodules according to the commit recorded in the superproject by - calling read-tree recursively, also setting the submodules HEAD to be + calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. --no-sparse-checkout:: diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..252e2d4e47 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules' HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..8e3b339802 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names an active submodule and the restore location + includes the working tree, the submodule will only be updated if + this option is given, in which case its working tree will be + restored to the commit recorded in the superproject, and any local + modifications overwritten. If nothing (or + `--no-recurse-submodules`) is used, submodules working trees will + not be updated. Just like linkgit:git-checkout[1], this will detach + `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..79dbc9624d 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with Using `--recurse-submodules` will update the content of all initialized submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is - used, the work trees of submodules will not be updated. Just + used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodules. -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert 2020-04-05 20:16 ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-04-05 20:16 ` [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-04-05 20:16 ` Damien Robert 2020-04-05 20:16 ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-04-05 20:16 ` [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..d7a63c8c12 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -63,6 +63,13 @@ submodule.recurse:: (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated via the + `--no-recurse-submodules` option. Note that some Git commands + lacking this option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + For these commands a workaround is to temporarily change the + configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert ` (2 preceding siblings ...) 2020-04-05 20:16 ` [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert @ 2020-04-05 20:16 ` Damien Robert 2020-04-05 21:57 ` Junio C Hamano 2020-04-05 20:16 ` [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 4 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert 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 | 13 ++++++++----- Documentation/config/push.txt | 2 ++ Documentation/fetch-options.txt | 3 ++- Documentation/git-pull.txt | 3 +-- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..4114af4b3b 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -1,11 +1,14 @@ fetch.recurseSubmodules:: - This option can be either set to a boolean value or to 'on-demand'. + This option controls whether `git fetch` (and the underlying fetch + in `git pull`) will recursively fetch into populated submodules. + 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 - when its superproject retrieves a commit that updates the submodule's + 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. + Defaults to 'on-demand', or to the value of 'submodule.recurse' if 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 00d03ec8c3..833f935cd0 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]). endif::git-pull[] -j:: 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. + -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-05 20:16 ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-04-05 21:57 ` Junio C Hamano 2020-04-06 13:49 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Junio C Hamano @ 2020-04-05 21:57 UTC (permalink / raw) To: Damien Robert; +Cc: git, Philippe Blain, Damien Robert Damien Robert <damien.olivier.robert@gmail.com> writes: > 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 | 13 ++++++++----- > Documentation/config/push.txt | 2 ++ > Documentation/fetch-options.txt | 3 ++- > Documentation/git-pull.txt | 3 +-- > 4 files changed, 13 insertions(+), 8 deletions(-) > > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt > index f11940280f..4114af4b3b 100644 > --- a/Documentation/config/fetch.txt > +++ b/Documentation/config/fetch.txt > @@ -1,11 +1,14 @@ > fetch.recurseSubmodules:: > - This option can be either set to a boolean value or to 'on-demand'. > + This option controls whether `git fetch` (and the underlying fetch > + in `git pull`) will recursively fetch into populated submodules. > + 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 > - when its superproject retrieves a commit that updates the submodule's > + 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 Why did you lose quotes around on-demand on this line? Shouldn't it be typeset the same way as the other one in the sentence "Defaults to ..."? > + pull will only recurse into a populated submodule when its > + superproject retrieves a commit that updates the submodule's > reference. > + Defaults to 'on-demand', or to the value of 'submodule.recurse' if set. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-05 21:57 ` Junio C Hamano @ 2020-04-06 13:49 ` Damien Robert 2020-04-06 17:56 ` Junio C Hamano 0 siblings, 1 reply; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:49 UTC (permalink / raw) To: Junio C Hamano; +Cc: git, Philippe Blain From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) : > Why did you lose quotes around on-demand on this line? Shouldn't it > be typeset the same way as the other one in the sentence "Defaults > to ..."? Yes it should, sorry it's my mistake, I'll send a new version. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-06 13:49 ` Damien Robert @ 2020-04-06 17:56 ` Junio C Hamano 2020-04-06 18:42 ` Damien Robert 0 siblings, 1 reply; 69+ messages in thread From: Junio C Hamano @ 2020-04-06 17:56 UTC (permalink / raw) To: Damien Robert; +Cc: git, Philippe Blain Damien Robert <damien.olivier.robert@gmail.com> writes: > From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) : >> Why did you lose quotes around on-demand on this line? Shouldn't it >> be typeset the same way as the other one in the sentence "Defaults >> to ..."? > > Yes it should, sorry it's my mistake, I'll send a new version. Thanks. You may want to wait a bit so that (1) others can spot similar mistakes, if any, in the version on the list and (2) you yourself find some similar errors while waiting for others. ^ permalink raw reply [flat|nested] 69+ messages in thread
* Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-06 17:56 ` Junio C Hamano @ 2020-04-06 18:42 ` Damien Robert 0 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 18:42 UTC (permalink / raw) To: Junio C Hamano; +Cc: git, Philippe Blain From Junio C Hamano, Mon 06 Apr 2020 at 10:56:49 (-0700) : > Thanks. You may want to wait a bit so that (1) others can spot > similar mistakes, if any, in the version on the list and (2) you > yourself find some similar errors while waiting for others. Well this was mainly the only change compared to v4 which was sent 10 days ago. This change was suggested by Philippe Blain, so it has already been read by him, me, you, and then me again when I sent v6 and checked carefully I did not miss another quote around 'on-demand'. Hopefully that will be enough :) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert ` (3 preceding siblings ...) 2020-04-05 20:16 ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-04-05 20:16 ` Damien Robert 4 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-05 20:16 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Some terminology: - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path>]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. The --recurse-submodules option mostly affects active submodules. An exception is `git fetch` where the option affects populated submodules. As a consequence, in `git pull --recurse-submodules` the fetch affects populated submodules, but the resulting working tree update only affects active submodules. In the documentation of `git-pull`, let's distinguish between the fetching part which affects populated submodules, and the updating of worktrees, which only affects active submodules. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 6 ++++-- Documentation/git-read-tree.txt | 2 +- Documentation/git-switch.txt | 2 +- 6 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 140bd3eabb..5b697eee1b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index ddb6acc025..cdf8e26b47 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -93,7 +93,7 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. This option has no effect diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 8461c0e83e..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -148,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 47bc4a7061..b336df00c7 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,8 +85,10 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[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-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). + This option controls if new commits of populated submodules should + be fetched, and if the working trees of active submodules should be + 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. + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 501f2ec375..5fa8bab64c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,7 +116,7 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 79dbc9624d..3759c3a265 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v6 0/5] doc: --recurse-submodules 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert ` (6 preceding siblings ...) 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-06 13:57 ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert ` (5 more replies) 7 siblings, 6 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Fix typo mentioned by Junio. Damien Robert (5): doc: list all commands affected by submodule.recurse doc: document --recurse-submodules for reset and restore doc: explain how to deactivate submodule.recurse completely doc: be more precise on (fetch|push).recurseSubmodules doc: --recurse-submodules mostly applies to active submodules Documentation/config/fetch.txt | 13 ++++++++----- Documentation/config/push.txt | 2 ++ Documentation/config/submodule.txt | 12 ++++++++++-- Documentation/fetch-options.txt | 3 ++- Documentation/git-checkout.txt | 4 ++-- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 5 +++-- Documentation/git-read-tree.txt | 4 ++-- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 4 ++-- Documentation/gitsubmodules.txt | 3 ++- 13 files changed, 52 insertions(+), 19 deletions(-) -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply [flat|nested] 69+ messages in thread
* [PATCH v6 1/5] doc: list all commands affected by submodule.recurse 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-06 13:57 ` [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore Damien Robert ` (4 subsequent siblings) 5 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Note that `ls-files` is not affected, even though it has a `--recurse-submodules` option, so list it as an exception too. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 5 +++-- Documentation/gitsubmodules.txt | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index b33177151c..5962f41ead 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -59,8 +59,9 @@ submodule.active:: submodule.recurse:: Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option, - except `clone`. + applies to all commands that have a `--recurse-submodules` option + (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, + `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. submodule.fetchJobs:: diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index c476f891b5..f9f4e65c9e 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse into submodules. The 'init' and 'update' subcommands of 'git submodule' will maintain submodules checked out and at an appropriate revision in your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +'checkout' recursing into submodules (note that 'submodule.recurse' also +affects other git commands, see linkgit:git-config[1] for a complete list). SEE ALSO -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-06 13:57 ` [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert ` (3 subsequent siblings) 5 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Also unify the formulation about --no-recurse-submodules for checkout and switch, which we reuse for restore. And correct the formulation about submodules' HEAD in read-tree, which we reuse in reset. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-read-tree.txt | 2 +- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 11 +++++++++++ Documentation/git-switch.txt | 2 +- 5 files changed, 20 insertions(+), 3 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c8fb995fa7..140bd3eabb 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) - is used, the work trees of submodules will not be updated. + is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodule. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index da33f84f33..501f2ec375 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -118,7 +118,7 @@ OPTIONS --[no-]recurse-submodules:: Using --recurse-submodules will update the content of all initialized submodules according to the commit recorded in the superproject by - calling read-tree recursively, also setting the submodules HEAD to be + calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. --no-sparse-checkout:: diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..252e2d4e47 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the working tree of all active submodules + according to the commit recorded in the superproject, also setting + the submodules' HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..8e3b339802 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + If `<pathspec>` names an active submodule and the restore location + includes the working tree, the submodule will only be updated if + this option is given, in which case its working tree will be + restored to the commit recorded in the superproject, and any local + modifications overwritten. If nothing (or + `--no-recurse-submodules`) is used, submodules working trees will + not be updated. Just like linkgit:git-checkout[1], this will detach + `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 197900363b..79dbc9624d 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with Using `--recurse-submodules` will update the content of all initialized submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is - used, the work trees of submodules will not be updated. Just + used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the submodules. -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-04-06 13:57 ` [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-06 13:57 ` [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert ` (2 subsequent siblings) 5 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/config/submodule.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index 5962f41ead..d7a63c8c12 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -63,6 +63,13 @@ submodule.recurse:: (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. + When set to true, it can be deactivated via the + `--no-recurse-submodules` option. Note that some Git commands + lacking this option may call some of the above commands affected by + `submodule.recurse`; for instance `git remote update` will call + `git fetch` but does not have a `--no-recurse-submodules` option. + For these commands a workaround is to temporarily change the + configuration value by using `git -c submodule.recurse=0`. submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert ` (2 preceding siblings ...) 2020-04-06 13:57 ` [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-06 13:57 ` [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 2020-04-16 13:09 ` [PATCH v6 0/5] doc: --recurse-submodules Philippe Blain 5 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert 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 | 13 ++++++++----- Documentation/config/push.txt | 2 ++ Documentation/fetch-options.txt | 3 ++- Documentation/git-pull.txt | 3 +-- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index f11940280f..b1a9b1461d 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -1,11 +1,14 @@ fetch.recurseSubmodules:: - This option can be either set to a boolean value or to 'on-demand'. + This option controls whether `git fetch` (and the underlying fetch + in `git pull`) will recursively fetch into populated submodules. + 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 - when its superproject retrieves a commit that updates the submodule's + 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. + Defaults to 'on-demand', or to the value of 'submodule.recurse' if 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 00d03ec8c3..833f935cd0 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]). endif::git-pull[] -j:: 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. + -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert ` (3 preceding siblings ...) 2020-04-06 13:57 ` [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert @ 2020-04-06 13:57 ` Damien Robert 2020-04-16 13:09 ` [PATCH v6 0/5] doc: --recurse-submodules Philippe Blain 5 siblings, 0 replies; 69+ messages in thread From: Damien Robert @ 2020-04-06 13:57 UTC (permalink / raw) To: git, Philippe Blain; +Cc: Damien Robert The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Some terminology: - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path>]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. The --recurse-submodules option mostly affects active submodules. An exception is `git fetch` where the option affects populated submodules. As a consequence, in `git pull --recurse-submodules` the fetch affects populated submodules, but the resulting working tree update only affects active submodules. In the documentation of `git-pull`, let's distinguish between the fetching part which affects populated submodules, and the updating of worktrees, which only affects active submodules. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> --- Documentation/git-checkout.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-ls-files.txt | 2 +- Documentation/git-pull.txt | 6 ++++-- Documentation/git-read-tree.txt | 2 +- Documentation/git-switch.txt | 2 +- 6 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 140bd3eabb..5b697eee1b 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also --recurse-submodules:: --no-recurse-submodules:: - Using `--recurse-submodules` will update the content of all initialized + Using `--recurse-submodules` will update the content of all active submodules according to the commit recorded in the superproject. If local modifications in a submodule would be overwritten the checkout will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`) diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index ddb6acc025..cdf8e26b47 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -93,7 +93,7 @@ OPTIONS with `--no-index`. --recurse-submodules:: - Recursively search in each submodule that has been initialized and + Recursively search in each submodule that is active and checked out in the repository. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. This option has no effect diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 8461c0e83e..3cb2ebb438 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -148,7 +148,7 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. + Recursively calls ls-files on each active submodule in the repository. Currently there is only support for the --cached mode. --abbrev[=<n>]:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 47bc4a7061..b336df00c7 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -85,8 +85,10 @@ OPTIONS Pass --verbose to git-fetch and git-merge. --[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-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]). + This option controls if new commits of populated submodules should + be fetched, and if the working trees of active submodules should be + 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. + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 501f2ec375..5fa8bab64c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -116,7 +116,7 @@ OPTIONS located in. --[no-]recurse-submodules:: - Using --recurse-submodules will update the content of all initialized + Using --recurse-submodules will update the content of all active submodules according to the commit recorded in the superproject by calling read-tree recursively, also setting the submodules' HEAD to be detached at that commit. diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index 79dbc9624d..3759c3a265 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with --recurse-submodules:: --no-recurse-submodules:: Using `--recurse-submodules` will update the content of all - initialized submodules according to the commit recorded in the + active submodules according to the commit recorded in the superproject. If nothing (or `--no-recurse-submodules`) is used, submodules working trees will not be updated. Just like linkgit:git-submodule[1], this will detach `HEAD` of the -- Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0) ^ permalink raw reply related [flat|nested] 69+ messages in thread
* Re: [PATCH v6 0/5] doc: --recurse-submodules 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert ` (4 preceding siblings ...) 2020-04-06 13:57 ` [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert @ 2020-04-16 13:09 ` Philippe Blain 5 siblings, 0 replies; 69+ messages in thread From: Philippe Blain @ 2020-04-16 13:09 UTC (permalink / raw) To: Damien Robert; +Cc: git, Damien Robert, Junio C Hamano Hi Damien, > Le 6 avr. 2020 à 09:57, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Fix typo mentioned by Junio. > > Damien Robert (5): > doc: list all commands affected by submodule.recurse > doc: document --recurse-submodules for reset and restore > doc: explain how to deactivate submodule.recurse completely > doc: be more precise on (fetch|push).recurseSubmodules > doc: --recurse-submodules mostly applies to active submodules A little late to the game, but consider this series Reviewed-by: Philippe Blain <levraiphilippeblain@gmail.com> (It's my first review, so I don't know if I should explicitly add that to each patch?...) Anyway, thanks a lot for putting time into this! Philippe. ^ permalink raw reply [flat|nested] 69+ messages in thread
end of thread, other threads:[~2020-04-16 13:09 UTC | newest] Thread overview: 69+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert 2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert 2020-03-02 4:43 ` Philippe Blain 2020-03-03 17:09 ` Damien Robert 2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert 2020-03-02 4:45 ` Philippe Blain 2020-03-03 17:26 ` Damien Robert 2020-03-06 4:16 ` Philippe Blain 2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert 2020-03-02 4:45 ` Philippe Blain 2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert 2020-03-02 4:46 ` Philippe Blain 2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert 2020-03-03 5:18 ` Philippe Blain 2020-03-02 4:47 ` Philippe Blain 2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert 2020-03-03 17:07 ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-03-03 21:54 ` Junio C Hamano 2020-03-06 4:16 ` Philippe Blain 2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert 2020-03-03 21:57 ` Junio C Hamano 2020-03-03 22:05 ` Robert P. J. Day 2020-03-03 22:04 ` Damien Robert 2020-03-06 4:16 ` Philippe Blain 2020-03-03 17:07 ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-03-03 22:05 ` Junio C Hamano 2020-03-03 22:12 ` Robert P. J. Day 2020-03-03 17:07 ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert 2020-03-06 4:17 ` Philippe Blain 2020-03-20 22:23 ` Damien Robert 2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert 2020-03-20 21:37 ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-20 21:37 ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-03-22 22:36 ` Philippe Blain 2020-03-25 21:05 ` Damien Robert 2020-03-20 21:37 ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert 2020-03-22 22:36 ` Philippe Blain 2020-03-20 21:37 ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-03-22 22:37 ` Philippe Blain 2020-03-22 23:01 ` Junio C Hamano 2020-03-22 23:21 ` Philippe Blain 2020-03-20 21:37 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert 2020-03-22 22:38 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert 2020-03-25 21:09 ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-03-25 21:09 ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-03-29 20:34 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert 2020-03-25 21:09 ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-03-29 20:49 ` Philippe Blain 2020-03-25 21:09 ` [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert 2020-04-05 20:16 ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-04-05 20:16 ` [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-04-05 20:16 ` [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert 2020-04-05 20:16 ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-04-05 21:57 ` Junio C Hamano 2020-04-06 13:49 ` Damien Robert 2020-04-06 17:56 ` Junio C Hamano 2020-04-06 18:42 ` Damien Robert 2020-04-05 20:16 ` [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert 2020-04-06 13:57 ` [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore Damien Robert 2020-04-06 13:57 ` [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert 2020-04-06 13:57 ` [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert 2020-04-06 13:57 ` [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert 2020-04-16 13:09 ` [PATCH v6 0/5] doc: --recurse-submodules Philippe Blain
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).