Petar Vutov [off-list ref] writes:
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.
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.
Sorry for a very slow response; I seem to have missed this one.
The end result looks good. Care to wrap it up into a single patch
(iow, make a "mishmash of both patches") with a good log message so
we can move the topic forward?
Thanks.
quoted hunk
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.