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>
Petar Vutov committed
Jul 25, 2023 at 23:22 UTC
7cebc5bd786a95722dc545a2cad22124ec996c00
2 files changed
+22
-15
Documentation/git-submodule.txt
+19
-12
@@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree).
95
init [--] [<path>...]::
96
Initialize the submodules recorded in the index (which were
97
added and committed elsewhere) by setting `submodule.$name.url`
98
- in .git/config. It uses the same setting from `.gitmodules` as
98
+ in `.git/config`, using the same setting from `.gitmodules` as
99
a template. If the URL is relative, it will be resolved using
100
the default remote. If there is no default remote, the current
101
repository will be assumed to be upstream.
@@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules
105
configured to be active will be initialized, otherwise all submodules are
106
initialized.
107
+
108
-When present, it will also copy the value of `submodule.$name.update`.
109
-This command does not alter existing information in .git/config.
110
-You can then customize the submodule clone URLs in .git/config
108
+It will also copy the value of `submodule.$name.update`, if present in
109
+the `.gitmodules` file, to `.git/config`, but (1) this command does not
110
+alter existing information in `.git/config`, and (2) `submodule.$name.update`
111
+that is set to a custom command is *not* copied for security reasons.
112
++
113
+You can then customize the submodule clone URLs in `.git/config`
114
for your local setup and proceed to `git submodule update`;
115
you can also just use `git submodule update --init` without
116
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
146
on command line options and the value of `submodule.<name>.update`
147
configuration variable. The command line option takes precedence over
148
the configuration variable. If neither is given, a 'checkout' is performed.
149
+(note: what is in `.gitmodules` file is irrelevant at this point;
150
+see `git submodule init` above for how `.gitmodules` is used).
151
The 'update' procedures supported both from the command line as well as
152
through the `submodule.<name>.update` configuration are:
153
@@ -160,16 +165,18 @@ checked out in the submodule.
165
merge;; the commit recorded in the superproject will be merged
166
into the current branch in the submodule.
167
163
-The following 'update' procedures are only available via the
164
-`submodule.<name>.update` configuration variable:
168
+The following update procedures have additional limitations:
169
166
- custom command;; arbitrary shell command that takes a single
167
- argument (the sha1 of the commit recorded in the
168
- superproject) is executed. When `submodule.<name>.update`
169
- is set to '!command', the remainder after the exclamation mark
170
- is the custom command.
170
+ custom command;; mechanism for running arbitrary commands with the
171
+ commit ID as an argument. Specifically, if the
172
+ `submodule.<name>.update` configuration variable is set to
173
+ `!custom command`, the object name of the commit recorded in the
174
+ superproject for the submodule is appended to the `custom command`
175
+ string and executed. Note that this mechanism is not supported in
176
+ the `.gitmodules` file or on the command line.
177
172
- none;; the submodule is not updated.
178
+ none;; the submodule is not updated. This update procedure is not
179
+ allowed on the command line.
180
181
If the submodule is not yet initialized, and you just want to use the
182
setting as stored in `.gitmodules`, you can automatically initialize the
Documentation/gitmodules.txt
+3
-3
@@ -43,9 +43,9 @@ submodule.<name>.update::
43
command in the superproject. This is only used by `git
44
submodule init` to initialize the configuration variable of
45
the same name. Allowed values here are 'checkout', 'rebase',
46
- 'merge' or 'none'. See description of 'update' command in
47
- linkgit:git-submodule[1] for their meaning. For security
48
- reasons, the '!command' form is not accepted here.
46
+ 'merge' or 'none', but not '!command' (for security reasons).
47
+ See the description of the 'update' command in
48
+ linkgit:git-submodule[1] for more details.
49
50
submodule.<name>.branch::
51
A remote branch name for tracking updates in the upstream submodule.