[v5,2/3] advice: revamp advise API
diff mbox series

Message ID b7f10d060a41c1ef3d25e4c07be3747c7902b997.1582628141.git.gitgitgadget@gmail.com
State New
Headers show
Series
  • advice: revamp advise API
Related show

Commit Message

Johannes Schindelin via GitGitGadget Feb. 25, 2020, 10:55 a.m. UTC
From: Heba Waly <heba.waly@gmail.com>

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>
---
 Makefile               |  1 +
 advice.c               | 86 ++++++++++++++++++++++++++++++++++++++++--
 advice.h               | 52 +++++++++++++++++++++++++
 t/helper/test-advise.c | 19 ++++++++++
 t/helper/test-tool.c   |  1 +
 t/helper/test-tool.h   |  1 +
 t/t0018-advice.sh      | 32 ++++++++++++++++
 7 files changed, 188 insertions(+), 4 deletions(-)
 create mode 100644 t/helper/test-advise.c
 create mode 100755 t/t0018-advice.sh

Comments

Junio C Hamano Feb. 25, 2020, 5:40 p.m. UTC | #1
"Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Heba Waly <heba.waly@gmail.com>
>
> 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.

This is for step [3/3], isn't it?  I'll discard this paragraph.

>
> Signed-off-by: Heba Waly <heba.waly@gmail.com>
> ---
>  Makefile               |  1 +
>  advice.c               | 86 ++++++++++++++++++++++++++++++++++++++++--
>  advice.h               | 52 +++++++++++++++++++++++++
>  t/helper/test-advise.c | 19 ++++++++++
>  t/helper/test-tool.c   |  1 +
>  t/helper/test-tool.h   |  1 +
>  t/t0018-advice.sh      | 32 ++++++++++++++++
>  7 files changed, 188 insertions(+), 4 deletions(-)
>  create mode 100644 t/helper/test-advise.c
>  create mode 100755 t/t0018-advice.sh
>
> diff --git a/Makefile b/Makefile
> index 09f98b777ca..ed923a3e818 100644
> --- a/Makefile
> +++ b/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
> diff --git a/advice.c b/advice.c
> index fd836332dad..5c2068b8f8a 100644
> --- a/advice.c
> +++ b/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;
> +}

So, in this hypothetical but quite realistic example:

	if (advice_enabled(ADVICE_FOO)) {
		char *foo = expensive_preparation();
		advice_if_enabled(ADVICE_FOO, "use of %s is discouraged", foo);
	}

we end up formulating the "advice.*" key twice and ask git_config_get_bool()
about the same key twice?

> +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);
> +	}
> +}

Also, as "enum advice_type" will be part of the public API, and
there is little type checking for enums, we shouldn't be naming them
randomly like these---we'd at least want to use a common prefix,
like "ADVICE_", in front of them.  Those who are focused only on
advice subsystem may feel that names like PUSH_UPDATE_REJECTED are
sufficiently clear, but within the context of the whole system,
there is no cue that these UPCASED_WORDS identifiers belong to the
advice subsystem or somewhere else.

> +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;

Oh, no, make the number of calls to xstrfmr() three times, not
twice, as I said in the previous example.

I wonder if it would make the implementation better to do these:

 - Rename advice_config_keys[] to advice_setting[] that does not
   imply it is only about the keys;

 - This table will know, for each enum advice_type, which
   configuration variable enables it, *and* if it is enabled.

i.e.

        static struct {
                const char *config_key;
                int disabled;
        } advice_setting[] = {
                [ADVICE_ADD_EMBEDED_REPO] = { "addEmbeddedRepo" },
                [ADVICE_AM_WORK_DIR]      = { "amWorkDir" },
                ...
                [ADVICE_WAITING_FOR_EDITOR] = { "waitingForEditor" },
        };


Side Note: you have AMWORKDIR that is unreadable.  If the config
           name uses camelCase by convention, the UPCASED_WORDS
           should be separated with underscore at the same word
           boundary.

Then, upon the first call to advice_enabled(), call git_config()
with a callback like

	static int populate_advice_settings(const char *var, const char *value, void *cb)
	{
		int advice_type;
		const char *name;

		if (!skip_prefix(var, "advice.", &name))
			return 0;
		advice_type = find_advice_type_by_name(advice_setting, name);
		if (advice_type < 0)
			return 0; /* unknown advice.* variable */
		/* advice.foo=false means advice.foo is disabled */
		advice_setting[advice_type].disabled = !git_config_bool(var, value);
	}

only once.  Your get_config_value() would then become a mere lookup
in advice_setting[] array, e.g.

	int advice_enabled(unsigned advice_type)
	{
		static int initialized;

		if (!initialized) {
			initialized = 1;
			git_config(populate_advice_settings, NULL);
		}
		if (ARRAY_SIZE(advice_setting) <= advice_type)
			BUG("OOB advice type requested???");
		return !advice_setting[advice_type].disabled;
	}

with your "push-update-rejected has two names" twist added.

Hmm?
Emily Shaffer Feb. 25, 2020, 7:56 p.m. UTC | #2
On Tue, Feb 25, 2020 at 09:40:28AM -0800, Junio C Hamano wrote:
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > +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;
> > +}
> 
> So, in this hypothetical but quite realistic example:
> 
> 	if (advice_enabled(ADVICE_FOO)) {
> 		char *foo = expensive_preparation();
> 		advice_if_enabled(ADVICE_FOO, "use of %s is discouraged", foo);
> 	}
> 
> we end up formulating the "advice.*" key twice and ask git_config_get_bool()
> about the same key twice?
> 
> > +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;
> 
> Oh, no, make the number of calls to xstrfmr() three times, not
> twice, as I said in the previous example.
> 
> I wonder if it would make the implementation better to do these:
> 
>  - Rename advice_config_keys[] to advice_setting[] that does not
>    imply it is only about the keys;
> 
>  - This table will know, for each enum advice_type, which
>    configuration variable enables it, *and* if it is enabled.
> 
> i.e.
> 
>         static struct {
>                 const char *config_key;
>                 int disabled;
>         } advice_setting[] = {
>                 [ADVICE_ADD_EMBEDED_REPO] = { "addEmbeddedRepo" },
>                 [ADVICE_AM_WORK_DIR]      = { "amWorkDir" },
>                 ...
>                 [ADVICE_WAITING_FOR_EDITOR] = { "waitingForEditor" },
>         };
> 
> 
> Side Note: you have AMWORKDIR that is unreadable.  If the config
>            name uses camelCase by convention, the UPCASED_WORDS
>            should be separated with underscore at the same word
>            boundary.
> 
> Then, upon the first call to advice_enabled(), call git_config()
> with a callback like
> 
> 	static int populate_advice_settings(const char *var, const char *value, void *cb)
> 	{
> 		int advice_type;
> 		const char *name;
> 
> 		if (!skip_prefix(var, "advice.", &name))
> 			return 0;
> 		advice_type = find_advice_type_by_name(advice_setting, name);
> 		if (advice_type < 0)
> 			return 0; /* unknown advice.* variable */
> 		/* advice.foo=false means advice.foo is disabled */
> 		advice_setting[advice_type].disabled = !git_config_bool(var, value);
> 	}
> 
> only once.  Your get_config_value() would then become a mere lookup
> in advice_setting[] array, e.g.
> 
> 	int advice_enabled(unsigned advice_type)
> 	{
> 		static int initialized;
> 
> 		if (!initialized) {
> 			initialized = 1;
> 			git_config(populate_advice_settings, NULL);
> 		}
> 		if (ARRAY_SIZE(advice_setting) <= advice_type)
> 			BUG("OOB advice type requested???");
> 		return !advice_setting[advice_type].disabled;
> 	}
> 
> with your "push-update-rejected has two names" twist added.

I'm a little confused about the need to cache the result of
git_config_get_bool() - isn't that a lookup from a hashmap which is
already populated at setup time, and therefore inexpensive? I would
think the only expensive part here is the xstrfmt() calls, which it
seems like would be easy to do away with by storing the fully-qualified
advice key in the array instead. What am I missing?

 - Emily
Junio C Hamano Feb. 25, 2020, 8:09 p.m. UTC | #3
Emily Shaffer <emilyshaffer@google.com> writes:

>> ...  Your get_config_value() would then become a mere lookup
>> in advice_setting[] array, e.g.
>> 
>> 	int advice_enabled(unsigned advice_type)
>> 	{
>> 		static int initialized;
>> 
>> 		if (!initialized) {
>> 			initialized = 1;
>> 			git_config(populate_advice_settings, NULL);
>> 		}
>> 		if (ARRAY_SIZE(advice_setting) <= advice_type)
>> 			BUG("OOB advice type requested???");
>> 		return !advice_setting[advice_type].disabled;
>> 	}
>> 
>> with your "push-update-rejected has two names" twist added.
>
> I'm a little confused about the need to cache the result of
> git_config_get_bool() - isn't that a lookup from a hashmap which is
> already populated at setup time, and therefore inexpensive?

Looking up from hashmap with a string key is always more expensive
than indexing into a linear array with the array index.  Also, the
suggested arrangement makes the advice API implementation more self
contained, I'd think.
Junio C Hamano Feb. 25, 2020, 8:35 p.m. UTC | #4
Junio C Hamano <gitster@pobox.com> writes:

> Emily Shaffer <emilyshaffer@google.com> writes:
>
>>> ...  Your get_config_value() would then become a mere lookup
>>> in advice_setting[] array, e.g.
>>> 
>>> 	int advice_enabled(unsigned advice_type)
>>> 	{
>>> 		static int initialized;
>>> 
>>> 		if (!initialized) {
>>> 			initialized = 1;
>>> 			git_config(populate_advice_settings, NULL);
>>> 		}
>>> 		if (ARRAY_SIZE(advice_setting) <= advice_type)
>>> 			BUG("OOB advice type requested???");
>>> 		return !advice_setting[advice_type].disabled;
>>> 	}
>>> 
>>> with your "push-update-rejected has two names" twist added.

One beauty of the approach is that the "twist" can be done in the
initialization codepath, e.g.

 	int advice_enabled(unsigned advice_type)
 	{
 		static int initialized;
 
 		if (!initialized) {
 			initialized = 1;
 			git_config(populate_advice_settings, NULL);

                        advice_setting[ADVICE_PUSH_UPDATE_REJECTED] &=
                        advice_setting[ADVICE_PUSH_UPDATE_REJECTED_ALIAS];
 		}
 		if (ARRAY_SIZE(advice_setting) <= advice_type)
 			BUG("OOB advice type requested???");
 		return !advice_setting[advice_type].disabled;
 	}

which means that the function literally becomes an array access that
is guarded for out-of-bounds index.

Thanks, Emily, for making me look at the suggested code again to
realize this ;-)
Heba Waly Feb. 25, 2020, 9:19 p.m. UTC | #5
On Wed, Feb 26, 2020 at 6:40 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Heba Waly <heba.waly@gmail.com>
> >
> > 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.
>
> This is for step [3/3], isn't it?  I'll discard this paragraph.

Yes, should have been discarded.

> >
> > Signed-off-by: Heba Waly <heba.waly@gmail.com>
> > ---
> >  Makefile               |  1 +
> >  advice.c               | 86 ++++++++++++++++++++++++++++++++++++++++--
> >  advice.h               | 52 +++++++++++++++++++++++++
> >  t/helper/test-advise.c | 19 ++++++++++
> >  t/helper/test-tool.c   |  1 +
> >  t/helper/test-tool.h   |  1 +
> >  t/t0018-advice.sh      | 32 ++++++++++++++++
> >  7 files changed, 188 insertions(+), 4 deletions(-)
> >  create mode 100644 t/helper/test-advise.c
> >  create mode 100755 t/t0018-advice.sh
> >
> > diff --git a/Makefile b/Makefile
> > index 09f98b777ca..ed923a3e818 100644
> > --- a/Makefile
> > +++ b/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
> > diff --git a/advice.c b/advice.c
> > index fd836332dad..5c2068b8f8a 100644
> > --- a/advice.c
> > +++ b/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;
> > +}
>
> So, in this hypothetical but quite realistic example:
>
>         if (advice_enabled(ADVICE_FOO)) {
>                 char *foo = expensive_preparation();
>                 advice_if_enabled(ADVICE_FOO, "use of %s is discouraged", foo);
>         }
>
> we end up formulating the "advice.*" key twice and ask git_config_get_bool()
> about the same key twice?

No, in the above example, advise() should be called not advise_if_enabled().
As we discussed in the beginning of this thread.
https://public-inbox.org/git/xmqqa75py7u8.fsf@gitster-ct.c.googlers.com/

>
> > +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);
> > +     }
> > +}
>
> Also, as "enum advice_type" will be part of the public API, and
> there is little type checking for enums, we shouldn't be naming them
> randomly like these---we'd at least want to use a common prefix,
> like "ADVICE_", in front of them.  Those who are focused only on
> advice subsystem may feel that names like PUSH_UPDATE_REJECTED are
> sufficiently clear, but within the context of the whole system,
> there is no cue that these UPCASED_WORDS identifiers belong to the
> advice subsystem or somewhere else.
>

I agree.

> > +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;
>
> Oh, no, make the number of calls to xstrfmr() three times, not
> twice, as I said in the previous example.
>
> I wonder if it would make the implementation better to do these:
>
>  - Rename advice_config_keys[] to advice_setting[] that does not
>    imply it is only about the keys;
>
>  - This table will know, for each enum advice_type, which
>    configuration variable enables it, *and* if it is enabled.
>
> i.e.
>
>         static struct {
>                 const char *config_key;
>                 int disabled;
>         } advice_setting[] = {
>                 [ADVICE_ADD_EMBEDED_REPO] = { "addEmbeddedRepo" },
>                 [ADVICE_AM_WORK_DIR]      = { "amWorkDir" },
>                 ...
>                 [ADVICE_WAITING_FOR_EDITOR] = { "waitingForEditor" },
>         };
>
>
> Side Note: you have AMWORKDIR that is unreadable.  If the config
>            name uses camelCase by convention, the UPCASED_WORDS
>            should be separated with underscore at the same word
>            boundary.

I followed the original global variable name, which is
`advice_amworkdir`, we can change that.

>
> Then, upon the first call to advice_enabled(), call git_config()
> with a callback like
>
>         static int populate_advice_settings(const char *var, const char *value, void *cb)
>         {
>                 int advice_type;
>                 const char *name;
>
>                 if (!skip_prefix(var, "advice.", &name))
>                         return 0;
>                 advice_type = find_advice_type_by_name(advice_setting, name);
>                 if (advice_type < 0)
>                         return 0; /* unknown advice.* variable */
>                 /* advice.foo=false means advice.foo is disabled */
>                 advice_setting[advice_type].disabled = !git_config_bool(var, value);
>         }
>
> only once.  Your get_config_value() would then become a mere lookup
> in advice_setting[] array, e.g.
>
>         int advice_enabled(unsigned advice_type)
>         {
>                 static int initialized;
>
>                 if (!initialized) {
>                         initialized = 1;
>                         git_config(populate_advice_settings, NULL);
>                 }
>                 if (ARRAY_SIZE(advice_setting) <= advice_type)
>                         BUG("OOB advice type requested???");
>                 return !advice_setting[advice_type].disabled;
>         }
>
> with your "push-update-rejected has two names" twist added.
>
> Hmm?

I wasn't very happy about having to keep the list of config keys in
memory, but that was a good enough solution for now.
I also agree that there could be benefits for caching the values, as
you mentioned it will be less expensive than looking up from the
hashmap, but this array will grow with every new advice added to the
system. And this data is already loaded in the hashmap, so we are
duplicating it.
So are the benefits worth the duplication? I don't know.

Thanks,
Heba
Junio C Hamano Feb. 25, 2020, 10:02 p.m. UTC | #6
Heba Waly <heba.waly@gmail.com> writes:

> I wasn't very happy about having to keep the list of config keys in
> memory, but that was a good enough solution for now.

If you force your programmers to specify the advice_type as a small
integer, and the setting is stored in the config as string keys,
somebody MUST have a table to convert from one to the other.  So I
am not sure if it is even sensible to feel unhappy about having to
have a list in the first place.  Are we looking for some kind of
miracles ;-)?

On the other hand, it does bother my sense of aesthetics a lot it
our code forces our programmers to give a small integer to us, only
so that we convert that integer to a string and use the string to
look up a value in a hashtable, every time the program wants a
lookup.  Performance-wise, that's not a huge downside.  It just rubs
my sense of code hygiene the wrong way.

Especially when the primary way for our programmers to specify which
advice they are talking about is by passing an integer, and if we
need to have a table indexed by that integer in the program anyway.

We could instead do something like:

    /* advice.h */
    #ifndef _ADVICE_H_
    #define _ADVICE_H_ 1
    extern const char ADVICE_ADD_EMBEDDED_REPO[];
    extern const char ADVICE_AM_WORK_DIR[];
    ...
    #endif

    /* advice.c */
    const char ADVICE_ADD_EMBEDDED_REPO[] = "advice.addEmbeddedRepo";
    const char ADVICE_ADD_AM_WORK_DIR[] = "advice.amWorkDir";
    ...

and the callers can still do

    advise_if_enabled(ADVICE_NESTED_TAG,
		      _(message_advice_nested_tag), tag, object_ref);

with the benefit of compiler catching a silly typo, without having
to have any "enum-to-string" table while letting the config API
layer do any caching transparently.  As these calls will never be
placed in a performance critical codepath, that might be more
appropriate.  

I dunno.
Heba Waly Feb. 26, 2020, 12:37 a.m. UTC | #7
On Wed, Feb 26, 2020 at 11:02 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Heba Waly <heba.waly@gmail.com> writes:
>
> > I wasn't very happy about having to keep the list of config keys in
> > memory, but that was a good enough solution for now.
>
> If you force your programmers to specify the advice_type as a small
> integer, and the setting is stored in the config as string keys,
> somebody MUST have a table to convert from one to the other.  So I
> am not sure if it is even sensible to feel unhappy about having to
> have a list in the first place.  Are we looking for some kind of
> miracles ;-)?
>

The reason I had to add the list of keys wasn't the enums, but because
it's needed by list_config_advices() which returns all the advice
config variables names. This is used when the user runs `git help
--config`.
And as a result, I added the enum to utilize it in accessing the list
and avoid hard coded strings in functions calls.

> On the other hand, it does bother my sense of aesthetics a lot it
> our code forces our programmers to give a small integer to us, only
> so that we convert that integer to a string and use the string to
> look up a value in a hashtable, every time the program wants a
> lookup.  Performance-wise, that's not a huge downside.  It just rubs
> my sense of code hygiene the wrong way.
>
> Especially when the primary way for our programmers to specify which
> advice they are talking about is by passing an integer, and if we
> need to have a table indexed by that integer in the program anyway.
>
> We could instead do something like:
>
>     /* advice.h */
>     #ifndef _ADVICE_H_
>     #define _ADVICE_H_ 1
>     extern const char ADVICE_ADD_EMBEDDED_REPO[];
>     extern const char ADVICE_AM_WORK_DIR[];
>     ...
>     #endif
>
>     /* advice.c */
>     const char ADVICE_ADD_EMBEDDED_REPO[] = "advice.addEmbeddedRepo";
>     const char ADVICE_ADD_AM_WORK_DIR[] = "advice.amWorkDir";
>     ...
>
> and the callers can still do
>
>     advise_if_enabled(ADVICE_NESTED_TAG,
>                       _(message_advice_nested_tag), tag, object_ref);
>
> with the benefit of compiler catching a silly typo, without having
> to have any "enum-to-string" table while letting the config API
> layer do any caching transparently.  As these calls will never be
> placed in a performance critical codepath, that might be more
> appropriate.
>

I'm not against this approach as well, but as I mentioned above, we
need a list of keys to be returned by list_config_advices(), that's
why defining the constant strings will not be sufficient in our case.

Thanks,
Heba
Junio C Hamano Feb. 26, 2020, 3:03 a.m. UTC | #8
Heba Waly <heba.waly@gmail.com> writes:

> I'm not against this approach as well, but as I mentioned above, we
> need a list of keys to be returned by list_config_advices(), that's
> why defining the constant strings will not be sufficient in our case.

Sorry, but I do not get it.  

Either you use enum or a bunch of variables of type const char [],
"list all of them" would need an array whose elements are all of
them, so

        const char ADVICE_FOO[] = "advice.foo";
        const char ADVICE_BAR[] = "advice.bar";
        ...

        static const char *all_advice_type[] = {
                ADVICE_FOO, ADVICE_BAR, ...
        };

	void for_each_advice_type(int (*fn)(const char *name))
	{
		int i;
		for (i = 0; i < ARRAY_SIZE(all_advice_type); i++)
			fn(all_advice_type[i]);
	}

would be sufficient, and I do not think it takes any more effort to
create and manage than using an array indexed with the enum, no?
Heba Waly Feb. 26, 2020, 8:28 p.m. UTC | #9
On Wed, Feb 26, 2020 at 4:03 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Heba Waly <heba.waly@gmail.com> writes:
>
> > I'm not against this approach as well, but as I mentioned above, we
> > need a list of keys to be returned by list_config_advices(), that's
> > why defining the constant strings will not be sufficient in our case.
>
> Sorry, but I do not get it.
>
> Either you use enum or a bunch of variables of type const char [],
> "list all of them" would need an array whose elements are all of
> them, so
>
>         const char ADVICE_FOO[] = "advice.foo";
>         const char ADVICE_BAR[] = "advice.bar";
>         ...
>
>         static const char *all_advice_type[] = {
>                 ADVICE_FOO, ADVICE_BAR, ...
>         };
>
>         void for_each_advice_type(int (*fn)(const char *name))
>         {
>                 int i;
>                 for (i = 0; i < ARRAY_SIZE(all_advice_type); i++)
>                         fn(all_advice_type[i]);
>         }
>
> would be sufficient, and I do not think it takes any more effort to
> create and manage than using an array indexed with the enum, no?
>

hmm, you're right, I just personally prefer having related variables
collected in one data structure (whenever possible) like a list (or
enum in this case) rather than defining each independently as a const
variable. On the other hand, I understand that you'd prefer to skip
the extra step of converting the enum to string.
hmmm ok, I'll change the enum and send a new version soon.

Thanks,
Heba
Junio C Hamano Feb. 26, 2020, 8:44 p.m. UTC | #10
Heba Waly <heba.waly@gmail.com> writes:

> variable. On the other hand, I understand that you'd prefer to skip
> the extra step of converting the enum to string.
> hmmm ok, I'll change the enum and send a new version soon.

To avoid misunderstanding, I do not object to enum based approach at
all.  In fact, I'd rather prefer it over bunch of const strings that
can be checked by the compiler.  What I do not prefer compared to
either of these approaches is to accept enum from the caller and
convert it to string to consult config API every time, which is
worse than "bunch of const strings".

Thanks.
Jonathan Tan Feb. 26, 2020, 9:48 p.m. UTC | #11
> Heba Waly <heba.waly@gmail.com> writes:
> 
> > I'm not against this approach as well, but as I mentioned above, we
> > need a list of keys to be returned by list_config_advices(), that's
> > why defining the constant strings will not be sufficient in our case.
> 
> Sorry, but I do not get it.  
> 
> Either you use enum or a bunch of variables of type const char [],
> "list all of them" would need an array whose elements are all of
> them, so
> 
>         const char ADVICE_FOO[] = "advice.foo";
>         const char ADVICE_BAR[] = "advice.bar";
>         ...
> 
>         static const char *all_advice_type[] = {
>                 ADVICE_FOO, ADVICE_BAR, ...
>         };
> 
> 	void for_each_advice_type(int (*fn)(const char *name))
> 	{
> 		int i;
> 		for (i = 0; i < ARRAY_SIZE(all_advice_type); i++)
> 			fn(all_advice_type[i]);
> 	}
> 
> would be sufficient, and I do not think it takes any more effort to
> create and manage than using an array indexed with the enum, no?

With the enum:

(.h)
enum advice_type {
	ADVICE_FOO,
	ADVICE_BAR
};

(.c)
static const char *advice_config_keys[] = {
	[ADVICE_FOO] = "advice.foo",
	[ADVICE_BAR] = "advice.bar"
};
/* No need for all_advice_type because we can loop over advice_config_keys */

With the bunch of variables of type const char []:

(.h)
extern const char ADVICE_FOO[];
extern const char ADVICE_BAR[];

(.c)
const char ADVICE_FOO[] = "advice.foo";
const char ADVICE_BAR[] = "advice.bar";
static const char *all_advice_type[] = {
	ADVICE_FOO,
	ADVICE_BAR
};

Junio, is this what you meant? It seems to me that there is an extra array to
be managed in the latter case. Admittedly, this is a tradeoff against needing
to convert the enum to a string when checking config, as you describe [1].

[1] https://lore.kernel.org/git/xmqq7e09hydx.fsf@gitster-ct.c.googlers.com/

Patch
diff mbox series

diff --git a/Makefile b/Makefile
index 09f98b777ca..ed923a3e818 100644
--- a/Makefile
+++ b/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
diff --git a/advice.c b/advice.c
index fd836332dad..5c2068b8f8a 100644
--- a/advice.c
+++ b/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)
diff --git a/advice.h b/advice.h
index b706780614d..a8461a362a3 100644
--- a/advice.h
+++ b/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);
diff --git a/t/helper/test-advise.c b/t/helper/test-advise.c
new file mode 100644
index 00000000000..279cad6460e
--- /dev/null
+++ b/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;
+}
diff --git a/t/helper/test-tool.c b/t/helper/test-tool.c
index f20989d4497..6977badc690 100644
--- a/t/helper/test-tool.c
+++ b/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 },
diff --git a/t/helper/test-tool.h b/t/helper/test-tool.h
index 8ed2af71d1b..ca5e33b842f 100644
--- a/t/helper/test-tool.h
+++ b/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);
diff --git a/t/t0018-advice.sh b/t/t0018-advice.sh
new file mode 100755
index 00000000000..e03554d2f34
--- /dev/null
+++ b/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