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

[Junio C Hamano <gitster@pobox.com>]

Petar Vutov <pvutov@imap.cc> writes:

> 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.