gvfs-helper: emit advice on transient errors

Users sometimes see transient network errors, but they are actually due
to some other problem within the installation of a packfile. Observed
resolutions include freeing up space on a full disk or deleting the
shared object cache because something was broken due to a file
corruption or power outage.

This change only provides the advice to suggest those workarounds to
help users help themselves.

This is our first advice custom to the microsoft/git fork, so I have
partitioned the key away from the others to avoid adjacent change
conflicts (at least until upstream adds a new change at the end of the
alphabetical list).

We could consider providing a tool that does a more robust check of the
shared object cache, but since 'git fsck' isn't safe to run as it may
download missing objects, we do not have that ability at the moment.

The good news is that it is safe to delete and rebuild the shared object
cache as long as all local branches are pushed. The branches must be
pushed because the local .git/objects/ directory is moved to the shared
object cache in the 'cache-local-objects' maintenance task.

Signed-off-by: Derrick Stolee <stolee@gmail.com>

Author: derrickstolee

advice.c

@@ -93,6 +93,9 @@ static struct {
 	[ADVICE_USE_CORE_FSMONITOR_CONFIG]		= { "useCoreFSMonitorConfig" },
 	[ADVICE_WAITING_FOR_EDITOR]			= { "waitingForEditor" },
 	[ADVICE_WORKTREE_ADD_ORPHAN]			= { "worktreeAddOrphan" },
+
+	/* microsoft/git custom advice below: */
+	[ADVICE_GVFS_HELPER_TRANSIENT_RETRY]		= { "gvfs.transientRetry"},
 };
 
 static const char turn_off_instructions[] =

advice.h

@@ -60,6 +60,9 @@ enum advice_type {
 	ADVICE_USE_CORE_FSMONITOR_CONFIG,
 	ADVICE_WAITING_FOR_EDITOR,
 	ADVICE_WORKTREE_ADD_ORPHAN,
+
+	/* microsoft/git custom advice below: */
+	ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
 };
 
 int git_default_advice_config(const char *var, const char *value);

gvfs-helper.c

@@ -255,6 +255,7 @@
 #include "packfile.h"
 #include "date.h"
 #include "versioncmp.h"
+#include "advice.h"
 
 #define TR2_CAT "gvfs-helper"
 
@@ -3016,6 +3017,32 @@ static int compute_transient_delay(int attempt)
 	return v;
 }
 
+static void gvfs_advice_on_retry(void)
+{
+	static int advice_given = 0;
+
+	if (advice_given)
+		return;
+	advice_given = 1;
+
+	if (gvfs_shared_cache_pathname.len) {
+		advise_if_enabled(ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
+				  "These retries may hint towards issues with your disk or\n"
+				  "shared object cache. Check to see if your disk is full.\n"
+				  "If your disk has space, then your shared object cache\n"
+				  "may have corrupt files. Push all local branches then\n"
+				  "delete '%s'\n"
+				  "and run 'git fetch' to reload the cache.",
+				  gvfs_shared_cache_pathname.buf);
+	} else {
+		advise_if_enabled(ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
+				  "These retries may hint towards issues with your disk.\n"
+				  "Check to see if your disk is full. Note also that you\n"
+				  "do not have a gvfs.sharedCache config, which is not\n"
+				  "normal. You may need to delete and reclone this repo.");
+	}
+}
+
 /*
  * Robustly make an HTTP request.  Retry if necessary to hide common
  * transient network errors and/or 429 blockages.
@@ -3058,6 +3085,10 @@ static void do_req__with_robust_retry(const char *url_base,
 			/*fallthru*/
 
 		case GH__RETRY_MODE__TRANSIENT:
+			/*
+			 * Give advice for common reasons this could happen:
+			 */
+			gvfs_advice_on_retry();
 			params->k_transient_delay_sec =
 				compute_transient_delay(params->k_attempt);
 			continue;