| Message ID | 20200303170740.1879432-6-damien.olivier.robert+git@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: --recurse-submodules | expand |
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
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.
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
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(-)