[PATCH] submodule: explain first attempt failure clearly

[Jonathan Tan <jonathantanmy@google.com>]

When cloning with --recurse-submodules a superproject with at least one
submodule with HEAD pointing to an unborn branch, the clone goes
something like this:

	Cloning into 'test'...
	<messages about cloning of superproject>
	Submodule '<name>' (<uri>) registered for path '<submodule path>'
	Cloning into '<submodule path>'...
	fatal: Couldn't find remote ref HEAD
	Unable to fetch in submodule path '<submodule path>'
	<messages about fetching with SHA-1>
	From <uri>
	 * branch            <hash> -> FETCH_HEAD
	Submodule path '<submodule path>': checked out '<hash>'

In other words, first, a fetch is done with no hash arguments (that is,
a fetch of HEAD) resulting in a "Couldn't find remote ref HEAD" error;
then, a fetch is done given a hash, which succeeds.

The fetch given a hash was added in fb43e31f2b ("submodule: try harder
to fetch needed sha1 by direct fetching sha1", 2016-02-24), and the
"Unable to fetch..." message was downgraded from a fatal error to a
notice in e30d833671 ("git-submodule.sh: try harder to fetch a
submodule", 2018-05-16).

This commit improves the notice to be clearer that we are retrying the
fetch, and that the previous messages do not necessarily indicate that
the whole command fails. In other words:

 - If the HEAD-fetch succeeds and we then have the commit we want, no
   extra messages are printed.
 - If the HEAD-fetch succeeds and we do not have the commit we want, but
   the hash-fetch succeeds, no additional messages are printed.
 - If the HEAD-fetch succeeds and we do not have the commit we want, but
   the hash-fetch fails, this is a fatal error.
 - If the HEAD-fetch fails, we print the notice, and if the hash-fetch
   succeeds, no additional messages are printed.
 - If the HEAD-fetch fails, we print the notice, and if the hash-fetch
   fails, this is a fatal error.

It could be said that we should just eliminate the HEAD-fetch
altogether, but that changes some behavior (in particular, some refs
that were opportunistically updated would no longer be), so I have left
that alone for now.

There is an analogous situation with the fetching code in fetch_finish()
and surrounding functions. For now, I have added a NEEDSWORK.

Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
---
 git-submodule.sh | 2 +-
 submodule.c      | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/git-submodule.sh b/git-submodule.sh
index 514ede2596..2c0fb6d723 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -594,7 +594,7 @@ cmd_update()
 				# is not reachable from a ref.
 				is_tip_reachable "$sm_path" "$sha1" ||
 				fetch_in_submodule "$sm_path" $depth ||
-				say "$(eval_gettext "Unable to fetch in submodule path '\$displaypath'")"
+				say "$(eval_gettext "Unable to fetch in submodule path '\$displaypath'; trying to directly fetch \$sha1:")"
 
 				# Now we tried the usual fetch, but $sha1 may
 				# not be reachable from any of the refs
diff --git a/submodule.c b/submodule.c
index 21cf50ca15..b16c0ecc95 100644
--- a/submodule.c
+++ b/submodule.c
@@ -1548,6 +1548,13 @@ static int fetch_finish(int retvalue, struct strbuf *err,
 	struct oid_array *commits;
 
 	if (retvalue)
+		/*
+		 * NEEDSWORK: This indicates that the overall fetch
+		 * failed, even though there may be a subsequent fetch
+		 * by commit hash that might work. It may be a good
+		 * idea to not indicate failure in this case, and only
+		 * indicate failure if the subsequent fetch fails.
+		 */
 		spf->result = 1;
 
 	if (!task || !task->sub)
-- 
2.21.0.155.ge902e9bcae.dirty