submodule_needs_pushing(): explain the behaviour when we cannot answer

When we do not have commits that are involved in the update of the
superproject in our copy of submodule, we cannot tell if the remote
end needs to acquire these commits to be able to check out the
superproject tree.  Explain why we answer "no there is no need/point
in pushing from our submodule repository" in this case.

Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/submodule.c b/submodule.c
index 85287a1d16b7e5346fcd760bf2afd1deb75e6ee2..b5094881823c9abf33625ff0b396cbcb6114e7da 100644 (file)
--- a/submodule.c
+++ b/submodule.c
@@ -553,6 +553,17 @@ static int submodule_has_commits(const char *path, struct sha1_array *commits)
 static int submodule_needs_pushing(const char *path, struct sha1_array *commits)
 {
        if (!submodule_has_commits(path, commits))
+               /*
+                * NOTE: We do consider it safe to return "no" here. The
+                * correct answer would be "We do not know" instead of
+                * "No push needed", but it is quite hard to change
+                * the submodule pointer without having the submodule
+                * around. If a user did however change the submodules
+                * without having the submodule around, this indicates
+                * an expert who knows what they are doing or a
+                * maintainer integrating work from other people. In
+                * both cases it should be safe to skip this check.
+                */
                return 0;
 
        if (for_each_remote_ref_submodule(path, has_remote, NULL) > 0) {