From: Petar Vutov Date: Fri, 14 Jul 2023 22:03:31 GMT Subject: Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command Message-ID: <0d29ac42-4e8f-71b6-b85f-00de182e2957@imap.cc> In-Reply-To: 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..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..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..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..branch:: A remote branch name for tracking updates in the upstream submodule. -- 2.41.0