| Message ID | 20200320213729.571924-6-damien.olivier.robert+git@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: --recurse-submodules | expand |
> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit 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
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
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(-)