Merge branch 'gc/branch-recurse-submodules-fix'

[thirdparty/git.git] / Documentation / fetch-options.txt

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index f9036831898f4ea275d6682f17c17479d4fb0953..6cdd9d43c5abd223aba5350eaea9bd22032bc4de 100644 (file)
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -186,15 +186,23 @@ endif::git-pull[]
 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
-       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'.
 endif::git-pull[]
 
 -j::