]> git.ipfire.org Git - thirdparty/git.git/commit - Documentation/git-ls-files.txt
doc: --recurse-submodules mostly applies to active submodules
authorDamien Robert <damien.olivier.robert@gmail.com>
Mon, 6 Apr 2020 13:57:09 +0000 (15:57 +0200)
committerJunio C Hamano <gitster@pobox.com>
Mon, 6 Apr 2020 20:42:43 +0000 (13:42 -0700)
commitacbfae32a31180d781357028af9aff8928672d4b
treebc737ce26e99375e3f6adbc5cbb0093f35ed906b
parent4da9e99e6eaab24ef86c44642b0692669adacfeb
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>
Documentation/git-checkout.txt
Documentation/git-grep.txt
Documentation/git-ls-files.txt
Documentation/git-pull.txt
Documentation/git-read-tree.txt
Documentation/git-switch.txt