submodule.h: use a named enum for RECURSE_SUBMODULES_*

[phil-blain]

Changes since v1:

• converted one user of the enum from an 'int' to the new enum type,
  so the patch is not debug-only, as suggested by Glen.
• updated the commit message to use an 'int' as example of
  a local variable being compared with an enum constant, instead of
  using a struct member which is already of enum type, as pointed
  out by Junio
• added a little bit more explanation in the commit message as to
  how this patch can help when debugging.

CC: Emily Shaffer emilyshaffer@google.com
CC: Glen Choo chooglen@google.com

[phil-blain]

/submit

[gitgitgadget]

Submitted as pull.1111.git.1641410782015.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1111/phil-blain/submodule-recurse-enum-v1

To fetch this version to local tag pr-1111/phil-blain/submodule-recurse-enum-v1:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1111/phil-blain/submodule-recurse-enum-v1

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Using a named enum allows casting an integer to the enum type in both
> GDB and LLDB:
>
>     (gdb) p (enum diff_submodule_format) options->submodule_format
>     $1 = DIFF_SUBMODULE_LOG

Hmph, this was somewhat unexpected and quite disappointing.

Because that's not what those "Let's move away from #define'd
constants and use more enums" said when they sold their "enum" to
us.  In the diff_options struct, the .submodule_format member is of
type enum already, so, if we trust what they told us when they sold
their enums, "p options->submodule_format" should be enough to give
us "DIFF_SUBMODULE_LOG", not "1", as its output.  Do you really need
the cast in the above example?

> Name the enum listing the different RECURSE_SUBMODULES_* modes, to make
> debugging easier.

Even though this patch may be a good single step in the right
direction, until it is _used_ to declare a variable or a member of a
struct of that enum type, it probably is not useful as much as it
could be.  The user needs to know which enum is stored in that "int"
variable or member the user is interested in to cast it to.

That is, many changes like this one.

diff --git i/builtin/pull.c w/builtin/pull.c
index c8457619d8..f2fd4784df 100644
--- i/builtin/pull.c
+++ w/builtin/pull.c
@@ -71,7 +71,7 @@ static const char * const pull_usage[] = {
 /* Shared options */
 static int opt_verbosity;
 static char *opt_progress;
-static int recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
+static enum submodule_recurse_mode recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
 
 /* Options passed to git-merge or git-rebase */
 static enum rebase_type opt_rebase = -1;

[gitgitgadget]

On the Git mailing list, Philippe Blain wrote (reply to this):

Hi Junio,

Le 2022-01-05 à 16:20, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
>> Using a named enum allows casting an integer to the enum type in both
>> GDB and LLDB:
>>
>>      (gdb) p (enum diff_submodule_format) options->submodule_format
>>      $1 = DIFF_SUBMODULE_LOG
> 
> Hmph, this was somewhat unexpected and quite disappointing.
> 
> Because that's not what those "Let's move away from #define'd
> constants and use more enums" said when they sold their "enum" to
> us.  In the diff_options struct, the .submodule_format member is of
> type enum already, so, if we trust what they told us when they sold
> their enums, "p options->submodule_format" should be enough to give
> us "DIFF_SUBMODULE_LOG", not "1", as its output.  Do you really need
> the cast in the above example?

Yes, you are right that my example does not reflect what I'm saying, since
options->submodule_format is not an int. I checked and indeed we do not
need any cast to get "DIFF_SUBMODULE_LOG". We do need it when dealing with int's,
which is not the case here. I'll try to find a better example.

> 
>> Name the enum listing the different RECURSE_SUBMODULES_* modes, to make
>> debugging easier.
> 
> Even though this patch may be a good single step in the right
> direction, until it is _used_ to declare a variable or a member of a
> struct of that enum type, it probably is not useful as much as it
> could be.  The user needs to know which enum is stored in that "int"
> variable or member the user is interested in to cast it to.

Yes, that's true. But when I came across that, I was in a place of the
code where some int was compared with a constant in this enum,
RECURSE_SUBMODULES_something. So it would have been easy to check where
the enum is declared, learn its name and use it to cast the int to the enum
type. That's the kind of situation I have in mind.

> 
> That is, many changes like this one.
> 
> diff --git i/builtin/pull.c w/builtin/pull.c
> index c8457619d8..f2fd4784df 100644
> --- i/builtin/pull.c
> +++ w/builtin/pull.c
> @@ -71,7 +71,7 @@ static const char * const pull_usage[] = {
>   /* Shared options */
>   static int opt_verbosity;
>   static char *opt_progress;
> -static int recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
> +static enum submodule_recurse_mode recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
>   
>   /* Options passed to git-merge or git-rebase */
>   static enum rebase_type opt_rebase = -1;
> 

Yes, this is a parallel effort that could be done, I agree, but my patch
was meant to help in the mean time.

Thanks,

Philippe.

[gitgitgadget]

User Philippe Blain <levraiphilippeblain@gmail.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Glen Choo wrote (reply to this):

Philippe Blain <levraiphilippeblain@gmail.com> writes:

>> 
>> That is, many changes like this one.
>> 
>> diff --git i/builtin/pull.c w/builtin/pull.c
>> index c8457619d8..f2fd4784df 100644
>> --- i/builtin/pull.c
>> +++ w/builtin/pull.c
>> @@ -71,7 +71,7 @@ static const char * const pull_usage[] = {
>>   /* Shared options */
>>   static int opt_verbosity;
>>   static char *opt_progress;
>> -static int recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
>> +static enum submodule_recurse_mode recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
>>   
>>   /* Options passed to git-merge or git-rebase */
>>   static enum rebase_type opt_rebase = -1;
>> 
>
> Yes, this is a parallel effort that could be done, I agree, but my patch
> was meant to help in the mean time.

There are quite a few sites that could use this
s/int/enum submodule_recurse_mode change. I suppose one _could_ change
all of them at once, but that seems cumbersome to review and prone to
conflict.

So that this isn't debugger-only, I'd be happy with at least one change
(perhaps the one that inspired you to name the enum in the first place),
and making the other changes when it makes sense, e.g. I can do this for
the fetch machinery while I work on enhancements to `fetch
--recurse-submodules`.

[gitgitgadget]

On the Git mailing list, Glen Choo wrote (reply to this):

Junio C Hamano <gitster@pobox.com> writes:

> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
>> Using a named enum allows casting an integer to the enum type in both
>> GDB and LLDB:
>>
>>     (gdb) p (enum diff_submodule_format) options->submodule_format
>>     $1 = DIFF_SUBMODULE_LOG
>
> Hmph, this was somewhat unexpected and quite disappointing.
>
> Because that's not what those "Let's move away from #define'd
> constants and use more enums" said when they sold their "enum" to
> us.  In the diff_options struct, the .submodule_format member is of
> type enum already, so, if we trust what they told us when they sold
> their enums, "p options->submodule_format" should be enough to give
> us "DIFF_SUBMODULE_LOG", not "1", as its output.  Do you really need
> the cast in the above example?
>
>> Name the enum listing the different RECURSE_SUBMODULES_* modes, to make
>> debugging easier.
>
> Even though this patch may be a good single step in the right
> direction, until it is _used_ to declare a variable or a member of a
> struct of that enum type, it probably is not useful as much as it
> could be.  The user needs to know which enum is stored in that "int"
> variable or member the user is interested in to cast it to.
>
> That is, many changes like this one.
>
> diff --git i/builtin/pull.c w/builtin/pull.c
> index c8457619d8..f2fd4784df 100644
> --- i/builtin/pull.c
> +++ w/builtin/pull.c
> @@ -71,7 +71,7 @@ static const char * const pull_usage[] = {
>  /* Shared options */
>  static int opt_verbosity;
>  static char *opt_progress;
> -static int recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
> +static enum submodule_recurse_mode recurse_submodules = RECURSE_SUBMODULES_DEFAULT;
>  
>  /* Options passed to git-merge or git-rebase */
>  static enum rebase_type opt_rebase = -1;

Your comment on the use of RECURSE_SUBMODULES_DEFAULT elsewhere [1]
reminded me of how odd this enum actually is.

* submodule_recurse_mode is used almost exclusively by fetch and push 
  because they are the only commands that accept anything other than
  true/false.
* however, it is also used by
  submodule.c:config_update_recurse_submodules to store true/false (it
  don't even use RECURSE_SUBMODULES_DEFAULT!)

i.e. I suspect that the enum is only relevant for fetch/push, but its
values for _ON and _OFF have been co-opted for other things.

This patch and the suggestion of s/int/enum submodule_recurse_mode makes
sense, though I think we can take this a bit further in some follow-up
work:

If I am correct in my suspicion earlier, then submodule_recurse_mode can
be made even more specific, like "submodule_transport_mode", and all
non-transport related uses can be replaced with int.

If I am wrong and there are some legitimate uses for
submodule_recurse_mode that I have missed, it might still be worthwhile
to separate the different uses of the enum so that it doesn't end up
overloaded.

[1] https://lore.kernel.org/git/xmqqr19cjuzw.fsf@gitster.g

[phil-blain]

/submit

[gitgitgadget]

Submitted as pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1111/phil-blain/submodule-recurse-enum-v2

To fetch this version to local tag pr-1111/phil-blain/submodule-recurse-enum-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1111/phil-blain/submodule-recurse-enum-v2

[gitgitgadget]

On the Git mailing list, Glen Choo wrote (reply to this):

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Using a named enum allows casting an integer to the enum type in both
> GDB and LLDB:
>
>     $ gdb -q -ex 'b wt-status.c:44' -ex r --args ./git status
>     (gdb) p (enum color_wt_status) slot
>     $1 = WT_STATUS_ONBRANCH
>
>     $ lldb -o 'b wt-status.c:44' -o r -- ./git status
>     (lldb) p (color_wt_status) slot
>     (color_wt_status) $0 = WT_STATUS_ONBRANCH
>
> In LLDB, it's also required to cast in the reversed direction, i.e.
> cast an enum constant into its corresponding integer:
>
>     (lldb) p (int) color_wt_status::WT_STATUS_ONBRANCH
>     (int) $1 = 8
>
> Name the enum listing the different RECURSE_SUBMODULES_* modes, to make
> debugging easier. For example, when stepping through a part of the code
> where an int is compared with a constant in this enum, it allows casting
> the int to the enum type or vice-versa, after quickly checking where the
> enum constant is declared and learning the enum name.

Makes sense, and besides just making debugging easier, this would also
make code easier to read once we use the enum in more places (instead of
just int).

> As to not make this patch a debug-only change, convert the
> 'fetch_recurse' member of 'struct submodule' to use the newly named
> enum.

[...]

>  submodule-config.h | 2 +-
>  submodule.h        | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/submodule-config.h b/submodule-config.h
> index 65875b94ea5..55a4c3e0bd5 100644
> --- a/submodule-config.h
> +++ b/submodule-config.h
> @@ -37,7 +37,7 @@ struct submodule {
>  	const char *path;
>  	const char *name;
>  	const char *url;
> -	int fetch_recurse;
> +	enum submodule_recurse_mode fetch_recurse;
>  	const char *ignore;
>  	const char *branch;
>  	struct submodule_update_strategy update_strategy;
> diff --git a/submodule.h b/submodule.h
> index 6bd2c99fd99..55cf6f01d0c 100644
> --- a/submodule.h
> +++ b/submodule.h
> @@ -13,7 +13,7 @@ struct repository;
>  struct string_list;
>  struct strbuf;
>  
> -enum {
> +enum submodule_recurse_mode {
>  	RECURSE_SUBMODULES_ONLY = -5,
>  	RECURSE_SUBMODULES_CHECK = -4,
>  	RECURSE_SUBMODULES_ERROR = -3,

Like Junio, I think it would be nice to use the enum in more places, but
frankly there are so many sites that would need to change that I don't
think it's reasonable for one person to change them all.

So I'm happy to take this first step and do the rest of the refactoring
incrementally. I still think the enum's values are too disjointed and
should eventually be broken up, but that's a refactoring for later.

Reviewed-by: Glen Choo <chooglen@google.com>

[gitgitgadget]

This branch is now known as pb/submodule-recurse-mode-enum.

[gitgitgadget]

This patch series was integrated into seen via git@c2d40f2.

[gitgitgadget]

This patch series was integrated into seen via git@020bd49.

[gitgitgadget]

This patch series was integrated into seen via git@1f3876b.

[gitgitgadget]

This patch series was integrated into seen via git@4ab6e9c.

[gitgitgadget]

This patch series was integrated into seen via git@6edfe5a.

[gitgitgadget]

This patch series was integrated into seen via git@4e0f23b.

[gitgitgadget]

This patch series was integrated into seen via git@64c2aa3.

[gitgitgadget]

There was a status update in the "New Topics" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'?
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@897aca9.

[gitgitgadget]

This patch series was integrated into seen via git@5d58e33.

[gitgitgadget]

This patch series was integrated into seen via git@8d54e61.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@4469359.

[gitgitgadget]

This patch series was integrated into seen via git@bf0b4fe.

[gitgitgadget]

This patch series was integrated into seen via git@5f179c7.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@7a67800.

[gitgitgadget]

This patch series was integrated into seen via git@f9fed7e.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@817a468.

[gitgitgadget]

This patch series was integrated into seen via git@eec001f.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@cbcb30a.

[gitgitgadget]

This patch series was integrated into seen via git@a1c5abf.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'next'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@1f25dca.

[gitgitgadget]

This patch series was integrated into seen via git@a991da2.

[gitgitgadget]

This patch series was integrated into seen via git@571f6d1.

[gitgitgadget]

This patch series was integrated into next via git@1164a4c.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'master'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@7a62f2b.

[gitgitgadget]

This patch series was integrated into seen via git@98f0418.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch pb/submodule-recurse-mode-enum on the Git mailing list:

Small code clean-up.

Will merge to 'master'.
source: <pull.1111.v2.git.1649092211419.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@fe12db1.

[gitgitgadget]

This patch series was integrated into seen via git@24137ca.

[gitgitgadget]

This patch series was integrated into seen via git@c1ff525.

[gitgitgadget]

This patch series was integrated into seen via git@1f82e85.

[gitgitgadget]

This patch series was integrated into seen via git@ee0241b.

[gitgitgadget]

This patch series was integrated into master via git@ee0241b.

[gitgitgadget]

This patch series was integrated into next via git@ee0241b.

[gitgitgadget]

Closed via ee0241b.