Junio C Hamano <gitster@xxxxxxxxx> 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`
