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 v5 5/5] doc: --recurse-submodules mostly applies to active submodules
Date: Sun, 5 Apr 2020 22:16:33 +0200 [thread overview]
Message-ID: <20200405201633.704987-6-damien.olivier.robert+git@gmail.com> (raw)
In-Reply-To: <20200405201633.704987-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 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>
---
Documentation/git-checkout.txt | 2 +-
Documentation/git-grep.txt | 2 +-
Documentation/git-ls-files.txt | 2 +-
Documentation/git-pull.txt | 6 ++++--
Documentation/git-read-tree.txt | 2 +-
Documentation/git-switch.txt | 2 +-
6 files changed, 9 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 140bd3eabb..5b697eee1b 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..b336df00c7 100644
--- 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 501f2ec375..5fa8bab64c 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 79dbc9624d..3759c3a265 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, submodules working trees will not be updated. Just
like linkgit:git-submodule[1], this will detach `HEAD` of the
--
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)
next prev parent reply other threads:[~2020-04-05 20:16 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 ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert
2020-03-22 22:38 ` 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 ` Damien Robert [this message]
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200405201633.704987-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.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.