Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jul 13, 2023, 19:55 UTC
- Message-ID
- <xmqqwmz3oacg.fsf@gitster.g>
- In-Reply-To
- <a8bde495-57fc-6a70-e325-6e2a52f40552@imap.cc>
Petar Vutov <pvutov@imap.cc> writes:
Show 8 quoted lines
> Oops, this was supposed to go under > <7090349c-4485-d5c4-1f26-190974864f72@imap.cc>.. > > Side question in this side thread: I was tempted to change the mention > of "configuration variable" with "git-config variable", to highlight > the narrow meaning of the term. But I grepped and that term is used > everywhere in the documentation. Changing it only in this section > would be inconsistent.
Don't. People should be familiar with "configuration variable", but may not be with "git-config variable".
How about doing it this way? I moved 'none' up, as it is effective in `.gitmodules` and as a configuration variable, just like all others, and then completely rewrote the somewhat awkward explanation of the custom command thing.
----- >8 --------- >8 --------- >8 --------- >8 ---- Subject: submodule: clarify that "!custom command" is the only oddball
We singled out 'none' and 'custom command' as submodule update modes that cannot be specified in the .gitmodules file, but 'none' can appear there, and use of a custom command is the only oddball.
Move the description of 'none' up, clarify how the custom command is used, and explicitly say it cannot be used in the `.gitmodules` file.
Strictly speaking, the last one should not be needed, as we already say `configuration variable`, but to new readers, the distinction between the configuration variable and settings that appear in the .gitmodules file may not be apparent; hopefully the new text will help them understand where it can(not) be used.
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-submodule.txt | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-)
diff --git c/Documentation/git-submodule.txt w/Documentation/git-submodule.txt index 4d3ab6b9f9..391ff0dbf2 100644 --- c/Documentation/git-submodule.txt +++ w/Documentation/git-submodule.txt @@ -160,17 +160,15 @@ checked out in the submodule. merge;; the commit recorded in the superproject will be merged into the current branch in the submodule. -The following 'update' procedures are only available via the -`submodule.<name>.update` configuration variable: - - custom command;; arbitrary shell command that takes a single - argument (the sha1 of the commit recorded in the - superproject) is executed. When `submodule.<name>.update` - is set to '!command', the remainder after the exclamation mark - is the custom command. - none;; the submodule is not updated. + custom command;; When the `submodule.<name>.update` + configuration variable is set to `!custom command`, the + object name of the commit recorded in the superproject + for the submodule is appended to the `custom command` + string and gets executed. Note that this mechanism + cannot be used in the `.gitmodules` file. + If the submodule is not yet initialized, and you just want to use the setting as stored in `.gitmodules`, you can automatically initialize the submodule with the `--init` option.