doc: highlight that .gitmodules does not support !command

Bugfix for fc01a5d2 (submodule update documentation: don't repeat
ourselves, 2016-12-27).

The `custom command` and `none` options are described as sharing the
same limitations, but one is allowed in .gitmodules and the other is
not.

Rewrite the description for custom commands to be more precise,
and make it easier for readers to notice that custom commands cannot
be used in the .gitmodules file.

Signed-off-by: Petar Vutov <pvutov@imap.cc>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 4d3ab6b9f925cde1ef8835d790fa1fd66108a36d..695730609aa3ab5a18d45cbff6aba5d1499dfdce 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree).
 init [--] [<path>...]::
        Initialize the submodules recorded in the index (which were
        added and committed elsewhere) by setting `submodule.$name.url`
-       in .git/config. It uses the same setting from `.gitmodules` as
+       in `.git/config`, using the same setting from `.gitmodules` as
        a template. If the URL is relative, it will be resolved using
        the default remote. If there is no default remote, the current
        repository will be assumed to be upstream.
@@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules
 configured to be active will be initialized, otherwise all submodules are
 initialized.
 +
-When present, it will also copy the value of `submodule.$name.update`.
-This command does not alter existing information in .git/config.
-You can then customize the submodule clone URLs in .git/config
+It will also copy the value of `submodule.$name.update`, if present in
+the `.gitmodules` file, to `.git/config`, but (1) this command does not
+alter existing information in `.git/config`, and (2) `submodule.$name.update`
+that is set to a custom command is *not* copied for security reasons.
++
+You can then customize the submodule clone URLs in `.git/config`
 for your local setup and proceed to `git submodule update`;
 you can also just use `git submodule update --init` without
 the explicit 'init' step if you do not intend to customize
@@ -143,6 +146,8 @@ the submodules. The "updating" can be done in several ways depending
 on command line options and the value of `submodule.<name>.update`
 configuration variable. The command line option takes precedence over
 the configuration variable. If neither is given, a 'checkout' is performed.
+(note: what is in `.gitmodules` file is irrelevant at this point;
+see `git submodule init` above for how `.gitmodules` is used).
 The 'update' procedures supported both from the command line as well as
 through the `submodule.<name>.update` configuration are:
 
@@ -160,16 +165,18 @@ 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:
+The following update procedures have additional limitations:
 
-       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 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.
+       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 dcee09b5001dc8cfb95753c0c02a5b49ba036752..d9bec8b1875502b22934877311d3124a3e5a22df 100644 (file)
--- 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.