[PATCH/RFC] parse-options.c: make OPTION__COUNTUP consider negative values

The reason to make it consider negative values or more specifically
"unspecified" values is to differentiate between the option passed
once, multiple times or with --no-option. This makes the receiver
know what actually happened with the arguments which is particularly
required with option have multiple levels of that option.

Eg. :
initialize verbose = -1
`git commit` => verbose = -1
`git commit -v` => verbose = 1
`git commit -v -v` => verbose = 1
`git commit --no-verbose` => verbose = 0

Signed-off-by: Pranit Bauva <redacted>

---
The discussion on the mailing list[1] suggested this approach.
I plan to include this with my previous patch regarding "configuration
for commonly used command `git commit -v`" as this is a requirement for
latter.

[1] : http://thread.gmane.org/gmane.comp.version-control.git/289027
---
 Documentation/technical/api-parse-options.txt | 6 ++++--
 parse-options.c                               | 8 +++++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 5f0757d..a908d8a 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt

@@ -144,8 +144,10 @@ There are some macros to easily define options:
 
 `OPT_COUNTUP(short, long, &int_var, description)`::
 	Introduce a count-up option.
-	`int_var` is incremented on each use of `--option`, and
-	reset to zero with `--no-option`.
+	If the `int_var` is negative and `--option` is absent,
+	then it will retain its value. Otherwise it will first set
+	`int_var` to 0 and then increment it on each use of `--option`,
+	and reset to zero with `--no-option`.
 
 `OPT_BIT(short, long, &int_var, description, mask)`::
 	Introduce a boolean option.

diff --git a/parse-options.c b/parse-options.c
index 47a9192..86d30bd 100644
--- a/parse-options.c
+++ b/parse-options.c

@@ -110,7 +110,13 @@ static int get_value(struct parse_opt_ctx_t *p,
 		return 0;
 
 	case OPTION_COUNTUP:
-		*(int *)opt->value = unset ? 0 : *(int *)opt->value + 1;
+		if (unset)
+			*(int *)opt->value = 0;
+		else {
+			if (*(int *)opt->value < 0)
+				*(int *)opt->value = 0;
+			*(int *)opt->value += 1;
+		}
 		return 0;
 
 	case OPTION_SET_INT:

--

https://github.com/git/git/pull/212

On Wed, Mar 16, 2016 at 11:16:58PM +0000, Pranit Bauva wrote:

The reason to make it consider negative values or more specifically
"unspecified" values is to differentiate between the option passed
once, multiple times or with --no-option. This makes the receiver
know what actually happened with the arguments which is particularly
required with option have multiple levels of that option.

Eg. :
initialize verbose = -1
`git commit` => verbose = -1
`git commit -v` => verbose = 1
`git commit -v -v` => verbose = 1
`git commit --no-verbose` => verbose = 0

This second to last example would be 2, right?

That aside, this patch does mean that one can no longer use
OPT_COUNTUP() for negative values (i.e., the caller must start it at
either 0 or 1, and it must always go up from there).

And we would need to verify that all of the existing callers are OK with
this. Did you check that that (not rhetorical; I suspect they are all
OK, but somebody needs to check)?

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

When looking more carefully at builtin/commit.c for the other thread, it
occurred to me that OPT_BOOL might be a better fit for commit's "-v". It
really is a boolean "show the diff or not" and thus unlike the other
"make me more verbose". And OPT_BOOL already has the behavior you want,
I think.

-Peff

On Wed, Mar 16, 2016 at 9:50 PM, Jeff King [off-list ref] wrote:

On Wed, Mar 16, 2016 at 11:16:58PM +0000, Pranit Bauva wrote:

quoted

The reason to make it consider negative values or more specifically
"unspecified" values is to differentiate between the option passed
once, multiple times or with --no-option. This makes the receiver

This is inaccurate and rather confusing. It's not that an
"unspecified" value gives you the ability to "differentiate between
once, multiple time or with --no-option", but rather that it allows
you to determine wether --option or --no-option was encountered at
all.

quoted

know what actually happened with the arguments which is particularly
required with option have multiple levels of that option.

Eg. :
initialize verbose = -1
`git commit` => verbose = -1
`git commit -v` => verbose = 1
`git commit -v -v` => verbose = 1
`git commit --no-verbose` => verbose = 0

This second to last example would be 2, right?

Right.

I'm not sure that this example block is helpful, though. A clearer
commit message which does a better job of explaining the reason for
the change would likely eliminate the need for an example.

That aside, this patch does mean that one can no longer use
OPT_COUNTUP() for negative values (i.e., the caller must start it at
either 0 or 1, and it must always go up from there).

And we would need to verify that all of the existing callers are OK with
this. Did you check that that (not rhetorical; I suspect they are all
OK, but somebody needs to check)?

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

Indeed, I was envisioning a more conservative approach of having
OPT__VERBOSE use a custom callback or perhaps introducing a new
'flags' value or even (probably too ugly) abusing the 'defval' field
to specially indicate that it wants the "negative means unspecified"
behavior; the other consumers of OPT_COUNTUP would not request this
special behavior. But, as you say, changing the behavior of
OPT_COUNTUP unconditionally may not be a deal-breaker.

I also realized that Pranit can achieve the desired behavior without
modifying OPT__VERBOSE at all. Specifically, rather than initializing
his opt_verbose variable to -1, he can instead initialize it to 1.
Then:

* if --verbose is seen (one or more times), opt_verbose will be >=2,
and the real verbosity level will be (opt_verbose - 1)

* if --no-verbose is seen, opt_verbose will be 0

* if neither is seen, then opt_verbose will remain 1

However, I think this approach is far too ugly and non-obvious to
seriously suggest using it, whereas the change to OPT__VERBOSE is
easily understood and could prove useful in the future for other
commands with multiple verbosity levels.

When looking more carefully at builtin/commit.c for the other thread, it
occurred to me that OPT_BOOL might be a better fit for commit's "-v". It
really is a boolean "show the diff or not" and thus unlike the other
"make me more verbose". And OPT_BOOL already has the behavior you want,
I think.

For completeness (for readers of this thread), it was pointed out in
the other thread[1] that git-commit does indeed recognize multiple
verbosity levels, so changing it to use OPT_BOOL would be undesirable
(wrong).

[1]: http://thread.gmane.org/gmane.comp.version-control.git/289027/focus=289074

On Thu, Mar 17, 2016 at 3:28 AM, Eric Sunshine [off-list ref] wrote:

I also realized that Pranit can achieve the desired behavior without
modifying OPT__VERBOSE at all. Specifically, rather than initializing
his opt_verbose variable to -1, he can instead initialize it to 1.
Then:

* if --verbose is seen (one or more times), opt_verbose will be >=2,
and the real verbosity level will be (opt_verbose - 1)

* if --no-verbose is seen, opt_verbose will be 0

* if neither is seen, then opt_verbose will remain 1

Eh, this is bogus. "git commit --no-verbose --verbose" would leave
opt_verbose at 1, which would fool it into thinking neither had been
seen.

Thus, a further +1 for an OPT__VERBOSE which understands "unspecified".

However, I think this approach is far too ugly and non-obvious to
seriously suggest using it, whereas the change to OPT__VERBOSE is
easily understood and could prove useful in the future for other
commands with multiple verbosity levels.

On Thu, Mar 17, 2016 at 12:58 PM, Eric Sunshine [off-list ref] wrote:

On Wed, Mar 16, 2016 at 9:50 PM, Jeff King [off-list ref] wrote:

quoted

On Wed, Mar 16, 2016 at 11:16:58PM +0000, Pranit Bauva wrote:

quoted

The reason to make it consider negative values or more specifically
"unspecified" values is to differentiate between the option passed
once, multiple times or with --no-option. This makes the receiver

This is inaccurate and rather confusing. It's not that an
"unspecified" value gives you the ability to "differentiate between
once, multiple time or with --no-option", but rather that it allows
you to determine wether --option or --no-option was encountered at
all.

I guess the language wasn't very clear. I will change this.

quoted

quoted

know what actually happened with the arguments which is particularly
required with option have multiple levels of that option.

Eg. :
initialize verbose = -1
`git commit` => verbose = -1
`git commit -v` => verbose = 1
`git commit -v -v` => verbose = 1
`git commit --no-verbose` => verbose = 0

This second to last example would be 2, right?

Right.

My bad, it should be 2.

I'm not sure that this example block is helpful, though. A clearer
commit message which does a better job of explaining the reason for
the change would likely eliminate the need for an example.

quoted

That aside, this patch does mean that one can no longer use
OPT_COUNTUP() for negative values (i.e., the caller must start it at
either 0 or 1, and it must always go up from there).

And we would need to verify that all of the existing callers are OK with
this. Did you check that that (not rhetorical; I suspect they are all
OK, but somebody needs to check)?

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

Indeed, I was envisioning a more conservative approach of having
OPT__VERBOSE use a custom callback or perhaps introducing a new
'flags' value or even (probably too ugly) abusing the 'defval' field
to specially indicate that it wants the "negative means unspecified"
behavior; the other consumers of OPT_COUNTUP would not request this
special behavior. But, as you say, changing the behavior of
OPT_COUNTUP unconditionally may not be a deal-breaker.

I also realized that Pranit can achieve the desired behavior without
modifying OPT__VERBOSE at all. Specifically, rather than initializing
his opt_verbose variable to -1, he can instead initialize it to 1.
Then:

* if --verbose is seen (one or more times), opt_verbose will be >=2,
and the real verbosity level will be (opt_verbose - 1)

* if --no-verbose is seen, opt_verbose will be 0

* if neither is seen, then opt_verbose will remain 1

However, I think this approach is far too ugly and non-obvious to
seriously suggest using it, whereas the change to OPT__VERBOSE is
easily understood and could prove useful in the future for other
commands with multiple verbosity levels.

quoted

When looking more carefully at builtin/commit.c for the other thread, it
occurred to me that OPT_BOOL might be a better fit for commit's "-v". It
really is a boolean "show the diff or not" and thus unlike the other
"make me more verbose". And OPT_BOOL already has the behavior you want,
I think.

For completeness (for readers of this thread), it was pointed out in
the other thread[1] that git-commit does indeed recognize multiple
verbosity levels, so changing it to use OPT_BOOL would be undesirable
(wrong).

[1]: http://thread.gmane.org/gmane.comp.version-control.git/289027/focus=289074

Sorry for a little late reply. I was under the impression that I had
replied before.

On Thu, Mar 17, 2016 at 7:20 AM, Jeff King [off-list ref] wrote:

That aside, this patch does mean that one can no longer use
OPT_COUNTUP() for negative values (i.e., the caller must start it at
either 0 or 1, and it must always go up from there).


And we would need to verify that all of the existing callers are OK with
this. Did you check that that (not rhetorical; I suspect they are all
OK, but somebody needs to check)?

I did a grep on parse-options.h and saw that only "verbose", "quiet"
and "force" use OPT_COUNTUP().
I then did a git grep for "verbose = -1", "quiet = -1"
But with "force = -1" showed that "builtin/clean.c" uses it. On a bit
careful examination, this patch would not make difference to it.

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

As I am new here, I don't really know how to go about with this. Could
you describe in a little detail so that I can work on it?

When looking more carefully at builtin/commit.c for the other thread, it
occurred to me that OPT_BOOL might be a better fit for commit's "-v". It
really is a boolean "show the diff or not" and thus unlike the other
"make me more verbose". And OPT_BOOL already has the behavior you want,
I think.

-Peff

On Fri, Mar 18, 2016 at 04:53:34PM +0530, Pranit Bauva wrote:

quoted

And we would need to verify that all of the existing callers are OK with
this. Did you check that that (not rhetorical; I suspect they are all
OK, but somebody needs to check)?

I did a grep on parse-options.h and saw that only "verbose", "quiet"
and "force" use OPT_COUNTUP().
I then did a git grep for "verbose = -1", "quiet = -1"
But with "force = -1" showed that "builtin/clean.c" uses it. On a bit
careful examination, this patch would not make difference to it.

Yeah, I see that it handles the config for force separately, and then
munges the "-1" into 0 before we get to parse_options.

There are uses of COUNTUP in cmd_hash_object() and test-parse-options.c,
but I think they are both fine.

Grepping for "verbose = -1" would miss any cases where we call the
argument something else (e.g., apply_verbosely). So I think it would be
more thorough to grep for OPT__VERBOSE, etc, and then follow-up on
whatever variable they use.

I just did so, and I didn't see any problems.

quoted

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

As I am new here, I don't really know how to go about with this. Could
you describe in a little detail so that I can work on it?

A more canonical example is changing a function return value. Imagine I
have a function which returns "1" for success and "0" for error, and I
want to change it to return "0" for success and "-1" for error. If I do
so and update each caller, then merging with a branch that has a new
caller will not result in any conflicts (there is no textual link
between the callers and the function), but the result will be subtly
broken (the new caller will get the error-check wrong).

So we generally try to find some way that the compiler will notice the
breakage. E.g., if the function changes name when the return value
semantics change, or if it gains a new argument at the same time, then
the compiler will notice and complain. We still have to fix it up during
the merge, of course, but it's easy to spot.

Likewise here. If you change the semantics of OPT_COUNTUP(), then any
branch which introduces a new use of "int foo = -1" and expects the old
semantics will be subtly broken.

The obvious fix would be to switch the name (to OPT_COUNTUP_DEFAULT() or
something). But that's a bit painful, as almost nobody uses COUNTUP
directly, so we'd need OPT__VERBOSE_DEFAULT().

I do think we could also declare that it's sufficiently unlikely for
somebody to have been using the old semantics for OPT_COUNTUP() with
a negative integer (as it does not really do anything useful), and just
accept the risk.

Which in the end is the same as ignoring the problem in the first place,
but there is a big difference between not thinking about the problem,
and thinking about it and deciding it's not a problem. :)

-Peff

On Sun, Mar 20, 2016 at 9:40 AM, Jeff King [off-list ref] wrote:

quoted

quoted

We are also changing semantics without changing the interface, which
means any topics in flight (that you _cannot_ review, because you have
not seen them yet) may be subtly broken. To me that is not an absolute
deal-breaker, but something to weigh against the utility of the change.

As I am new here, I don't really know how to go about with this. Could
you describe in a little detail so that I can work on it?

A more canonical example is changing a function return value. Imagine I
have a function which returns "1" for success and "0" for error, and I
want to change it to return "0" for success and "-1" for error. If I do
so and update each caller, then merging with a branch that has a new
caller will not result in any conflicts (there is no textual link
between the callers and the function), but the result will be subtly
broken (the new caller will get the error-check wrong).

So we generally try to find some way that the compiler will notice the
breakage. E.g., if the function changes name when the return value
semantics change, or if it gains a new argument at the same time, then
the compiler will notice and complain. We still have to fix it up during
the merge, of course, but it's easy to spot.

Likewise here. If you change the semantics of OPT_COUNTUP(), then any
branch which introduces a new use of "int foo = -1" and expects the old
semantics will be subtly broken.

The obvious fix would be to switch the name (to OPT_COUNTUP_DEFAULT() or
something). But that's a bit painful, as almost nobody uses COUNTUP
directly, so we'd need OPT__VERBOSE_DEFAULT().

This is quite new to me. It took me some time to digest it.

Which in the end is the same as ignoring the problem in the first place,
but there is a big difference between not thinking about the problem,
and thinking about it and deciding it's not a problem. :)

True That! ;)

Regards,
Pranit Bauva