Merge branch 'deprecate-core.useBuiltinFSMonitor'

Originally introduced as `core.useBuiltinFSMonitor` in Git for Windows
and developed, improved and stabilized there, the built-in FSMonitor
only made it into upstream Git (after unnecessarily long hemming and
hawing and throwing overly perfectionist style review sticks into the
spokes) as `core.fsmonitor = true`.

In Git for Windows, with this topic branch, we re-introduce the
now-obsolete config setting, with warnings suggesting to existing users
how to switch to the new config setting, with the intention to
ultimately drop the patch at some stage.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

Documentation/config/advice.txt

@@ -169,4 +169,8 @@ all advice messages.
 		Shown when the user tries to create a worktree from an
 		invalid reference, to tell the user how to create a new unborn
 		branch instead.
+
+	useCoreFSMonitorConfig::
+		Advice shown if the deprecated 'core.useBuiltinFSMonitor' config
+		setting is in use.
 --

advice.c

@@ -88,6 +88,7 @@ static struct {
 	[ADVICE_SUBMODULE_MERGE_CONFLICT]               = { "submoduleMergeConflict" },
 	[ADVICE_SUGGEST_DETACHING_HEAD]			= { "suggestDetachingHead" },
 	[ADVICE_UPDATE_SPARSE_PATH]			= { "updateSparsePath" },
+	[ADVICE_USE_CORE_FSMONITOR_CONFIG]		= { "useCoreFSMonitorConfig" },
 	[ADVICE_WAITING_FOR_EDITOR]			= { "waitingForEditor" },
 	[ADVICE_WORKTREE_ADD_ORPHAN]			= { "worktreeAddOrphan" },
 };

advice.h

@@ -55,6 +55,7 @@ enum advice_type {
 	ADVICE_SUBMODULE_MERGE_CONFLICT,
 	ADVICE_SUGGEST_DETACHING_HEAD,
 	ADVICE_UPDATE_SPARSE_PATH,
+	ADVICE_USE_CORE_FSMONITOR_CONFIG,
 	ADVICE_WAITING_FOR_EDITOR,
 	ADVICE_WORKTREE_ADD_ORPHAN,
 };

fsmonitor-settings.c

@@ -5,6 +5,7 @@
 #include "fsmonitor-ipc.h"
 #include "fsmonitor-settings.h"
 #include "fsmonitor-path-utils.h"
+#include "advice.h"
 
 /*
  * We keep this structure definition private and have getters
@@ -100,6 +101,31 @@ static struct fsmonitor_settings *alloc_settings(void)
 	return s;
 }
 
+static int check_deprecated_builtin_config(struct repository *r)
+{
+	int core_use_builtin_fsmonitor = 0;
+
+	/*
+	 * If 'core.useBuiltinFSMonitor' is set, print a deprecation warning
+	 * suggesting the use of 'core.fsmonitor' instead. If the config is
+	 * set to true, set the appropriate mode and return 1 indicating that
+	 * the check resulted the config being set by this (deprecated) setting.
+	 */
+	if(!repo_config_get_bool(r, "core.useBuiltinFSMonitor", &core_use_builtin_fsmonitor) &&
+	   core_use_builtin_fsmonitor) {
+		if (!git_env_bool("GIT_SUPPRESS_USEBUILTINFSMONITOR_ADVICE", 0)) {
+			advise_if_enabled(ADVICE_USE_CORE_FSMONITOR_CONFIG,
+					  _("core.useBuiltinFSMonitor=true is deprecated;"
+					    "please set core.fsmonitor=true instead"));
+			setenv("GIT_SUPPRESS_USEBUILTINFSMONITOR_ADVICE", "1", 1);
+		}
+		fsm_settings__set_ipc(r);
+		return 1;
+	}
+
+	return 0;
+}
+
 static void lookup_fsmonitor_settings(struct repository *r)
 {
 	const char *const_str;
@@ -126,12 +152,16 @@ static void lookup_fsmonitor_settings(struct repository *r)
 		return;
 
 	case 1: /* config value was unset */
+		if (check_deprecated_builtin_config(r))
+			return;
+
 		const_str = getenv("GIT_TEST_FSMONITOR");
 		break;
 
 	case -1: /* config value set to an arbitrary string */
-		if (repo_config_get_pathname(r, "core.fsmonitor", &to_free))
-			return; /* should not happen */
+		if (check_deprecated_builtin_config(r) ||
+		    repo_config_get_pathname(r, "core.fsmonitor", &to_free))
+			return;
 		const_str = to_free;
 		break;