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>

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 140bd3eabbf83c2f068880ac55080b40ed82f421..5b697eee1b7632a046b48d488b3c3af75ad7fa45 100644 (file)
--- 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 ddb6acc0257ef25c415de9e63e4fb9bacd1728ea..cdf8e26b479ef644696c67cd384e9802efd834c8 100644 (file)
--- 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 8461c0e83e9d535b25755be1d5045cdc30145cb4..3cb2ebb4380e28e8e4b4e1bb5e3f4ae511960b7a 100644 (file)
--- 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 47bc4a7061dec0c11cd95a3215dc790dc4dadda7..b336df00c7e6903a73992bd6a51018c69cd6d08e 100644 (file)
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,8 +85,10 @@ 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
-       be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
+       This option controls if new commits of populated submodules should
+       be fetched, and if the working trees of active submodules should be
+       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 501f2ec375d6909d134e290a4a6a7c46c139951e..5fa8bab64c2d0bb80f88ace023b5eafc898b05f1 100644 (file)
--- 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 79dbc9624ddffe88210a594ff9b66a1048c7a310..3759c3a265b5b9761a9df4d8e6b9d733d29aee04 100644 (file)
--- 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, submodules working trees will not be updated. Just
        like linkgit:git-submodule[1], this will detach `HEAD` of the