[PATCH] repo: show subcommand-specific help text

[PATCH] repo: show subcommand-specific help text

[Mahi Kassa]

Use subcommand-specific usage arrays for "git repo info" and "git repo structure" so that each command shows only its own synopsis in help output.

Keep the top-level "git repo -h" output unchanged, and add tests to cover the subcommand help behavior.
---
 builtin/repo.c            | 15 +++++++++++++--
 t/t1900-repo-info.sh      |  6 +++++-
 t/t1901-repo-structure.sh |  5 +++++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/builtin/repo.c b/builtin/repo.c
index 55f9b9095c..5ccc5c401a 100644
--- a/builtin/repo.c
+++ b/builtin/repo.c
@@ -27,6 +27,17 @@ static const char *const repo_usage[] = {
 	NULL
 };
 
+static const char *const repo_info_usage[] = {
+	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
+	"git repo info --keys [--format=(lines|nul) | -z]",
+	NULL
+};
+
+static const char *const repo_structure_usage[] = {
+	"git repo structure [--format=(table|lines|nul) | -z]",
+	NULL
+};
+
 typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
 
 enum output_format {
@@ -214,7 +225,7 @@ static int cmd_repo_info(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_info_usage, 0);
 
 	if (show_keys && (all_keys || argc))
 		die(_("--keys cannot be used with a <key> or --all"));
@@ -879,7 +890,7 @@ static int cmd_repo_structure(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_structure_usage, 0);
 	if (argc)
 		usage(_("too many arguments"));
 
diff --git a/t/t1900-repo-info.sh b/t/t1900-repo-info.sh
index a9eb07abe8..e0e79ff167 100755
--- a/t/t1900-repo-info.sh
+++ b/t/t1900-repo-info.sh
@@ -148,5 +148,9 @@ test_expect_success 'git repo info --keys uses lines as its default output forma
 	git repo info --keys >actual &&
 	test_cmp expect actual
 '
-
+test_expect_success 'git repo info -h shows only repo info usage' '
+	test_must_fail git repo info -h >actual &&
+	test_grep "git repo info" actual &&
+	test_grep ! "git repo structure" actual
+'
 test_done
diff --git a/t/t1901-repo-structure.sh b/t/t1901-repo-structure.sh
index 98921ce1cb..0f7ec4da10 100755
--- a/t/t1901-repo-structure.sh
+++ b/t/t1901-repo-structure.sh
@@ -224,4 +224,9 @@ test_expect_success 'progress meter option' '
 	)
 '
 
+test_expect_success 'git repo structure -h shows only repo structure usage' '
+	test_must_fail git repo structure -h >actual &&
+	test_grep "git repo structure" actual &&
+	test_grep ! "git repo info" actual
+'
 test_done
-- 
2.34.1

Re: [PATCH] repo: show subcommand-specific help text

[Derrick Stolee]

On 3/23/2026 11:29 AM, Mahi Kassa wrote:
> Use subcommand-specific usage arrays for "git repo info" and "git repo structure" so that each command shows only its own synopsis in help output.
> 
> Keep the top-level "git repo -h" output unchanged, and add tests to cover the subcommand help behavior.

Please wrap your lines in the commit message.

> +static const char *const repo_info_usage[] = {
> +	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
> +	"git repo info --keys [--format=(lines|nul) | -z]",
> +	NULL
> +};
> +
> +static const char *const repo_structure_usage[] = {
> +	"git repo structure [--format=(table|lines|nul) | -z]",
> +	NULL
> +};
> +

I did a visual comparison to the synopsis in Documentation/git-repo.adoc
[1] and these look the same. (I suspect that they also exist in the
repo_usage struct outside of the patch context, so they were easy to
copy from there.)

[1] https://github.com/git/git/blob/6e8d538aab8fe4dd07ba9fb87b5c7edcfa5706ad/Documentation/git-repo.adoc?plain=1#L10-L13

> -	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
> +	argc = parse_options(argc, argv, prefix, options, repo_info_usage, 0);

> -	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
> +	argc = parse_options(argc, argv, prefix, options, repo_structure_usage, 0);

Nice and easy here.

> --- a/t/t1900-repo-info.sh
> +++ b/t/t1900-repo-info.sh
> @@ -148,5 +148,9 @@ test_expect_success 'git repo info --keys uses lines as its default output forma
>  	git repo info --keys >actual &&
>  	test_cmp expect actual
>  '
> -

Don't erase the whitespace between tests.

> +test_expect_success 'git repo info -h shows only repo info usage' '
> +	test_must_fail git repo info -h >actual &&
> +	test_grep "git repo info" actual &&
> +	test_grep ! "git repo structure" actual
> +'
>  test_done

and keep whitespace between the end of the test and 'test_done'.

> diff --git a/t/t1901-repo-structure.sh b/t/t1901-repo-structure.sh
> index 98921ce1cb..0f7ec4da10 100755
> --- a/t/t1901-repo-structure.sh
> +++ b/t/t1901-repo-structure.sh
> @@ -224,4 +224,9 @@ test_expect_success 'progress meter option' '
>  	)
>  '
>  
> +test_expect_success 'git repo structure -h shows only repo structure usage' '

You preserved the whitespace above this test. good.

> +	test_must_fail git repo structure -h >actual &&
> +	test_grep "git repo structure" actual &&
> +	test_grep ! "git repo info" actual
> +'
>  test_done

But here we need some before 'test_done'.

Thanks,
-Stolee

Re: [PATCH] repo: show subcommand-specific help text

[Patrick Steinhardt]

On Mon, Mar 23, 2026 at 04:29:37PM +0100, Mahi Kassa wrote:
> diff --git a/builtin/repo.c b/builtin/repo.c
> index 55f9b9095c..5ccc5c401a 100644
> --- a/builtin/repo.c
> +++ b/builtin/repo.c
> @@ -27,6 +27,17 @@ static const char *const repo_usage[] = {
>  	NULL
>  };
>  
> +static const char *const repo_info_usage[] = {
> +	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
> +	"git repo info --keys [--format=(lines|nul) | -z]",
> +	NULL
> +};
> +
> +static const char *const repo_structure_usage[] = {
> +	"git repo structure [--format=(table|lines|nul) | -z]",
> +	NULL
> +};
> +
>  typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
>  
>  enum output_format {

These are basically the split-out parts of `repo_usage`, which makes
sense. But it also means that it will be quite easy for those two usages
to diverge over time. Would it make sense to maybe split the individual
usage strings into macros that we can reuse? Something like the below
(partial) patch.

Thanks!

Patrick

diff --git a/builtin/repo.c b/builtin/repo.c
index 55f9b9095c..200c5901a7 100644
--- a/builtin/repo.c
+++ b/builtin/repo.c
@@ -20,11 +20,22 @@
 #include "tree-walk.h"
 #include "utf8.h"
 
+#define REPO_INFO_USAGE \
+	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]", \
+	"git repo info --keys [--format=(lines|nul) | -z]"
+
+#define REPO_STRUCTURE_USAGE \
+	"git repo structure [--format=(table|lines|nul) | -z]"
+
 static const char *const repo_usage[] = {
-	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
-	"git repo info --keys [--format=(lines|nul) | -z]",
-	"git repo structure [--format=(table|lines|nul) | -z]",
-	NULL
+	REPO_INFO_USAGE,
+	REPO_STRUCTURE_USAGE,
+	NULL,
+};
+
+static const char *const repo_info_usage[] = {
+	REPO_INFO_USAGE,
+	NULL,
 };
 
 typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
@@ -214,7 +225,7 @@ static int cmd_repo_info(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_info_usage, 0);
 
 	if (show_keys && (all_keys || argc))
 		die(_("--keys cannot be used with a <key> or --all"));

[PATCH v2] repo: show subcommand-specific help text

[Mahi Kassa]

Use subcommand-specific usage arrays for "git repo info" and
"git repo structure" so that each command shows only its own
synopsis in help output.

Factor the shared usage strings into macros to avoid
duplicating the same synopsis text in multiple arrays.

Add tests to cover the subcommand help behavior.

---
v2:
- wrap commit message lines
- factor shared usage strings into macros to avoid duplication
- restore blank lines between tests and before test_done

 builtin/repo.c            | 15 +++++++++++++--
 t/t1900-repo-info.sh      |  6 +++++-
 t/t1901-repo-structure.sh |  5 +++++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/builtin/repo.c b/builtin/repo.c
index 55f9b9095c..5ccc5c401a 100644
--- a/builtin/repo.c
+++ b/builtin/repo.c
@@ -27,6 +27,17 @@ static const char *const repo_usage[] = {
 	NULL
 };
 
+static const char *const repo_info_usage[] = {
+	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
+	"git repo info --keys [--format=(lines|nul) | -z]",
+	NULL
+};
+
+static const char *const repo_structure_usage[] = {
+	"git repo structure [--format=(table|lines|nul) | -z]",
+	NULL
+};
+
 typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
 
 enum output_format {
@@ -214,7 +225,7 @@ static int cmd_repo_info(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_info_usage, 0);
 
 	if (show_keys && (all_keys || argc))
 		die(_("--keys cannot be used with a <key> or --all"));
@@ -879,7 +890,7 @@ static int cmd_repo_structure(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_structure_usage, 0);
 	if (argc)
 		usage(_("too many arguments"));
 
diff --git a/t/t1900-repo-info.sh b/t/t1900-repo-info.sh
index a9eb07abe8..e0e79ff167 100755
--- a/t/t1900-repo-info.sh
+++ b/t/t1900-repo-info.sh
@@ -148,5 +148,9 @@ test_expect_success 'git repo info --keys uses lines as its default output forma
 	git repo info --keys >actual &&
 	test_cmp expect actual
 '
-
+test_expect_success 'git repo info -h shows only repo info usage' '
+	test_must_fail git repo info -h >actual &&
+	test_grep "git repo info" actual &&
+	test_grep ! "git repo structure" actual
+'
 test_done
diff --git a/t/t1901-repo-structure.sh b/t/t1901-repo-structure.sh
index 98921ce1cb..0f7ec4da10 100755
--- a/t/t1901-repo-structure.sh
+++ b/t/t1901-repo-structure.sh
@@ -224,4 +224,9 @@ test_expect_success 'progress meter option' '
 	)
 '
 
+test_expect_success 'git repo structure -h shows only repo structure usage' '
+	test_must_fail git repo structure -h >actual &&
+	test_grep "git repo structure" actual &&
+	test_grep ! "git repo info" actual
+'
 test_done
-- 
2.34.1

Re: [PATCH v2] repo: show subcommand-specific help text

[Patrick Steinhardt]

On Tue, Mar 24, 2026 at 01:21:11PM +0100, Mahi Kassa wrote:
> Use subcommand-specific usage arrays for "git repo info" and
> "git repo structure" so that each command shows only its own
> synopsis in help output.
> 
> Factor the shared usage strings into macros to avoid
> duplicating the same synopsis text in multiple arrays.
> 
> Add tests to cover the subcommand help behavior.
> 
> ---
> v2:
> - wrap commit message lines
> - factor shared usage strings into macros to avoid duplication
> - restore blank lines between tests and before test_done

Something most have gone wrong, as I cannot see any of the macros. We
still duplicate the usage strings.

Patrick

> diff --git a/builtin/repo.c b/builtin/repo.c
> index 55f9b9095c..5ccc5c401a 100644
> --- a/builtin/repo.c
> +++ b/builtin/repo.c
> @@ -27,6 +27,17 @@ static const char *const repo_usage[] = {
>  	NULL
>  };
>  
> +static const char *const repo_info_usage[] = {
> +	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
> +	"git repo info --keys [--format=(lines|nul) | -z]",
> +	NULL
> +};
> +
> +static const char *const repo_structure_usage[] = {
> +	"git repo structure [--format=(table|lines|nul) | -z]",
> +	NULL
> +};
> +
>  typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
>  
>  enum output_format {

Re: [PATCH v2] repo: show subcommand-specific help text

[Derrick Stolee]

On 3/24/2026 8:21 AM, Mahi Kassa wrote:
> Use subcommand-specific usage arrays for "git repo info" and
> "git repo structure" so that each command shows only its own
> synopsis in help output.
> 
> Factor the shared usage strings into macros to avoid
> duplicating the same synopsis text in multiple arrays.
> 
> Add tests to cover the subcommand help behavior.

Missing sign-off.

> @@ -148,5 +148,9 @@ test_expect_success 'git repo info --keys uses lines as its default output forma
>  	git repo info --keys >actual &&
>  	test_cmp expect actual
>  '
> -
> +test_expect_success 'git repo info -h shows only repo info usage' '
> +	test_must_fail git repo info -h >actual &&
> +	test_grep "git repo info" actual &&
> +	test_grep ! "git repo structure" actual
> +'
>  test_done
> diff --git a/t/t1901-repo-structure.sh b/t/t1901-repo-structure.sh
> index 98921ce1cb..0f7ec4da10 100755
> --- a/t/t1901-repo-structure.sh
> +++ b/t/t1901-repo-structure.sh
> @@ -224,4 +224,9 @@ test_expect_success 'progress meter option' '
>  	)
>  '
>  
> +test_expect_success 'git repo structure -h shows only repo structure usage' '
> +	test_must_fail git repo structure -h >actual &&
> +	test_grep "git repo structure" actual &&
> +	test_grep ! "git repo info" actual
> +'
>  test_done

Whitespace issues persist in these test files.

Thanks,
-Stolee

[PATCH v3] repo: show subcommand-specific help text

[Mahi Kassa]

Use subcommand-specific usage arrays for "git repo info" and
"git repo structure" so that each command shows only its own
synopsis in help output.

Factor the shared usage strings into macros to avoid
duplicating the same synopsis text in multiple arrays.

Add tests to cover the subcommand help behavior.

The previous reroll mistakenly omitted the requested code
changes; this version includes them.

---
v3:
- include the requested code changes that were missing from v2
- factor shared usage strings into macros to avoid duplication
- restore blank lines between tests and before test_done

 builtin/repo.c            | 28 ++++++++++++++++++++++------
 t/t1900-repo-info.sh      |  6 ++++++
 t/t1901-repo-structure.sh |  6 ++++++
 3 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/builtin/repo.c b/builtin/repo.c
index 55f9b9095c..71a5c1c29c 100644
--- a/builtin/repo.c
+++ b/builtin/repo.c
@@ -20,11 +20,27 @@
 #include "tree-walk.h"
 #include "utf8.h"
 
+#define REPO_INFO_USAGE \
+	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]", \
+	"git repo info --keys [--format=(lines|nul) | -z]"
+
+#define REPO_STRUCTURE_USAGE \
+	"git repo structure [--format=(table|lines|nul) | -z]"
+
 static const char *const repo_usage[] = {
-	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
-	"git repo info --keys [--format=(lines|nul) | -z]",
-	"git repo structure [--format=(table|lines|nul) | -z]",
-	NULL
+	REPO_INFO_USAGE,
+	REPO_STRUCTURE_USAGE,
+	NULL,
+};
+
+static const char *const repo_info_usage[] = {
+	REPO_INFO_USAGE,
+	NULL,
+};
+
+static const char *const repo_structure_usage[] = {
+	REPO_STRUCTURE_USAGE,
+	NULL,
 };
 
 typedef int get_value_fn(struct repository *repo, struct strbuf *buf);
@@ -214,7 +230,7 @@ static int cmd_repo_info(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_info_usage, 0);
 
 	if (show_keys && (all_keys || argc))
 		die(_("--keys cannot be used with a <key> or --all"));
@@ -879,7 +895,7 @@ static int cmd_repo_structure(int argc, const char **argv, const char *prefix,
 		OPT_END()
 	};
 
-	argc = parse_options(argc, argv, prefix, options, repo_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, repo_structure_usage, 0);
 	if (argc)
 		usage(_("too many arguments"));
 
diff --git a/t/t1900-repo-info.sh b/t/t1900-repo-info.sh
index a9eb07abe8..39bb77dda0 100755
--- a/t/t1900-repo-info.sh
+++ b/t/t1900-repo-info.sh
@@ -149,4 +149,10 @@ test_expect_success 'git repo info --keys uses lines as its default output forma
 	test_cmp expect actual
 '
 
+test_expect_success 'git repo info -h shows only repo info usage' '
+	test_must_fail git repo info -h >actual &&
+	test_grep "git repo info" actual &&
+	test_grep ! "git repo structure" actual
+'
+
 test_done
diff --git a/t/t1901-repo-structure.sh b/t/t1901-repo-structure.sh
index 98921ce1cb..10050abd70 100755
--- a/t/t1901-repo-structure.sh
+++ b/t/t1901-repo-structure.sh
@@ -224,4 +224,10 @@ test_expect_success 'progress meter option' '
 	)
 '
 
+test_expect_success 'git repo structure -h shows only repo structure usage' '
+	test_must_fail git repo structure -h >actual &&
+	test_grep "git repo structure" actual &&
+	test_grep ! "git repo info" actual
+'
+
 test_done
-- 
2.34.1

Re: [PATCH v3] repo: show subcommand-specific help text

[Derrick Stolee]

On 3/24/2026 2:48 PM, Mahi Kassa wrote:
> Use subcommand-specific usage arrays for "git repo info" and
> "git repo structure" so that each command shows only its own
> synopsis in help output.
> 
> Factor the shared usage strings into macros to avoid
> duplicating the same synopsis text in multiple arrays.
> 
> Add tests to cover the subcommand help behavior.

You need a sign-off in your commit message.
 
> The previous reroll mistakenly omitted the requested code
> changes; this version includes them.

This kind of information needs to be below the --- along with
your "V3" changes:
 
> ---
> v3:
> - include the requested code changes that were missing from v2
> - factor shared usage strings into macros to avoid duplication
> - restore blank lines between tests and before test_done

(here)

Outside of these issues with the message, the diff itself
looks good.

Thanks,
-Stolee

Re: [PATCH v3] repo: show subcommand-specific help text

[Patrick Steinhardt]

On Tue, Mar 24, 2026 at 07:48:43PM +0100, Mahi Kassa wrote:
> Use subcommand-specific usage arrays for "git repo info" and
> "git repo structure" so that each command shows only its own
> synopsis in help output.
> 
> Factor the shared usage strings into macros to avoid
> duplicating the same synopsis text in multiple arrays.
> 
> Add tests to cover the subcommand help behavior.
> 
> The previous reroll mistakenly omitted the requested code
> changes; this version includes them.
> 
> ---
> v3:
> - include the requested code changes that were missing from v2
> - factor shared usage strings into macros to avoid duplication
> - restore blank lines between tests and before test_done

By the way, it is highly recommended to respond to some of the review
mails directly, as it helps to create a dialog between submitter and
reviewer. Otherwise reviewers may feel as if they are talking to a code
emitting entity :)

It's not necessary to reply to every single mail, but going like "Oops,
yes, I indeed forgot to add the request code changes. Will fix in the
next version" can go a long way to make the interaction more social.

> diff --git a/builtin/repo.c b/builtin/repo.c
> index 55f9b9095c..71a5c1c29c 100644
> --- a/builtin/repo.c
> +++ b/builtin/repo.c
> @@ -20,11 +20,27 @@
>  #include "tree-walk.h"
>  #include "utf8.h"
>  
> +#define REPO_INFO_USAGE \
> +	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]", \
> +	"git repo info --keys [--format=(lines|nul) | -z]"
> +
> +#define REPO_STRUCTURE_USAGE \
> +	"git repo structure [--format=(table|lines|nul) | -z]"
> +
>  static const char *const repo_usage[] = {
> -	"git repo info [--format=(lines|nul) | -z] [--all | <key>...]",
> -	"git repo info --keys [--format=(lines|nul) | -z]",
> -	"git repo structure [--format=(table|lines|nul) | -z]",
> -	NULL
> +	REPO_INFO_USAGE,
> +	REPO_STRUCTURE_USAGE,
> +	NULL,
> +};
> +
> +static const char *const repo_info_usage[] = {
> +	REPO_INFO_USAGE,
> +	NULL,
> +};
> +
> +static const char *const repo_structure_usage[] = {
> +	REPO_STRUCTURE_USAGE,
> +	NULL,
>  };
>  
>  typedef int get_value_fn(struct repository *repo, struct strbuf *buf);

I think it would make sense to split this out into two commits: one
where you introduce the macros as a preparatory refactoring, and then
the next one where you start to differentiate the different usage
strings.

Otherwise this looks good to me now, thanks!

Patrick

Re: [PATCH v3] repo: show subcommand-specific help text

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> v3:
>> - include the requested code changes that were missing from v2
>> - factor shared usage strings into macros to avoid duplication
>> - restore blank lines between tests and before test_done
>
> By the way, it is highly recommended to respond to some of the review
> mails directly, as it helps to create a dialog between submitter and
> reviewer. Otherwise reviewers may feel as if they are talking to a code
> emitting entity :)
>
> It's not necessary to reply to every single mail, but going like "Oops,
> yes, I indeed forgot to add the request code changes. Will fix in the
> next version" can go a long way to make the interaction more social.

Hear! hear!  A new iteration without any introduction is harder to
accept without such a pre-warning to suggest what the author thought
after getting suggestions in earlier reviews.  Did they agree and
took the suggestion?  Did they disagree but took the suggestion
anyway, and if so why did they think the suggestion was not such a
good change?  Did they disagree and did not take the suggestion and
if so why?  They changed the code but not in the way suggested in
the review, but why the new way was thought to be better than both
the original and the reviewer input is unknown?