Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command
From: Junio C Hamano <hidden>
Date: 2023-07-13 19:38:49
pvutov@imap.cc writes:
From: Petar Vutov <redacted> Bugfix for fc01a5d2 (submodule update documentation: don't repeat ourselves, 2016-12-27). The `custom command` and `none` entries are described as sharing the same limitations, but one is allowed in .gitmodules and the other is not. Instead, describe their limitations separately and in slightly more detail.
Sounds sensible.
quoted hunk
Signed-off-by: Petar Vutov <redacted> --- Changes from v1: Don't delete the documentation for `!command`. Instead, highlight the differences in the limitations of `none` and `!command`. Changes from v2: Improve phrasing. Add the bugfix blurb in the commit message. Documentation/git-submodule.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 4d3ab6b9f9..69ee2cd6b0 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt@@ -160,16 +160,19 @@ 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. ++ +Custom commands are only allowed in the `submodule.<name>.update` +git-config variable. They cannot be used in the .gitmodules file. none;; the submodule is not updated. ++ +The `none` update procedure is allowed in the .gitmodules file +or the `submodule.<name>.update` git-config variable.
But the usual ones like "merge" are also allowed in both places. Does this still need to be said? I wonder if it makes more sense to swap the order of these two entries, showing "none" without any additional text first, and then describe "custom command" with the note, exactly like you did above.