path: root/Documentation/fetch-options.txt
diff options
authorGlen Choo <>2022-03-08 00:14:32 (GMT)
committerJunio C Hamano <>2022-03-16 23:08:59 (GMT)
commitb90d9f7632d380d3f16197ae657ab57075acd1eb (patch)
treea89794a4a8f9add7069a79d86e1854fff540d04f /Documentation/fetch-options.txt
parent5370b91f3fae9d7a511e23142b55082200152cef (diff)
fetch: fetch unpopulated, changed submodules
"git fetch --recurse-submodules" only considers populated submodules (i.e. submodules that can be found by iterating the index), which makes "git fetch" behave differently based on which commit is checked out. As a result, even if the user has initialized all submodules correctly, they may not fetch the necessary submodule commits, and commands like "git checkout --recurse-submodules" might fail. Teach "git fetch" to fetch cloned, changed submodules regardless of whether they are populated. This is in addition to the current behavior of fetching populated submodules (which is always attempted regardless of what was fetched in the superproject, or even if nothing was fetched in the superproject). A submodule may be encountered multiple times (via the list of populated submodules or via the list of changed submodules). When this happens, "git fetch" only reads the 'populated copy' and ignores the 'changed copy'. Amend the verify_fetch_result() test helper so that we can assert on which 'copy' is being read. Signed-off-by: Glen Choo <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/fetch-options.txt')
1 files changed, 17 insertions, 9 deletions
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index f903683..6cdd9d4 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -186,15 +186,23 @@ endif::git-pull[]
This option controls if and under what conditions new commits of
- populated 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
- 'yes', which is the default when this option is used without any
- 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. By default, 'on-demand' is used, unless
- `fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
+ submodules should be fetched too. When recursing through submodules,
+ `git fetch` always attempts to fetch "changed" submodules, that is, a
+ submodule that has commits that are referenced by a newly fetched
+ superproject commit but are missing in the local submodule clone. A
+ changed submodule can be fetched as long as it is present locally e.g.
+ in `$GIT_DIR/modules/` (see linkgit:gitsubmodules[7]); if the upstream
+ adds a new submodule, that submodule cannot be fetched until it is
+ cloned e.g. by `git submodule update`.
+When set to 'on-demand', only changed submodules are fetched. When set
+to 'yes', all populated submodules are fetched and submodules that are
+both unpopulated and changed are fetched. When set to 'no', submodules
+are never fetched.
+When unspecified, this uses the value of `fetch.recurseSubmodules` if it
+is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset.
+When this option is used without any value, it defaults to 'yes'.