Skip to contentSkip to conversation

submodule: explicitly specify on-demand upon push

PATCH In review Jonathan Tan 3 participants 10 messages Nov 8, 2022 – Nov 16, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 submodule: explicitly specify on-demand upon push

When running "git push --recurse-submodules=on-demand" (or "=only") on a superproject with nested submodules and assuming default configurations, only the top-level submodules are pushed. This is because recursion into the top-level submodules is performed with "git push" (without any additional relevant options), and the default configuration is to not recurse to nested submodules.

Therefore, instead of recursing with "git push" without any additional relevant options, recurse with "--recurse-submodules=on-demand".

This now means that any push.recurseSubmodules configuration in any submodule is no longer respected: only the configuration (or CLI argument to override it) of the superproject is used. Update the documentation accordingly.

(As a side effect of making the documentation of both the CLI argument and the config variable consistent, the config variable is now documented to support "only". This has been the case for a while, and I have also included a test to show that.)

---
 Documentation/config/push.txt  | 18 ++++------
 Documentation/git-push.txt     |  2 +-
 submodule.c                    |  9 +++++
 t/t5531-deep-submodule-push.sh | 66 ++++++++++++++++++++++++++++++++++
 4 files changed, 82 insertions(+), 13 deletions(-)
Documentation/config/push.txt +6 -12
index 7386fea225..9960afef84 100644
@@ -110,20 +110,14 @@ This will result in only b (a and c are cleared).
 ----
 
 push.recurseSubmodules::
-	Make sure all submodule commits used by the revisions to be pushed
-	are available on a remote-tracking branch. If the value is 'check'
-	then Git will verify that all submodule commits that changed in the
-	revisions to be pushed are available on at least one remote of the
-	submodule. If any commits are missing, the push will be aborted and
-	exit with non-zero status. If the value is 'on-demand' then all
-	submodules that changed in the revisions to be pushed will be
-	pushed. If on-demand was not able to push all necessary revisions
-	it will also be aborted and exit with non-zero status. If the value
-	is 'no' then default behavior of ignoring submodules when pushing
-	is retained. You may override this configuration at time of push by
-	specifying '--recurse-submodules=check|on-demand|no'.
+	May be "check", "on-demand", "only", or "no", with the same behavior
+	as that of "push --recurse-submodules".
 	If not set, 'no' is used by default, unless 'submodule.recurse' is
 	set (in which case a 'true' value means 'on-demand').
++
+Whenever "git push" is executed, only the configuration of the
+repository in which the command was run is used, not any of its
+submodules (even if any such submodule contains its own submodules).
 
 push.useForceIfIncludes::
 	If set to "true", it is equivalent to specifying
Documentation/git-push.txt +1 -1
index def7657ef9..c63a4c186b 100644
@@ -407,7 +407,7 @@ Specifying `--no-force-if-includes` disables this behavior.
 	remote of the submodule. If any commits are missing the push will
 	be aborted and exit with non-zero status. If 'on-demand' is used
 	all submodules that changed in the revisions to be pushed will be
-	pushed. If on-demand was not able to push all necessary revisions it will
+	recursively pushed. If on-demand was not able to push all necessary revisions it will
 	also be aborted and exit with non-zero status. If 'only' is used all
 	submodules will be recursively pushed while the superproject is left
 	unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
submodule.c +9 -0
index bf7a2c7918..06ee74a282 100644
@@ -1130,6 +1130,15 @@ static int push_submodule(const char *path,
 	if (for_each_remote_ref_submodule(path, has_remote, NULL) > 0) {
 		struct child_process cp = CHILD_PROCESS_INIT;
 		strvec_push(&cp.args, "push");
+		/*
+		 * If this function is called, it is because the user
+		 * requested recursion through
+		 * --recurse-submodules=on-demand or
+		 * --recurse-submodules=only (or the equivalent
+		 * config). In both cases, we should fully recurse into
+		 * all submodules and their descendants.
+		 */
+		strvec_push(&cp.args, "--recurse-submodules=on-demand");
 		if (dry_run)
 			strvec_push(&cp.args, "--dry-run");
 
t/t5531-deep-submodule-push.sh +66 -0

72 lines not on this page · raw message

Signature · 1 line
2.38.1.431.g37b22c650d-goog
#1 lore raw
Quoted 4 lines · Jonathan Tan

This now means that any push.recurseSubmodules configuration in any submodule is no longer respected: only the configuration (or CLI argument to override it) of the superproject is used. Update the documentation accordingly.

Hmm. Is that a desired outcome or an unfortunate side-effect of the implementation below?

Not having thought about this a lot, the behavior I might expect is something along the lines of recursively pushing throughout the submodule tree, stopping the recursion as soon as we get to a nested submodule which says "don't push any of my children".

On the other hand, I could sympathize with a compelling argument that the superproject alone should be in charge of determining what gets pushed.

Though TBH, it seems like the former is more convincing. If I depend on an external repository through a submodule, and that repository itself has submodules, it would be nice to configure (once) that I don't want to even try and push any of that repository's children.

Thanks,
Taylor

#2 lore raw
Quoted 8 lines · Taylor Blau
Quoted 4 lines · Jonathan Tan

This now means that any push.recurseSubmodules configuration in any submodule is no longer respected: only the configuration (or CLI argument to override it) of the superproject is used. Update the documentation accordingly.

Hmm. Is that a desired outcome or an unfortunate side-effect of the implementation below?

What started this effort was investigating whether push.recurseSubmodules could be set to "only", since that is something that would be useful at $DAYJOB. It turns out that push.recurseSubmodules is not documented to take "only", but it is supported, with the caveat that if a repository has push.recurseSubmodules=only, you cannot recursively push in its superproject because there is a check that submodules have been pushed, and with this setting, that submodule is not pushed (since only nested submodules are pushed).

In addition, there is the usage of the word "recursively" when describing "--recurse-submodules=only"...

If only is used all submodules will be recursively pushed while the superproject is left unpushed.

...even though this is not true with the default configuration. (Having said that, there is no "recursively" with --recurse-submodules=on-demand, so maybe it is the non-recursive meaning that is intended.)

So all this led me to think that it's best if only the top-level configuration is used, but I'm open to other ideas.

Quoted 5 lines

Not having thought about this a lot, the behavior I might expect is something along the lines of recursively pushing throughout the submodule tree, stopping the recursion as soon as we get to a nested submodule which says "don't push any of my children".

Quoted 8 lines

On the other hand, I could sympathize with a compelling argument that the superproject alone should be in charge of determining what gets pushed.

Though TBH, it seems like the former is more convincing. If I depend on an external repository through a submodule, and that repository itself has submodules, it would be nice to configure (once) that I don't want to even try and push any of that repository's children.

I just tried this and the behavior is reasonable except possibly for when push.recurseSubmodules=only is configured in a top-level submodule. Let's see if other people have something to say. For me, this would also be fine since we can just make sure that we don't configure "only" in top-level submodules that have their own nested submodules.

#3 lore raw
Quoted 14 lines · Jonathan Tan
Quoted 5 lines

Not having thought about this a lot, the behavior I might expect is something along the lines of recursively pushing throughout the submodule tree, stopping the recursion as soon as we get to a nested submodule which says "don't push any of my children".

Quoted 8 lines

On the other hand, I could sympathize with a compelling argument that the superproject alone should be in charge of determining what gets pushed.

Though TBH, it seems like the former is more convincing. If I depend on an external repository through a submodule, and that repository itself has submodules, it would be nice to configure (once) that I don't want to even try and push any of that repository's children.

Quoted 5 lines

I just tried this and the behavior is reasonable except possibly for when push.recurseSubmodules=only is configured in a top-level submodule. Let's see if other people have something to say. For me, this would also be fine since we can just make sure that we don't configure "only" in top-level submodules that have their own nested submodules.

For this patch, I think what Jonathan has proposed is preferable because that's close to what "git fetch" [1] does, i.e. when a superproject has parsed a setting for "recurse into submodules" (from either the CLI or config), it passes that value to its submodules via "--recurse-submodules", overriding the submodule's config.

In the longer term though, I think neither "git fetch" nor "git push" (as of this patch) gets it right. I think it should be closer to:

- If the user has passed a "--recurse-submodules" flag via the CLI, respect that in the superproject and all submodules regardless of nesting. (Make sure not to conflate config values with the CLI option in the way "git fetch" does today.)
- Otherwise, each submodule should respect their own config setting if it is set.
- Otherwise, each submodule should respect their superproject's config setting if it is set.

[1] "git fetch" is somewhat more complicated than this, since it also reads values from .gitmodules and passes a "default" value, neither of which is relevant here I think. See this ML thread for some previous discussion.
https://lore.kernel.org/git/[email protected]/

#4 lore raw

PATCH v2 1/1 Doc: document push.recurseSubmodules=only

In reply to Jonathan Tan

Git learned pushing submodules without pushing the superproject by the user specifying --recurse-submodules=only through 6c656c3fe4 ("submodules: add RECURSE_SUBMODULES_ONLY value", 2016-12-20) and 225e8bf778 ("push: add option to push only submodules", 2016-12-20). For users who use this feature regularly, it is desirable to have an equivalent configuration.

It turns out that such a configuration (push.recurseSubmodules=only) is already supported, even though it is neither documented nor mentioned in the commit messages, due to the way the --recurse-submodules=only feature was implemented (a function used to parse --recurse-submodules was updated to support "only", but that same function is used to parse push.recurseSubmodules too). What is left is to document it and test it, which is what this commit does.

There is a possible point of confusion when recursing into a submodule that itself has the push.recurseSubmodules=only configuration, because if a repository has only its submodules pushed and not itself, its superproject can never be pushed. Therefore, treat such configurations as being "on-demand", and print a warning message.

---
Thanks once again, Taylor and Glen for your comments. To try to summarize:

- For me, the most important thing is to explicitly support (with documentation) the push.recurseSubmodules=only configuration.
- Between the submodule being able to decide for itself whether recursion continues, and the superproject deciding everything, Taylor thinks the former is more convincing.
- The former is also the status quo.
- Glen makes a further point that either scheme (the status quo and the behavior in v1) would not be the ideal behavior, but that a CLI argument overrides all config, and in the absence of a CLI argument, a submodule should be able to decide for itself whether recursion should continue (except when there is no config present, in which case it should defer to the superproject).

If we were to implement v1 and then the ideal behavior later, we would need to revert some of the v1-introduced behavior: if there is configuration in both the superproject and a submodule, the status quo is that the submodule's configuration takes precedence, v1 has the superproject's configuration taking precedence, and with ideal behavior, the submodule's configuration takes precedence.

So it makes sense to stick to the status quo for this patch. It is possible to support push.recurseSubmodules=only with all existing behavior preserved (in fact, push.recurseSubmodules=only is already supported, just undocumented) so I have decided to go with that approach.

---
 Documentation/config/push.txt  | 14 ++--------
 Documentation/git-push.txt     |  6 +++-
 builtin/push.c                 | 12 ++++++--
 submodule.c                    |  6 ++++
 t/t5531-deep-submodule-push.sh | 50 ++++++++++++++++++++++++++++++++++
 5 files changed, 73 insertions(+), 15 deletions(-)
Documentation/config/push.txt +2 -12
index 7386fea225..43338b65e8 100644
@@ -110,18 +110,8 @@ This will result in only b (a and c are cleared).
 ----
 
 push.recurseSubmodules::
-	Make sure all submodule commits used by the revisions to be pushed
-	are available on a remote-tracking branch. If the value is 'check'
-	then Git will verify that all submodule commits that changed in the
-	revisions to be pushed are available on at least one remote of the
-	submodule. If any commits are missing, the push will be aborted and
-	exit with non-zero status. If the value is 'on-demand' then all
-	submodules that changed in the revisions to be pushed will be
-	pushed. If on-demand was not able to push all necessary revisions
-	it will also be aborted and exit with non-zero status. If the value
-	is 'no' then default behavior of ignoring submodules when pushing
-	is retained. You may override this configuration at time of push by
-	specifying '--recurse-submodules=check|on-demand|no'.
+	May be "check", "on-demand", "only", or "no", with the same behavior
+	as that of "push --recurse-submodules".
 	If not set, 'no' is used by default, unless 'submodule.recurse' is
 	set (in which case a 'true' value means 'on-demand').
 
Documentation/git-push.txt +5 -1
index def7657ef9..5bb1d5aae2 100644
@@ -409,10 +409,14 @@ Specifying `--no-force-if-includes` disables this behavior.
 	all submodules that changed in the revisions to be pushed will be
 	pushed. If on-demand was not able to push all necessary revisions it will
 	also be aborted and exit with non-zero status. If 'only' is used all
-	submodules will be recursively pushed while the superproject is left
+	submodules will be pushed while the superproject is left
 	unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
 	to override the push.recurseSubmodules configuration variable when no
 	submodule recursion is required.
++
+When using 'on-demand' or 'only', if a submodule has a
+"push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration,
+further recursion will occur. In this case, "only" is treated as "on-demand".
 
 --[no-]verify::
 	Toggle the pre-push hook (see linkgit:githooks[5]).  The
builtin/push.c +10 -2
index f0329c62a2..60ac8017e5 100644
@@ -466,8 +466,16 @@ static int option_parse_recurse_submodules(const struct option *opt,
 
 	if (unset)
 		*recurse_submodules = RECURSE_SUBMODULES_OFF;
-	else
-		*recurse_submodules = parse_push_recurse_submodules_arg(opt->long_name, arg);
+	else {
+		if (!strcmp(arg, "only-is-on-demand")) {
+			if (*recurse_submodules == RECURSE_SUBMODULES_ONLY) {
+				warning(_("recursing into submodule with push.recurseSubmodules=only; using on-demand instead"));
+				*recurse_submodules = RECURSE_SUBMODULES_ON_DEMAND;
+			}
+		} else {
+			*recurse_submodules = parse_push_recurse_submodules_arg(opt->long_name, arg);
+		}
+	}
 
 	return 0;
 }
submodule.c +6 -0
index bf7a2c7918..5cd21252d8 100644
@@ -1130,6 +1130,12 @@ static int push_submodule(const char *path,
 	if (for_each_remote_ref_submodule(path, has_remote, NULL) > 0) {
 		struct child_process cp = CHILD_PROCESS_INIT;
 		strvec_push(&cp.args, "push");
+		/*
+		 * When recursing into a submodule, treat any "only" configurations as "on-
+		 * demand", since "only" would not work (we need all submodules to be pushed
+		 * in order to be able to push the superproject).
+		 */
+		strvec_push(&cp.args, "--recurse-submodules=only-is-on-demand");
 		if (dry_run)
 			strvec_push(&cp.args, "--dry-run");
 
t/t5531-deep-submodule-push.sh +50 -0

56 lines not on this page · raw message

Signature · 1 line
2.38.1.493.g58b659f92b-goog
#5 lore raw

Re: [PATCH v2] Doc: document push.recurseSubmodules=only

Quoted 6 lines · Jonathan Tan
 Documentation/config/push.txt  | 14 ++--------
 Documentation/git-push.txt     |  6 +++-
 builtin/push.c                 | 12 ++++++--
 submodule.c                    |  6 ++++
 t/t5531-deep-submodule-push.sh | 50 ++++++++++++++++++++++++++++++++++
 5 files changed, 73 insertions(+), 15 deletions(-)

Seems reasonable to me. Glen?

Thanks,
Taylor

#6 lore raw

Re: [PATCH v2] Doc: document push.recurseSubmodules=only

In reply to Jonathan Tan
Quoted 4 lines · Jonathan Tan

- For me, the most important thing is to explicitly support (with documentation) the push.recurseSubmodules=only configuration.
- Between the submodule being able to decide for itself whether recursion continues, and the superproject deciding everything, Taylor

Quoted 8 lines

thinks the former is more convincing.
- The former is also the status quo.
- Glen makes a further point that either scheme (the status quo and the behavior in v1) would not be the ideal behavior, but that a CLI argument overrides all config, and in the absence of a CLI argument, a submodule should be able to decide for itself whether recursion should continue (except when there is no config present, in which case it should defer to the superproject).

Ok. I find the status quo argument convincing, so I'm okay with the approach in this patch.

That said.. I find the status quo very surprising and unergonomic. As demonstrated in a test below, if a submodule has push.recurseSubmodules unset, recursion doesn't occur. At the very least, I would have expected the submodule to respect the superproject's config since that's still a statement of intent.

I expect that we will have to change this behavior at some point, and hopefully my "ideal" behavior makes sense to users.

Quoted 35 lines
Documentation/config/push.txt +2 -12
index 7386fea225..43338b65e8 100644
@@ -110,18 +110,8 @@ This will result in only b (a and c are cleared).
 ----
 
 push.recurseSubmodules::
-	Make sure all submodule commits used by the revisions to be pushed
-	are available on a remote-tracking branch. If the value is 'check'
-	then Git will verify that all submodule commits that changed in the
-	revisions to be pushed are available on at least one remote of the
-	submodule. If any commits are missing, the push will be aborted and
-	exit with non-zero status. If the value is 'on-demand' then all
-	submodules that changed in the revisions to be pushed will be
-	pushed. If on-demand was not able to push all necessary revisions
-	it will also be aborted and exit with non-zero status. If the value
-	is 'no' then default behavior of ignoring submodules when pushing
-	is retained. You may override this configuration at time of push by
-	specifying '--recurse-submodules=check|on-demand|no'.
+	May be "check", "on-demand", "only", or "no", with the same behavior
+	as that of "push --recurse-submodules".
 	If not set, 'no' is used by default, unless 'submodule.recurse' is
 	set (in which case a 'true' value means 'on-demand').
 
Documentation/git-push.txt +1 -1
index def7657ef9..5bb1d5aae2 100644
@@ -409,10 +409,14 @@ Specifying `--no-force-if-includes` disables this behavior.
 	all submodules that changed in the revisions to be pushed will be
 	pushed. If on-demand was not able to push all necessary revisions it will
 	also be aborted and exit with non-zero status. If 'only' is used all
-	submodules will be recursively pushed while the superproject is left
+	submodules will be pushed while the superproject is left

Documentation/git-push.txt Specifying `--no-force-if-includes` disables this behavior. · line 422

Quoted 10 lines
Documentation/git-push.txt +4 -0
 	unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
 	to override the push.recurseSubmodules configuration variable when no
 	submodule recursion is required.
++
+When using 'on-demand' or 'only', if a submodule has a
+"push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration,
+further recursion will occur. In this case, "only" is treated as "on-demand".
 
 --[no-]verify::
 	Toggle the pre-push hook (see linkgit:githooks[5]).  The

Everything up to here looks good.

Quoted 29 lines
builtin/push.c +10 -2
index f0329c62a2..60ac8017e5 100644
@@ -466,8 +466,16 @@ static int option_parse_recurse_submodules(const struct option *opt,
 
 	if (unset)
 		*recurse_submodules = RECURSE_SUBMODULES_OFF;
-	else
-		*recurse_submodules = parse_push_recurse_submodules_arg(opt->long_name, arg);
+	else {
+		if (!strcmp(arg, "only-is-on-demand")) {
+			if (*recurse_submodules == RECURSE_SUBMODULES_ONLY) {
+				warning(_("recursing into submodule with push.recurseSubmodules=only; using on-demand instead"));
+				*recurse_submodules = RECURSE_SUBMODULES_ON_DEMAND;
+			}
+		} else {
+			*recurse_submodules = parse_push_recurse_submodules_arg(opt->long_name, arg);
+		}
+	}
 
 	return 0;
 }
submodule.c +0 -0
index bf7a2c7918..5cd21252d8 100644
@@ -1130,6 +1130,12 @@ static int push_submodule(const char *path,
 	if (for_each_remote_ref_submodule(path, has_remote, NULL) > 0) {

submodule.c static int push_submodule(const char *path, · line 1140

Quoted 10 lines
submodule.c +6 -0
 		struct child_process cp = CHILD_PROCESS_INIT;
 		strvec_push(&cp.args, "push");
+		/*
+		 * When recursing into a submodule, treat any "only" configurations as "on-
+		 * demand", since "only" would not work (we need all submodules to be pushed
+		 * in order to be able to push the superproject).
+		 */
+		strvec_push(&cp.args, "--recurse-submodules=only-is-on-demand");
 		if (dry_run)
 			strvec_push(&cp.args, "--dry-run");

When we pass this magic, undocumented value, "git push" will warn about about "only" and override it with "on-demand". We always pass it when we recurse into submodules, and we assume that no user will pass it, thus we get the warning iff we are recursing into submodules.

In that case, it sounds like "--recurse-submodules=only-is-on-demand" is a synonym for "this is a submodule that is being recursed into". In that case, wouldn't it be more self-documenting to have a hidden CLI flag that expresses exactly that ? e.g. we could add a PARSE_OPT_HIDDEN flag called "--is-recursing" and check that boolean value. This seems clearer to me at least.

Quoted 34 lines
t/t5531-deep-submodule-push.sh +25 -0
index 3f58b515ce..302e4cbdba 100755
@@ -512,6 +512,56 @@ test_expect_success 'push only unpushed submodules recursively' '
 	test_cmp expected_pub actual_pub
 '
 
+setup_subsub () {
+	git init upstream &&
+	git init upstream/sub &&
+	git init upstream/sub/deepsub &&
+	test_commit -C upstream/sub/deepsub innermost &&
+	git -C upstream/sub submodule add ./deepsub deepsub &&
+	git -C upstream/sub commit -m middle &&
+	git -C upstream submodule add ./sub sub &&
+	git -C upstream commit -m outermost &&
+
+	git -c protocol.file.allow=always clone --recurse-submodules upstream downstream &&
+	git -C downstream/sub/deepsub checkout -b downstream-branch &&
+	git -C downstream/sub checkout -b downstream-branch &&
+	git -C downstream checkout -b downstream-branch
+}
+
+new_downstream_commits () {
+	test_commit -C downstream/sub/deepsub new-innermost &&
+	git -C downstream/sub add deepsub &&
+	git -C downstream/sub commit -m new-middle &&
+	git -C downstream add sub &&
+	git -C downstream commit -m new-outermost
+}
+
+test_expect_success 'push with push.recurseSubmodules=only on superproject' '

t/t5531-deep-submodule-push.sh test_expect_success 'push only unpushed submodules recursively' ' · line 549

Quoted 10 lines
t/t5531-deep-submodule-push.sh +10 -0
+	test_when_finished rm -rf upstream downstream &&
+	setup_subsub &&
+	new_downstream_commits &&
+	git -C downstream config push.recurseSubmodules only &&
+	git -C downstream push origin downstream-branch &&
+
+	test_must_fail git -C upstream rev-parse refs/heads/downstream-branch &&
+	git -C upstream/sub rev-parse refs/heads/downstream-branch &&
+	test_must_fail git -C upstream/sub/deepsub rev-parse refs/heads/downstream-branch
+'

This test demonstrates the behavior I find surprising.

Quoted 8 lines
t/t5531-deep-submodule-push.sh +8 -0
+
+test_expect_success 'push with push.recurseSubmodules=only on superproject and top-level submodule' '
+	test_when_finished rm -rf upstream downstream &&
+	setup_subsub &&
+	new_downstream_commits &&
+	git -C downstream config push.recurseSubmodules only &&
+	git -C downstream/sub config push.recurseSubmodules only &&
+	git -C downstream push origin downstream-branch 2> err &&

t/t5531-deep-submodule-push.sh test_expect_success 'push only unpushed submodules recursively' ' · line 567

Quoted 10 lines
t/t5531-deep-submodule-push.sh +7 -0
+
+	test_must_fail git -C upstream rev-parse refs/heads/downstream-branch &&
+	git -C upstream/sub rev-parse refs/heads/downstream-branch &&
+	git -C upstream/sub/deepsub rev-parse refs/heads/downstream-branch &&
+	grep "recursing into submodule with push.recurseSubmodules=only; using on-demand instead" err
+'
+
 test_expect_success 'push propagating the remotes name to a submodule' '
 	git -C work remote add origin ../pub.git &&
 	git -C work remote add pub ../pub.git &&

The tests look good, and are quite readable.

Quoted 2 lines
Signature · 1 line
2.38.1.493.g58b659f92b-goog
#7 lore raw

Re: [PATCH v2] Doc: document push.recurseSubmodules=only

First of all, thanks for taking a look at this.

Quoted 8 lines · Glen Choo

That said.. I find the status quo very surprising and unergonomic. As demonstrated in a test below, if a submodule has push.recurseSubmodules unset, recursion doesn't occur. At the very least, I would have expected the submodule to respect the superproject's config since that's still a statement of intent.

I expect that we will have to change this behavior at some point, and hopefully my "ideal" behavior makes sense to users.

Well, your "ideal" behavior makes sense to me :-)

Quoted 11 lines

When we pass this magic, undocumented value, "git push" will warn about about "only" and override it with "on-demand". We always pass it when we recurse into submodules, and we assume that no user will pass it, thus we get the warning iff we are recursing into submodules.

In that case, it sounds like "--recurse-submodules=only-is-on-demand" is a synonym for "this is a submodule that is being recursed into". In that case, wouldn't it be more self-documenting to have a hidden CLI flag that expresses exactly that ? e.g. we could add a PARSE_OPT_HIDDEN flag called "--is-recursing" and check that boolean value. This seems clearer to me at least.

Hmm...--recurse-submodules=only-is-on-demand is hidden too, right? One advantage of doing this instead of a separate arg is that neither the caller nor "git push" needs to think about what happens if both --recurse- submodules=something and --is-recursing are both specified.

#8 lore raw

Re: [PATCH v2] Doc: document push.recurseSubmodules=only

Quoted 5 lines · Jonathan Tan
Quoted 5 lines

When we pass this magic, undocumented value, "git push" will warn about about "only" and override it with "on-demand". We always pass it when we recurse into submodules, and we assume that no user will pass it, thus we get the warning iff we are recursing into submodules.

Quoted 8 lines
Quoted 6 lines

In that case, it sounds like "--recurse-submodules=only-is-on-demand" is a synonym for "this is a submodule that is being recursed into". In that case, wouldn't it be more self-documenting to have a hidden CLI flag that expresses exactly that ? e.g. we could add a PARSE_OPT_HIDDEN flag called "--is-recursing" and check that boolean value. This seems clearer to me at least.

Hmm...--recurse-submodules=only-is-on-demand is hidden too, right?

I suppose so, but as a matter of personal taste, when encountering a hidden CLI option, I'd prefer to see the option's documentation when I grep:

OPT_HIDDEN_BOOL(0, "is-recursing", &is_recursing, "internal only,
override recurseSubmodules = only")

than:

  if (!strcmp(arg, "only-is-on-demand")) {
    /* etc */
  }
Quoted 4 lines

One
advantage of doing this instead of a separate arg is that neither the caller nor "git push" needs to think about what happens if both --recurse- submodules=something and --is-recursing are both specified.

That's true, and I suppose it prevents the temptation to reuse --is-recursing for things it wasn't meant for. But in that case, couldn't we say the same thing if we renamed "--is-recursing" to "--recurse-only-is-on-demand"?

At any rate, do treat this as just a suggestion. I won't block this if both you and Taylor find this clear enough :)

#9 lore raw

Re: [PATCH v2] Doc: document push.recurseSubmodules=only

Quoted 2 lines · Glen Choo

At any rate, do treat this as just a suggestion. I won't block this if both you and Taylor find this clear enough :)

I admit that I do not care too much either way ;-).

Thanks,
Taylor