Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command

[Petar Vutov <pvutov@imap.cc>]

On 7/13/23 23:37, Junio C Hamano wrote:
> So, here is another round, this time the primary change is to stop
> talking about `.gitmodules` in the "update" section, but explain how
> `.gitmodules` file is used in the "init" section.

Looks good to me.

I applied your patch and then made some additions, which I'll append at 
the end of this message. Summary:

* Added your rewrite from yesterday. I like that it's more precise than 
the current docs, but I struggle with the complexity of the first 
sentence. I wanted to make it easier to follow by splitting it in two 
somehow. Instead I ended up with an introductory sentence summarizing 
the functionality with small words.

* In gitmodules.txt, moved the security disclaimer so people are more 
likely to see it before they follow the link to git-submodule.txt.

* Explicitly called out `none` and `custom command` as being unusable on 
the command line (and in .gitmodules). I expect that you won't want that 
.gitmodules mention anymore, but I left it in for now, up to you.

By the way, I ran into an SO question where some people were discussing 
the same issue: https://stackoverflow.com/q/65744067/876832

The diff below is based on top of your patch from yesterday, since I 
assume that you don't want to look at a mishmash of both patches.

---
  Documentation/git-submodule.txt | 19 ++++++++++++-------
  Documentation/gitmodules.txt    |  6 +++---
  2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-submodule.txt 
b/Documentation/git-submodule.txt
index 5248840b18..695730609a 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -165,13 +165,18 @@ checked out in the submodule.
  	merge;; the commit recorded in the superproject will be merged
  	    into the current branch in the submodule.

-	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.
+The following update procedures have additional limitations:
+
+	custom command;; mechanism for running arbitrary commands with the
+	    commit ID as an argument. Specifically, if 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 executed. Note that this mechanism is not supported in
+	    the `.gitmodules` file or on the command line.
+
+	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
  setting as stored in `.gitmodules`, you can automatically initialize the
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index dcee09b500..d9bec8b187 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -43,9 +43,9 @@ submodule.<name>.update::
  	command in the superproject. This is only used by `git
  	submodule init` to initialize the configuration variable of
  	the same name. Allowed values here are 'checkout', 'rebase',
-	'merge' or 'none'. See description of 'update' command in
-	linkgit:git-submodule[1] for their meaning. For security
-	reasons, the '!command' form is not accepted here.
+	'merge' or 'none', but not '!command' (for security reasons).
+	See the description of the 'update' command in
+	linkgit:git-submodule[1] for more details.

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