@matheusbsbs / matheus-bagliano / commits / acbfae32a3
Fork 0

doc: --recurse-submodules mostly applies to active submodules

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Damien Robert committed Apr 6, 2020 at 15:57 UTC acbfae32a31180d781357028af9aff8928672d4b
6 files changed +9 -7
Documentation/git-checkout.txt
+1 -1
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
292
293 --recurse-submodules::
294 --no-recurse-submodules::
295 - Using `--recurse-submodules` will update the content of all initialized
295 + Using `--recurse-submodules` will update the content of all active
296 submodules according to the commit recorded in the superproject. If
297 local modifications in a submodule would be overwritten the checkout
298 will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
Documentation/git-grep.txt
+1 -1
@@ -93,7 +93,7 @@ OPTIONS
93 with `--no-index`.
94
95 --recurse-submodules::
96 - Recursively search in each submodule that has been initialized and
96 + Recursively search in each submodule that is active and
97 checked out in the repository. When used in combination with the
98 <tree> option the prefix of all submodule output will be the name of
99 the parent project's <tree> object. This option has no effect
Documentation/git-ls-files.txt
+1 -1
@@ -148,7 +148,7 @@ a space) at the start of each line:
148 top directory.
149
150 --recurse-submodules::
151 - Recursively calls ls-files on each submodule in the repository.
151 + Recursively calls ls-files on each active submodule in the repository.
152 Currently there is only support for the --cached mode.
153
154 --abbrev[=<n>]::
Documentation/git-pull.txt
+4 -2
@@ -85,8 +85,10 @@ OPTIONS
85 Pass --verbose to git-fetch and git-merge.
86
87 --[no-]recurse-submodules[=yes|on-demand|no]::
88 - This option controls if new commits of all populated submodules should
89 - be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
88 + This option controls if new commits of populated submodules should
89 + be fetched, and if the working trees of active submodules should be
90 + updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
91 + linkgit:gitmodules[5]).
92 +
93 If the checkout is done via rebase, local submodule commits are rebased as well.
94 +
Documentation/git-read-tree.txt
+1 -1
@@ -116,7 +116,7 @@ OPTIONS
116 located in.
117
118 --[no-]recurse-submodules::
119 - Using --recurse-submodules will update the content of all initialized
119 + Using --recurse-submodules will update the content of all active
120 submodules according to the commit recorded in the superproject by
121 calling read-tree recursively, also setting the submodules' HEAD to be
122 detached at that commit.
Documentation/git-switch.txt
+1 -1
@@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with
181 --recurse-submodules::
182 --no-recurse-submodules::
183 Using `--recurse-submodules` will update the content of all
184 - initialized submodules according to the commit recorded in the
184 + active submodules according to the commit recorded in the
185 superproject. If nothing (or `--no-recurse-submodules`) is
186 used, submodules working trees will not be updated. Just
187 like linkgit:git-submodule[1], this will detach `HEAD` of the