[PATCH 0/1] commit-graph: drop top-level --[no-]progress

This patch provides one way to fix an issue that SZEDER described in [1]. The
issue is that `git commit-graph` began accepting `--[no-]progress` as a
top-level argument as an unintentional side-effect of 84e4484f12 (commit-graph:
use parse_options_concat(), 2021-08-23).

Some discussion beginning at [2] indicates a couple of reasons why this is
undesirable, and they are summarized in the patch below.

But most importantly, if we do want to get rid of the top-level
`--[no-]progress`, then we should act quickly to do it before 84e4484f12 (which
currently isn't tagged) is released.

An open question is whether the same should be done for the multi-pack-index
command, whose top-level support for `--[no-]progress` was released in v2.32.0
with 60ca94769c (builtin/multi-pack-index.c: split sub-commands, 2021-03-30).

[1]: https://lore.kernel.org/git/20210917211337.GC2118053@szeder.dev/
[2]: https://lore.kernel.org/git/YUUQzswYL5x74Tps@coredump.intra.peff.net/

Taylor Blau (1):
  builtin/commit-graph.c: don't accept common --[no-]progress

 builtin/commit-graph.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

-- 
2.33.0.96.g73915697e6

In 84e4484f12 (commit-graph: use parse_options_concat(), 2021-08-23) we
unified common options of commit-graph's subcommands into a single
"common_opts" array.

But 84e4484f12 introduced a behavior change which is to accept the
"--[no-]progress" option before any sub-commands, e.g.,

    git commit-graph --progress write ...

Prior to that commit, the above would error out with "unknown option".

There are two issues with this behavior change. First is that the
top-level --[no-]progress is not always respected. This is because
isatty(2) is performed in the sub-commands, which unconditionally
overwrites any --[no-]progress that was given at the top-level.

But the second issue is that the existing sub-commands of commit-graph
only happen to both have a sensible interpretation of what `--progress`
or `--no-progress` means. If we ever added a sub-command which didn't
have a notion of progress, we would be forced to ignore the top-level
`--[no-]progress` altogether.

Since we haven't released a version of Git that supports --[no-]progress
as a top-level option for `git commit-graph`, let's remove it.

Suggested-by: SZEDER Gábor <redacted>
Signed-off-by: Taylor Blau <redacted>
---
 builtin/commit-graph.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 21fc6e934b..067587a0fd 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c

@@ -50,8 +50,6 @@ static struct option common_opts[] = {
 	OPT_STRING(0, "object-dir", &opts.obj_dir,
 		   N_("dir"),
 		   N_("the object directory to store the graph")),
-	OPT_BOOL(0, "progress", &opts.progress,
-		 N_("force progress reporting")),
 	OPT_END()
 };
 

@@ -95,6 +93,8 @@ static int graph_verify(int argc, const char **argv)
 	static struct option builtin_commit_graph_verify_options[] = {
 		OPT_BOOL(0, "shallow", &opts.shallow,
 			 N_("if the commit-graph is split, only verify the tip file")),
+		OPT_BOOL(0, "progress", &opts.progress,
+			 N_("force progress reporting")),
 		OPT_END(),
 	};
 	struct option *options = add_common_options(builtin_commit_graph_verify_options);

@@ -246,6 +246,8 @@ static int graph_write(int argc, const char **argv)
 		OPT_CALLBACK_F(0, "max-new-filters", &write_opts.max_new_filters,
 			NULL, N_("maximum number of changed-path Bloom filters to compute"),
 			0, write_option_max_new_filters),
+		OPT_BOOL(0, "progress", &opts.progress,
+			 N_("force progress reporting")),
 		OPT_END(),
 	};
 	struct option *options = add_common_options(builtin_commit_graph_write_options);

-- 
2.33.0.96.g73915697e6

On 9/18/2021 12:02 PM, Taylor Blau wrote:

In 84e4484f12 (commit-graph: use parse_options_concat(), 2021-08-23) we
unified common options of commit-graph's subcommands into a single
"common_opts" array.

But 84e4484f12 introduced a behavior change which is to accept the
"--[no-]progress" option before any sub-commands, e.g.,

    git commit-graph --progress write ...

Prior to that commit, the above would error out with "unknown option".

There are two issues with this behavior change. First is that the
top-level --[no-]progress is not always respected. This is because
isatty(2) is performed in the sub-commands, which unconditionally
overwrites any --[no-]progress that was given at the top-level.

But the second issue is that the existing sub-commands of commit-graph
only happen to both have a sensible interpretation of what `--progress`
or `--no-progress` means. If we ever added a sub-command which didn't
have a notion of progress, we would be forced to ignore the top-level
`--[no-]progress` altogether.

Since we haven't released a version of Git that supports --[no-]progress
as a top-level option for `git commit-graph`, let's remove it.

I agree that is the best way to respond right now. Moving it to
top-level will need more work.

Meanwhile this diff is easy to verify.

Thanks,
-Stolee

On Mon, Sep 20, 2021 at 08:46:32AM -0400, Derrick Stolee wrote:

On 9/18/2021 12:02 PM, Taylor Blau wrote:

quoted

Since we haven't released a version of Git that supports --[no-]progress
as a top-level option for `git commit-graph`, let's remove it.

I agree that is the best way to respond right now. Moving it to
top-level will need more work.

SZEDER posted a patch in [1] which would allow us to define a top-level
`--[no-]progress` option for the commit-graph builtin. (I'm assuming
that you meant the builtin when you said "top-level", and not git
itself).

But see some of his commentary above the patch in [1] about why we may
want to avoid applying something like his patch, in particular:

  In general, even when all subcommands of a git command understand a
  particular --option, that does not mean that it's a good idea to teach
  that option to that git command.  E.g. what if we later add another
  subcommand for which that --option doesn't make any sense?  And from
  the quoted discussion above it seems that teaching 'git commit-graph'
  the '--progress' option was not intentional at all.

This patch has the added advantage that we can always "go back" to
SZEDER's approach and make `--[no-]progress` work as an option to `git
commit-graph`. But doing this buys us some time to make sure that is the
approach we want to take.

Thanks,
Taylor

[1]: https://lore.kernel.org/git/20210917211337.GC2118053@szeder.dev/