Doc: explain submodule.alternateErrorStrategy

Commit 31224cbdc7 ("clone: recursive and reference option triggers
submodule alternates", 2016-08-17) taught Git to support the
configuration options "submodule.alternateLocation" and
"submodule.alternateErrorStrategy" on a superproject.

If "submodule.alternateLocation" is configured to "superproject" on a
superproject, whenever a submodule of that superproject is cloned, it
instead computes the analogous alternate path for that submodule from
$GIT_DIR/objects/info/alternates of the superproject, and references it.

The "submodule.alternateErrorStrategy" option determines what happens
if that alternate cannot be referenced. However, it is not clear that
the clone proceeds as if no alternate was specified when that option is
not set to "die" (as can be seen in the tests in 31224cbdc7). Therefore,
document it accordingly.

Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 0a1293b05135bf2d21ca7ef6639f309380e2040b..b33177151c5fe745652fc64a6fe4ec9858fc18c2 100644 (file)
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -79,4 +79,6 @@ submodule.alternateLocation::
 submodule.alternateErrorStrategy::
        Specifies how to treat errors with the alternates for a submodule
        as computed via `submodule.alternateLocation`. Possible values are
-       `ignore`, `info`, `die`. Default is `die`.
+       `ignore`, `info`, `die`. Default is `die`. Note that if set to `ignore`
+       or `info`, and if there is an error with the computed alternate, the
+       clone proceeds as if no alternate was specified.