mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
Merge branch 'dr/doc-recurse-submodules'
Documentation updates around the "--recurse-submodules" option. * dr/doc-recurse-submodules: doc: --recurse-submodules mostly applies to active submodules doc: be more precise on (fetch|push).recurseSubmodules doc: explain how to deactivate submodule.recurse completely doc: document --recurse-submodules for reset and restore doc: list all commands affected by submodule.recurse
This commit is contained in:
commit
cc908dbc76
|
@ -1,11 +1,14 @@
|
||||||
fetch.recurseSubmodules::
|
fetch.recurseSubmodules::
|
||||||
This option can be either set to a boolean value or to 'on-demand'.
|
This option controls whether `git fetch` (and the underlying fetch
|
||||||
|
in `git pull`) will recursively fetch into populated submodules.
|
||||||
|
This option can be set either to a boolean value or to 'on-demand'.
|
||||||
Setting it to a boolean changes the behavior of fetch and pull to
|
Setting it to a boolean changes the behavior of fetch and pull to
|
||||||
unconditionally recurse into submodules when set to true or to not
|
recurse unconditionally into submodules when set to true or to not
|
||||||
recurse at all when set to false. When set to 'on-demand' (the default
|
recurse at all when set to false. When set to 'on-demand', fetch and
|
||||||
value), fetch and pull will only recurse into a populated submodule
|
pull will only recurse into a populated submodule when its
|
||||||
when its superproject retrieves a commit that updates the submodule's
|
superproject retrieves a commit that updates the submodule's
|
||||||
reference.
|
reference.
|
||||||
|
Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
|
||||||
|
|
||||||
fetch.fsckObjects::
|
fetch.fsckObjects::
|
||||||
If it is set to true, git-fetch-pack will check all fetched
|
If it is set to true, git-fetch-pack will check all fetched
|
||||||
|
|
|
@ -112,3 +112,5 @@ push.recurseSubmodules::
|
||||||
is 'no' then default behavior of ignoring submodules when pushing
|
is 'no' then default behavior of ignoring submodules when pushing
|
||||||
is retained. You may override this configuration at time of push by
|
is retained. You may override this configuration at time of push by
|
||||||
specifying '--recurse-submodules=check|on-demand|no'.
|
specifying '--recurse-submodules=check|on-demand|no'.
|
||||||
|
If not set, 'no' is used by default, unless 'submodule.recurse' is
|
||||||
|
set (in which case a 'true' value means 'on-demand').
|
||||||
|
|
|
@ -59,9 +59,17 @@ submodule.active::
|
||||||
|
|
||||||
submodule.recurse::
|
submodule.recurse::
|
||||||
Specifies if commands recurse into submodules by default. This
|
Specifies if commands recurse into submodules by default. This
|
||||||
applies to all commands that have a `--recurse-submodules` option,
|
applies to all commands that have a `--recurse-submodules` option
|
||||||
except `clone`.
|
(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
|
||||||
|
`restore` and `switch`) except `clone` and `ls-files`.
|
||||||
Defaults to false.
|
Defaults to false.
|
||||||
|
When set to true, it can be deactivated via the
|
||||||
|
`--no-recurse-submodules` option. Note that some Git commands
|
||||||
|
lacking this option may call some of the above commands affected by
|
||||||
|
`submodule.recurse`; for instance `git remote update` will call
|
||||||
|
`git fetch` but does not have a `--no-recurse-submodules` option.
|
||||||
|
For these commands a workaround is to temporarily change the
|
||||||
|
configuration value by using `git -c submodule.recurse=0`.
|
||||||
|
|
||||||
submodule.fetchJobs::
|
submodule.fetchJobs::
|
||||||
Specifies how many submodules are fetched/cloned at the same time.
|
Specifies how many submodules are fetched/cloned at the same time.
|
||||||
|
|
|
@ -163,7 +163,8 @@ ifndef::git-pull[]
|
||||||
value. Use 'on-demand' to only recurse into a populated submodule
|
value. Use 'on-demand' to only recurse into a populated submodule
|
||||||
when the superproject retrieves a commit that updates the submodule's
|
when the superproject retrieves a commit that updates the submodule's
|
||||||
reference to a commit that isn't already in the local submodule
|
reference to a commit that isn't already in the local submodule
|
||||||
clone.
|
clone. By default, 'on-demand' is used, unless
|
||||||
|
`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
|
||||||
endif::git-pull[]
|
endif::git-pull[]
|
||||||
|
|
||||||
-j::
|
-j::
|
||||||
|
|
|
@ -292,11 +292,11 @@ Note that this option uses the no overlay mode by default (see also
|
||||||
|
|
||||||
--recurse-submodules::
|
--recurse-submodules::
|
||||||
--no-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
|
submodules according to the commit recorded in the superproject. If
|
||||||
local modifications in a submodule would be overwritten the checkout
|
local modifications in a submodule would be overwritten the checkout
|
||||||
will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
|
will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
|
||||||
is used, the work trees of submodules will not be updated.
|
is used, submodules working trees will not be updated.
|
||||||
Just like linkgit:git-submodule[1], this will detach `HEAD` of the
|
Just like linkgit:git-submodule[1], this will detach `HEAD` of the
|
||||||
submodule.
|
submodule.
|
||||||
|
|
||||||
|
|
|
@ -93,7 +93,7 @@ OPTIONS
|
||||||
with `--no-index`.
|
with `--no-index`.
|
||||||
|
|
||||||
--recurse-submodules::
|
--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
|
checked out in the repository. When used in combination with the
|
||||||
<tree> option the prefix of all submodule output will be the name of
|
<tree> option the prefix of all submodule output will be the name of
|
||||||
the parent project's <tree> object. This option has no effect
|
the parent project's <tree> object. This option has no effect
|
||||||
|
|
|
@ -148,7 +148,7 @@ a space) at the start of each line:
|
||||||
top directory.
|
top directory.
|
||||||
|
|
||||||
--recurse-submodules::
|
--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.
|
Currently there is only support for the --cached mode.
|
||||||
|
|
||||||
--abbrev[=<n>]::
|
--abbrev[=<n>]::
|
||||||
|
|
|
@ -85,8 +85,9 @@ OPTIONS
|
||||||
Pass --verbose to git-fetch and git-merge.
|
Pass --verbose to git-fetch and git-merge.
|
||||||
|
|
||||||
--[no-]recurse-submodules[=yes|on-demand|no]::
|
--[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 populated submodules should
|
||||||
be fetched and updated, too (see linkgit:git-config[1] and
|
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]).
|
linkgit:gitmodules[5]).
|
||||||
+
|
+
|
||||||
If the checkout is done via rebase, local submodule commits are rebased as well.
|
If the checkout is done via rebase, local submodule commits are rebased as well.
|
||||||
|
|
|
@ -116,9 +116,9 @@ OPTIONS
|
||||||
located in.
|
located in.
|
||||||
|
|
||||||
--[no-]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 by
|
submodules according to the commit recorded in the superproject by
|
||||||
calling read-tree recursively, also setting the submodules HEAD to be
|
calling read-tree recursively, also setting the submodules' HEAD to be
|
||||||
detached at that commit.
|
detached at that commit.
|
||||||
|
|
||||||
--no-sparse-checkout::
|
--no-sparse-checkout::
|
||||||
|
|
|
@ -87,6 +87,12 @@ but carries forward unmerged index entries.
|
||||||
different between `<commit>` and `HEAD`.
|
different between `<commit>` and `HEAD`.
|
||||||
If a file that is different between `<commit>` and `HEAD` has local
|
If a file that is different between `<commit>` and `HEAD` has local
|
||||||
changes, reset is aborted.
|
changes, reset is aborted.
|
||||||
|
|
||||||
|
--[no-]recurse-submodules::
|
||||||
|
When the working tree is updated, using --recurse-submodules will
|
||||||
|
also recursively reset the working tree of all active submodules
|
||||||
|
according to the commit recorded in the superproject, also setting
|
||||||
|
the submodules' HEAD to be detached at that commit.
|
||||||
--
|
--
|
||||||
|
|
||||||
See "Reset, restore and revert" in linkgit:git[1] for the differences
|
See "Reset, restore and revert" in linkgit:git[1] for the differences
|
||||||
|
|
|
@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.
|
||||||
patterns and unconditionally restores any files in
|
patterns and unconditionally restores any files in
|
||||||
`<pathspec>`.
|
`<pathspec>`.
|
||||||
|
|
||||||
|
--recurse-submodules::
|
||||||
|
--no-recurse-submodules::
|
||||||
|
If `<pathspec>` names an active submodule and the restore location
|
||||||
|
includes the working tree, the submodule will only be updated if
|
||||||
|
this option is given, in which case its working tree will be
|
||||||
|
restored to the commit recorded in the superproject, and any local
|
||||||
|
modifications overwritten. If nothing (or
|
||||||
|
`--no-recurse-submodules`) is used, submodules working trees will
|
||||||
|
not be updated. Just like linkgit:git-checkout[1], this will detach
|
||||||
|
`HEAD` of the submodule.
|
||||||
|
|
||||||
--overlay::
|
--overlay::
|
||||||
--no-overlay::
|
--no-overlay::
|
||||||
In overlay mode, the command never removes files when
|
In overlay mode, the command never removes files when
|
||||||
|
|
|
@ -181,9 +181,9 @@ name, the guessing is aborted. You can explicitly give a name with
|
||||||
--recurse-submodules::
|
--recurse-submodules::
|
||||||
--no-recurse-submodules::
|
--no-recurse-submodules::
|
||||||
Using `--recurse-submodules` will update the content of all
|
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
|
superproject. If nothing (or `--no-recurse-submodules`) is
|
||||||
used, the work trees of submodules will not be updated. Just
|
used, submodules working trees will not be updated. Just
|
||||||
like linkgit:git-submodule[1], this will detach `HEAD` of the
|
like linkgit:git-submodule[1], this will detach `HEAD` of the
|
||||||
submodules.
|
submodules.
|
||||||
|
|
||||||
|
|
|
@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
|
||||||
into submodules. The 'init' and 'update' subcommands of 'git submodule'
|
into submodules. The 'init' and 'update' subcommands of 'git submodule'
|
||||||
will maintain submodules checked out and at an appropriate revision in
|
will maintain submodules checked out and at an appropriate revision in
|
||||||
your working tree. Alternatively you can set 'submodule.recurse' to have
|
your working tree. Alternatively you can set 'submodule.recurse' to have
|
||||||
'checkout' recursing into submodules.
|
'checkout' recursing into submodules (note that 'submodule.recurse' also
|
||||||
|
affects other git commands, see linkgit:git-config[1] for a complete list).
|
||||||
|
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
|
|
Loading…
Reference in a new issue