From: Damien Robert <damien.olivier.robert@gmail.com>
To: git@vger.kernel.org, Philippe Blain <levraiphilippeblain@gmail.com>
Cc: Damien Robert <damien.olivier.robert+git@gmail.com>
Subject: [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules
Date: Fri, 20 Mar 2020 22:37:29 +0100 [thread overview]
Message-ID: <20200320213729.571924-6-damien.olivier.robert+git@gmail.com> (raw)
In-Reply-To: <20200320213729.571924-1-damien.olivier.robert+git@gmail.com>
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 submodules. An exception
is `git fetch` where the option affects populated submodules.
As a consequence, in `git pull` the fetch affects populated submodules,
but the resulting working tree update only affects active submodules.
In the documentation of `git-pull` we only refer to active submodules,
since it is implicit that the fetching behaviour is governed by the
fetch command.
Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-checkout.txt | 2 +-
Documentation/git-grep.txt | 2 +-
Documentation/git-ls-files.txt | 2 +-
Documentation/git-pull.txt | 2 +-
Documentation/git-read-tree.txt | 2 +-
Documentation/git-switch.txt | 2 +-
6 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..3be0a28284 100644
--- 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 ddb6acc025..cdf8e26b47 100644
--- 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 8461c0e83e..3cb2ebb438 100644
--- 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 47bc4a7061..2285f3729d 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,7 +85,7 @@ 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
+ This option controls if new commits of all active submodules should
be fetched and 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 da33f84f33..aab6856341 100644
--- 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 197900363b..337852d86b 100644
--- 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, the work trees of submodules will not be updated. Just
like linkgit:git-submodule[1], this will detach `HEAD` of the
--
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)
next prev parent reply other threads:[~2020-03-20 21:38 UTC|newest]
Thread overview: 69+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert
2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert
2020-03-02 4:43 ` Philippe Blain
2020-03-03 17:09 ` Damien Robert
2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-02 4:45 ` Philippe Blain
2020-03-03 17:26 ` Damien Robert
2020-03-06 4:16 ` Philippe Blain
2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert
2020-03-02 4:45 ` Philippe Blain
2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert
2020-03-02 4:46 ` Philippe Blain
2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert
2020-03-03 5:18 ` Philippe Blain
2020-03-02 4:47 ` Philippe Blain
2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert
2020-03-03 17:07 ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-03 17:07 ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-03 21:54 ` Junio C Hamano
2020-03-06 4:16 ` Philippe Blain
2020-03-03 17:07 ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert
2020-03-03 21:57 ` Junio C Hamano
2020-03-03 22:05 ` Robert P. J. Day
2020-03-03 22:04 ` Damien Robert
2020-03-06 4:16 ` Philippe Blain
2020-03-03 17:07 ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-03 22:05 ` Junio C Hamano
2020-03-03 22:12 ` Robert P. J. Day
2020-03-03 17:07 ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert
2020-03-06 4:17 ` Philippe Blain
2020-03-20 22:23 ` Damien Robert
2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert
2020-03-20 21:37 ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-20 21:37 ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-22 22:36 ` Philippe Blain
2020-03-25 21:05 ` Damien Robert
2020-03-20 21:37 ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-03-22 22:36 ` Philippe Blain
2020-03-20 21:37 ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-22 22:37 ` Philippe Blain
2020-03-22 23:01 ` Junio C Hamano
2020-03-22 23:21 ` Philippe Blain
2020-03-20 21:37 ` Damien Robert [this message]
2020-03-22 22:38 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Philippe Blain
2020-03-25 21:09 ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert
2020-03-25 21:09 ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-25 21:09 ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-29 20:34 ` Philippe Blain
2020-03-25 21:09 ` [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-03-25 21:09 ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-29 20:49 ` Philippe Blain
2020-03-25 21:09 ` [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-05 20:16 ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert
2020-04-05 20:16 ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-04-05 20:16 ` [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-04-05 20:16 ` [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-04-05 20:16 ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-04-05 21:57 ` Junio C Hamano
2020-04-06 13:49 ` Damien Robert
2020-04-06 17:56 ` Junio C Hamano
2020-04-06 18:42 ` Damien Robert
2020-04-05 20:16 ` [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-06 13:57 ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert
2020-04-06 13:57 ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-04-06 13:57 ` [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-04-06 13:57 ` [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-04-06 13:57 ` [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-04-06 13:57 ` [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-16 13:09 ` [PATCH v6 0/5] doc: --recurse-submodules Philippe Blain
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200320213729.571924-6-damien.olivier.robert+git@gmail.com \
--to=damien.olivier.robert@gmail.com \
--cc=damien.olivier.robert+git@gmail.com \
--cc=git@vger.kernel.org \
--cc=levraiphilippeblain@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).