kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

doc: highlight that .gitmodules does not support !command 

Bugfix for fc01a5d2 (submodule update documentation: don't repeat
ourselves, 2016-12-27).

The `custom command` and `none` options are described as sharing the
same limitations, but one is allowed in .gitmodules and the other is
not.

Rewrite the description for custom commands to be more precise,
and make it easier for readers to notice that custom commands cannot
be used in the .gitmodules file.

Signed-off-by: Petar Vutov <pvutov@imap.cc>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Petar Vutov 2023-07-25 23:22:18 +02:00 committed by Junio C Hamano
parent fb7d80edca
commit 7cebc5bd78
2 changed files with 22 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Documentation/git-submodule.txt
View File

@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree).
init [--] [<path>...]:: init [--] [<path>...]::
Initialize the submodules recorded in the index (which were Initialize the submodules recorded in the index (which were
added and committed elsewhere) by setting `submodule.$name.url` added and committed elsewhere) by setting `submodule.$name.url`
in .git/config. It uses the same setting from `.gitmodules` as in `.git/config`, using the same setting from `.gitmodules` as
a template. If the URL is relative, it will be resolved using a template. If the URL is relative, it will be resolved using
the default remote. If there is no default remote, the current the default remote. If there is no default remote, the current
repository will be assumed to be upstream. repository will be assumed to be upstream.
@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules
configured to be active will be initialized, otherwise all submodules are configured to be active will be initialized, otherwise all submodules are
initialized. initialized.
+ +
When present, it will also copy the value of `submodule.$name.update`. It will also copy the value of `submodule.$name.update`, if present in
This command does not alter existing information in .git/config. the `.gitmodules` file, to `.git/config`, but (1) this command does not
You can then customize the submodule clone URLs in .git/config alter existing information in `.git/config`, and (2) `submodule.$name.update`
that is set to a custom command is *not* copied for security reasons.
+
You can then customize the submodule clone URLs in `.git/config`
for your local setup and proceed to `git submodule update`; for your local setup and proceed to `git submodule update`;
you can also just use `git submodule update --init` without you can also just use `git submodule update --init` without
the explicit 'init' step if you do not intend to customize the explicit 'init' step if you do not intend to customize
@ -143,6 +146,8 @@ the submodules. The "updating" can be done in several ways depending
on command line options and the value of `submodule.<name>.update` on command line options and the value of `submodule.<name>.update`
configuration variable. The command line option takes precedence over configuration variable. The command line option takes precedence over
the configuration variable. If neither is given, a 'checkout' is performed. the configuration variable. If neither is given, a 'checkout' is performed.
(note: what is in `.gitmodules` file is irrelevant at this point;
see `git submodule init` above for how `.gitmodules` is used).
The 'update' procedures supported both from the command line as well as The 'update' procedures supported both from the command line as well as
through the `submodule.<name>.update` configuration are: through the `submodule.<name>.update` configuration are:


@ -160,16 +165,18 @@ checked out in the submodule.
merge;; the commit recorded in the superproject will be merged merge;; the commit recorded in the superproject will be merged
into the current branch in the submodule. into the current branch in the submodule.


The following 'update' procedures are only available via the The following update procedures have additional limitations:
`submodule.<name>.update` configuration variable:


custom command;; arbitrary shell command that takes a single custom command;; mechanism for running arbitrary commands with the
argument (the sha1 of the commit recorded in the commit ID as an argument. Specifically, if the
superproject) is executed. When `submodule.<name>.update` `submodule.<name>.update` configuration variable is set to
is set to '!command', the remainder after the exclamation mark `!custom command`, the object name of the commit recorded in the
is the custom command. superproject for the submodule is appended to the `custom command`
string and executed. Note that this mechanism is not supported in
the `.gitmodules` file or on the command line.


none;; the submodule is not updated. none;; the submodule is not updated. This update procedure is not
allowed on the command line.


If the submodule is not yet initialized, and you just want to use the If the submodule is not yet initialized, and you just want to use the
setting as stored in `.gitmodules`, you can automatically initialize the setting as stored in `.gitmodules`, you can automatically initialize the

6
Documentation/gitmodules.txt
View File

@ -43,9 +43,9 @@ submodule.<name>.update::
command in the superproject. This is only used by `git command in the superproject. This is only used by `git
submodule init` to initialize the configuration variable of submodule init` to initialize the configuration variable of
the same name. Allowed values here are 'checkout', 'rebase', the same name. Allowed values here are 'checkout', 'rebase',
'merge' or 'none'. See description of 'update' command in 'merge' or 'none', but not '!command' (for security reasons).
linkgit:git-submodule[1] for their meaning. For security See the description of the 'update' command in
reasons, the '!command' form is not accepted here. linkgit:git-submodule[1] for more details.


submodule.<name>.branch:: submodule.<name>.branch::
A remote branch name for tracking updates in the upstream submodule. A remote branch name for tracking updates in the upstream submodule.