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

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

Junio C Hamano <gitster@pobox.com> writes:

> After reading the original again and again, I hate more and more the
> way the original wasted too many words to refer to one thing twice
> (e.g. "arbitrary command" and then "is the custom command", "a
> single argument" and then the parenthesized explanation of it)
> without adding any clarity.

Another thing I noticed is that this section is ONLY talking about
the configuration variable, so everything both of us have been
saying misses the point.  The preamble before the choices
("checkout", "rebase", "merge", "custom" and "none") are listed read
like so:

    update [--init] [--remote] [-N|--no-f...
    +
    --
    Update the registered submodules to match what the superproject
    expects by cloning missing submodules, fetching missing commits
    in submodules and updating the working tree of
    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.
    The 'update' procedures supported both from the command line as well as
    through the `submodule.<name>.update` configuration are:

Then why do we even think about referring to ".gitmodules" here?  It
is because of this behaviour that is described elsewhere:

    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
            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.
    +
    Optional <path> arguments limit which submodules will be initialized.
    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`.

and this description is very flawed.  It says "X is copied", but not
"X is copied from A to B".  It also does not say that even if you
have a custom command there, it does not get copied.

It copies submodule.<name>.update from the ".gitmodules" to the
configuraiton.  And that is the reason why, the configuration may
have "submodule.<name>.update" in it after running "git init" to
initialize a submodule.  And that is why the choices of update
methods listed in the part your patch touched talked about things
that can both appear in .gitmodules and the configuration.  But the
linkage is quite indirect.

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.

 Documentation/git-submodule.txt | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git c/Documentation/git-submodule.txt w/Documentation/git-submodule.txt
index 4d3ab6b9f9..5248840b18 100644
--- c/Documentation/git-submodule.txt
+++ w/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,9 +165,6 @@ 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`