advice: revamp advise API

Currently it's very easy for the advice library's callers to miss
checking the visibility step before printing an advice. Also, it makes
more sense for this step to be handled by the advice library.

Add a new advise_if_enabled function that checks the visibility of
advice messages before printing.

Add a new helper advise_enabled to check the visibility of the advice
if the caller needs to carry out complicated processing based on that
value.

A list of config variables 'advice_config_keys' is added to be used by
list_config_advices() instead of 'advice_config[]' because we'll get
rid of 'advice_config[]' and the global variables once we migrate all
the callers to use the new APIs.

Also change the advise call in tag library from advise() to
advise_if_enabled() to construct an example of the usage of the new
API.

Signed-off-by: Heba Waly <heba.waly@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Author: HebaWaly

Makefile

@@ -695,6 +695,7 @@ X =
 
 PROGRAMS += $(patsubst %.o,git-%$X,$(PROGRAM_OBJS))
 
+TEST_BUILTINS_OBJS += test-advise.o
 TEST_BUILTINS_OBJS += test-chmtime.o
 TEST_BUILTINS_OBJS += test-config.o
 TEST_BUILTINS_OBJS += test-ctype.o

advice.c

@@ -96,13 +96,56 @@ static struct {
 	{ "pushNonFastForward", &advice_push_update_rejected }
 };
 
-static void vadvise(const char *advice, va_list params)
+static const char *advice_config_keys[] = {
+	[ADD_EMBEDDED_REPO]			 = "addEmbeddedRepo",
+	[AMWORKDIR]				 = "amWorkDir",
+	[CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME]	 = "checkoutAmbiguousRemoteBranchName",
+	[COMMIT_BEFORE_MERGE]			 = "commitBeforeMerge",
+	[DETACHED_HEAD]				 = "detachedHead",
+	[FETCH_SHOW_FORCED_UPDATES]		 = "fetchShowForcedUpdates",
+	[GRAFT_FILE_DEPRECATED]			 = "graftFileDeprecated",
+	[IGNORED_HOOK]				 = "ignoredHook",
+	[IMPLICIT_IDENTITY]			 = "implicitIdentity",
+	[NESTED_TAG]				 = "nestedTag",
+	[OBJECT_NAME_WARNING]			 = "objectNameWarning",
+	[PUSH_ALREADY_EXISTS]			 = "pushAlreadyExists",
+	[PUSH_FETCH_FIRST]			 = "pushFetchFirst",
+	[PUSH_NEEDS_FORCE]			 = "pushNeedsForce",
+
+	/* make this an alias for backward compatibility */
+	[PUSH_UPDATE_REJECTED_ALIAS]		 = "pushNonFastForward",
+
+	[PUSH_NON_FF_CURRENT]			 = "pushNonFFCurrent",
+	[PUSH_NON_FF_MATCHING]			 = "pushNonFFMatching",
+	[PUSH_UNQUALIFIED_REF_NAME]		 = "pushUnqualifiedRefName",
+	[PUSH_UPDATE_REJECTED]			 = "pushUpdateRejected",
+	[RESET_QUIET_WARNING]			 = "resetQuiet",
+	[RESOLVE_CONFLICT]			 = "resolveConflict",
+	[RM_HINTS]				 = "rmHints",
+	[SEQUENCER_IN_USE]			 = "sequencerInUse",
+	[SET_UPSTREAM_FAILURE]			 = "setupStreamFailure",
+	[STATUS_AHEAD_BEHIND_WARNING]		 = "statusAheadBehindWarning",
+	[STATUS_HINTS]				 = "statusHints",
+	[STATUS_U_OPTION]			 = "statusUoption",
+	[SUBMODULE_ALTERNATE_ERROR_STRATEGY_DIE] = "submoduleAlternateErrorStrategyDie",
+	[WAITING_FOR_EDITOR] 			 = "waitingForEditor",
+};
+
+static const char turn_off_instructions[] =
+N_("\n"
+   "Disable this message with \"git config %s false\"");
+
+static void vadvise(const char *advice, int display_instructions,
+		    char *key, va_list params)
 {
 	struct strbuf buf = STRBUF_INIT;
 	const char *cp, *np;
 
 	strbuf_vaddf(&buf, advice, params);
 
+	if (display_instructions)
+		strbuf_addf(&buf, turn_off_instructions, key);
+
 	for (cp = buf.buf; *cp; cp = np) {
 		np = strchrnul(cp, '\n');
 		fprintf(stderr,	_("%shint: %.*s%s\n"),
@@ -119,8 +162,43 @@ void advise(const char *advice, ...)
 {
 	va_list params;
 	va_start(params, advice);
-	vadvise(advice, params);
+	vadvise(advice, 0, "", params);
+	va_end(params);
+}
+
+static int get_config_value(enum advice_type type)
+{
+	int value = 1;
+	char *key = xstrfmt("%s.%s", "advice", advice_config_keys[type]);
+
+	git_config_get_bool(key, &value);
+	free(key);
+	return value;
+}
+
+int advice_enabled(enum advice_type type)
+{
+	switch (type) {
+	case PUSH_UPDATE_REJECTED:
+		return get_config_value(PUSH_UPDATE_REJECTED) &&
+		       get_config_value(PUSH_UPDATE_REJECTED_ALIAS);
+	default:
+		return get_config_value(type);
+	}
+}
+
+void advise_if_enabled(enum advice_type type, const char *advice, ...)
+{
+	char *key = xstrfmt("%s.%s", "advice", advice_config_keys[type]);
+	va_list params;
+
+	if (!advice_enabled(type))
+		return;
+
+	va_start(params, advice);
+	vadvise(advice, 1, key, params);
 	va_end(params);
+	free(key);
 }
 
 int git_default_advice_config(const char *var, const char *value)
@@ -159,8 +237,8 @@ void list_config_advices(struct string_list *list, const char *prefix)
 {
 	int i;
 
-	for (i = 0; i < ARRAY_SIZE(advice_config); i++)
-		list_config_item(list, prefix, advice_config[i].name);
+	for (i = 0; i < ARRAY_SIZE(advice_config_keys); i++)
+		list_config_item(list, prefix, advice_config_keys[i]);
 }
 
 int error_resolve_conflict(const char *me)

advice.h

@@ -32,9 +32,61 @@ extern int advice_checkout_ambiguous_remote_branch_name;
 extern int advice_nested_tag;
 extern int advice_submodule_alternate_error_strategy_die;
 
+/*
+ * To add a new advice, you need to:
+ * Define an advice_type.
+ * Add a new entry to advice_config_keys list.
+ * Add the new config variable to Documentation/config/advice.txt.
+ * Call advise_if_enabled to print your advice.
+ */
+enum advice_type {
+	ADD_EMBEDDED_REPO,
+	AMWORKDIR,
+	CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
+	COMMIT_BEFORE_MERGE,
+	DETACHED_HEAD,
+	FETCH_SHOW_FORCED_UPDATES,
+	GRAFT_FILE_DEPRECATED,
+	IGNORED_HOOK,
+	IMPLICIT_IDENTITY,
+	NESTED_TAG,
+	OBJECT_NAME_WARNING,
+	PUSH_ALREADY_EXISTS,
+	PUSH_FETCH_FIRST,
+	PUSH_NEEDS_FORCE,
+	PUSH_NON_FF_CURRENT,
+	PUSH_NON_FF_MATCHING,
+	PUSH_UNQUALIFIED_REF_NAME,
+	PUSH_UPDATE_REJECTED_ALIAS,
+	PUSH_UPDATE_REJECTED,
+	RESET_QUIET_WARNING,
+	RESOLVE_CONFLICT,
+	RM_HINTS,
+	SEQUENCER_IN_USE,
+	SET_UPSTREAM_FAILURE,
+	STATUS_AHEAD_BEHIND_WARNING,
+	STATUS_HINTS,
+	STATUS_U_OPTION,
+	SUBMODULE_ALTERNATE_ERROR_STRATEGY_DIE,
+	WAITING_FOR_EDITOR,
+};
+
+
 int git_default_advice_config(const char *var, const char *value);
 __attribute__((format (printf, 1, 2)))
 void advise(const char *advice, ...);
+
+/**
+ Checks if advice type is enabled (can be printed to the user).
+ Should be called before advise().
+ */
+int advice_enabled(enum advice_type type);
+
+/**
+ Checks the visibility of the advice before printing.
+ */
+void advise_if_enabled(enum advice_type type, const char *advice, ...);
+
 int error_resolve_conflict(const char *me);
 void NORETURN die_resolve_conflict(const char *me);
 void NORETURN die_conclude_merge(void);

t/helper/test-advise.c

@@ -0,0 +1,19 @@
+#include "test-tool.h"
+#include "cache.h"
+#include "advice.h"
+
+int cmd__advise_if_enabled(int argc, const char **argv)
+{
+	if (!argv[1])
+	die("usage: %s <advice>", argv[0]);
+
+	setup_git_directory();
+
+	/*
+	  Any advice type can be used for testing, but NESTED_TAG was selected
+	  here and in t0018 where this command is being executed.
+	 */
+	advise_if_enabled(NESTED_TAG, argv[1]);
+
+	return 0;
+}

t/helper/test-tool.c

@@ -14,6 +14,7 @@ struct test_cmd {
 };
 
 static struct test_cmd cmds[] = {
+	{ "advise", cmd__advise_if_enabled },
 	{ "chmtime", cmd__chmtime },
 	{ "config", cmd__config },
 	{ "ctype", cmd__ctype },

t/helper/test-tool.h

@@ -4,6 +4,7 @@
 #define USE_THE_INDEX_COMPATIBILITY_MACROS
 #include "git-compat-util.h"
 
+int cmd__advise_if_enabled(int argc, const char **argv);
 int cmd__chmtime(int argc, const char **argv);
 int cmd__config(int argc, const char **argv);
 int cmd__ctype(int argc, const char **argv);

t/t0018-advice.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+
+test_description='Test advise_if_enabled functionality'
+
+. ./test-lib.sh
+
+test_expect_success 'advice should be printed when config variable is unset' '
+	cat >expect <<-\EOF &&
+	hint: This is a piece of advice
+	hint: Disable this message with "git config advice.nestedTag false"
+	EOF
+	test-tool advise "This is a piece of advice" 2>actual &&
+	test_i18ncmp expect actual
+'
+
+test_expect_success 'advice should be printed when config variable is set to true' '
+	cat >expect <<-\EOF &&
+	hint: This is a piece of advice
+	hint: Disable this message with "git config advice.nestedTag false"
+	EOF
+	test_config advice.nestedTag true &&
+	test-tool advise "This is a piece of advice" 2>actual &&
+	test_i18ncmp expect actual
+'
+
+test_expect_success 'advice should not be printed when config variable is set to false' '
+	test_config advice.nestedTag false &&
+	test-tool advise "This is a piece of advice" 2>actual &&
+	test_must_be_empty actual
+'
+
+test_done