* [PATCH v3 01/36] CodingGuidelines: update and clarify command-line conventions
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:01 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 02/36] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
` (36 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Edit the section which explains how to create a good SYNOPSIS section
for clarity and accuracy, it was mostly introduced in
c455bd8950e (CodingGuidelines: Add a section on writing documentation,
2010-11-04):
* Change "extra" example to "file", which now naturally follows from
previous "<file>..." example (one or more) to "[<file>...]" (zero or
more).
* Explain how we prefer spacing around "[]()" tokens and "|"
alternatives, this is not a new policy, but just codifies what's
already the pattern in the most wide use in the documentation.
Having a space around " | " for flags, but not for flag values is
inconsistent, but this style guide codifies existing
patterns. Grepping shows that we don't have any instance matching the
second "Don't" example:
git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/CodingGuidelines | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 9fca21cc5f9..3d3bdeba9e4 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -650,8 +650,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -665,6 +665,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 02/36] builtin/bundle.c: indent with tabs
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 01/36] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:01 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (35 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix indentation issues introduced with 73c3253d75e (bundle: framework
for options before bundle file, 2019-11-10), and carried forward in
some subsequent commits.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index e80efce3a42..5c78894afd5 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,31 +12,31 @@
*/
static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ N_("git bundle verify [<options>] <file>"),
+ N_("git bundle list-heads <file> [<refname>...]"),
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
- NULL
+ N_("git bundle verify [<options>] <file>"),
+ NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
- NULL
+ N_("git bundle list-heads <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static int parse_options_cmd_bundle(int argc,
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 02/36] builtin/bundle.c: indent with tabs
2022-09-30 18:07 ` [PATCH v3 02/36] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:01 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:01 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Fix indentation issues introduced with 73c3253d75e (bundle: framework
> for options before bundle file, 2019-11-10), and carried forward in
> some subsequent commits.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> builtin/bundle.c | 26 +++++++++++++-------------
> 1 file changed, 13 insertions(+), 13 deletions(-)
Makes sense. "git show -w" allows us to see that the indentation is
the only change made with this step, too.
>
> diff --git a/builtin/bundle.c b/builtin/bundle.c
> index e80efce3a42..5c78894afd5 100644
> --- a/builtin/bundle.c
> +++ b/builtin/bundle.c
> @@ -12,31 +12,31 @@
> */
>
> static const char * const builtin_bundle_usage[] = {
> - N_("git bundle create [<options>] <file> <git-rev-list args>"),
> - N_("git bundle verify [<options>] <file>"),
> - N_("git bundle list-heads <file> [<refname>...]"),
> - N_("git bundle unbundle <file> [<refname>...]"),
> - NULL
> + N_("git bundle create [<options>] <file> <git-rev-list args>"),
> + N_("git bundle verify [<options>] <file>"),
> + N_("git bundle list-heads <file> [<refname>...]"),
> + N_("git bundle unbundle <file> [<refname>...]"),
> + NULL
> };
>
> static const char * const builtin_bundle_create_usage[] = {
> - N_("git bundle create [<options>] <file> <git-rev-list args>"),
> - NULL
> + N_("git bundle create [<options>] <file> <git-rev-list args>"),
> + NULL
> };
>
> static const char * const builtin_bundle_verify_usage[] = {
> - N_("git bundle verify [<options>] <file>"),
> - NULL
> + N_("git bundle verify [<options>] <file>"),
> + NULL
> };
>
> static const char * const builtin_bundle_list_heads_usage[] = {
> - N_("git bundle list-heads <file> [<refname>...]"),
> - NULL
> + N_("git bundle list-heads <file> [<refname>...]"),
> + NULL
> };
>
> static const char * const builtin_bundle_unbundle_usage[] = {
> - N_("git bundle unbundle <file> [<refname>...]"),
> - NULL
> + N_("git bundle unbundle <file> [<refname>...]"),
> + NULL
> };
>
> static int parse_options_cmd_bundle(int argc,
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 01/36] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 02/36] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:01 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L Ævar Arnfjörð Bjarmason
` (34 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git bundle" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 29 +++++++++++++++++++----------
1 file changed, 19 insertions(+), 10 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 5c78894afd5..1b08700bf9e 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -11,31 +11,40 @@
* bundle supporting "fetch", "pull", and "ls-remote".
*/
-static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+#define BUILTIN_BUNDLE_CREATE_USAGE \
+ N_("git bundle create [<options>] <file> <git-rev-list args>")
+#define BUILTIN_BUNDLE_VERIFY_USAGE \
+ N_("git bundle verify [<options>] <file>")
+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
+ N_("git bundle list-heads <file> [<refname>...]")
+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
+ N_("git bundle unbundle <file> [<refname>...]")
+
+static char const * const builtin_bundle_usage[] = {
+ BUILTIN_BUNDLE_CREATE_USAGE,
+ BUILTIN_BUNDLE_VERIFY_USAGE,
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
+ NULL,
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ BUILTIN_BUNDLE_CREATE_USAGE,
NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
+ BUILTIN_BUNDLE_VERIFY_USAGE,
NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h
2022-09-30 18:07 ` [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:01 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:01 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Avoid repeating the "-h" output for the "git bundle" command, and
> instead define the usage of each subcommand with macros, so that the
> "-h" output for the command itself can re-use those definitions. See
> [1], [2] and [3] for prior art using the same pattern.
>
> 1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
> macro, 2021-03-30)
> 2. 8757b35d443 (commit-graph: define common usage with a macro,
> 2021-08-23)
> 3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
> 2022-03-17)
This of course is an improvement, but makes me wonder if we need to
device even more concise ways to simplify all these commands with
subcommands.
Unlike the simplest case like this one, where no subcommand take any
option, a more general mechanism needs to allow some subcommands to
take their own options, so it will probably not an easy thing to do,
and a more general one that allows us to write each string only once
would probably need its own "mark-up" language, so it would probably
not be a good direction to go. So let's declare that the pattern
used in the result of applying this patch is the optimal one and
stop there.
Thanks.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> builtin/bundle.c | 29 +++++++++++++++++++----------
> 1 file changed, 19 insertions(+), 10 deletions(-)
>
> diff --git a/builtin/bundle.c b/builtin/bundle.c
> index 5c78894afd5..1b08700bf9e 100644
> --- a/builtin/bundle.c
> +++ b/builtin/bundle.c
> @@ -11,31 +11,40 @@
> * bundle supporting "fetch", "pull", and "ls-remote".
> */
>
> -static const char * const builtin_bundle_usage[] = {
> - N_("git bundle create [<options>] <file> <git-rev-list args>"),
> - N_("git bundle verify [<options>] <file>"),
> - N_("git bundle list-heads <file> [<refname>...]"),
> - N_("git bundle unbundle <file> [<refname>...]"),
> - NULL
> +#define BUILTIN_BUNDLE_CREATE_USAGE \
> + N_("git bundle create [<options>] <file> <git-rev-list args>")
> +#define BUILTIN_BUNDLE_VERIFY_USAGE \
> + N_("git bundle verify [<options>] <file>")
> +#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
> + N_("git bundle list-heads <file> [<refname>...]")
> +#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
> + N_("git bundle unbundle <file> [<refname>...]")
> +
> +static char const * const builtin_bundle_usage[] = {
> + BUILTIN_BUNDLE_CREATE_USAGE,
> + BUILTIN_BUNDLE_VERIFY_USAGE,
> + BUILTIN_BUNDLE_LIST_HEADS_USAGE,
> + BUILTIN_BUNDLE_UNBUNDLE_USAGE,
> + NULL,
> };
>
> static const char * const builtin_bundle_create_usage[] = {
> - N_("git bundle create [<options>] <file> <git-rev-list args>"),
> + BUILTIN_BUNDLE_CREATE_USAGE,
> NULL
> };
>
> static const char * const builtin_bundle_verify_usage[] = {
> - N_("git bundle verify [<options>] <file>"),
> + BUILTIN_BUNDLE_VERIFY_USAGE,
> NULL
> };
>
> static const char * const builtin_bundle_list_heads_usage[] = {
> - N_("git bundle list-heads <file> [<refname>...]"),
> + BUILTIN_BUNDLE_LIST_HEADS_USAGE,
> NULL
> };
>
> static const char * const builtin_bundle_unbundle_usage[] = {
> - N_("git bundle unbundle <file> [<refname>...]"),
> + BUILTIN_BUNDLE_UNBUNDLE_USAGE,
> NULL
> };
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:00 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
` (33 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Improve the error message emitted when there's a bad -L argument, and
do so using the parse-options.c flavor of "usage()", instead of using
the non-parse-options.c usage() function. This was the last user of
usage() in this file.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/blame.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/builtin/blame.c b/builtin/blame.c
index a9fe8cf7a68..8ec59fa2096 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
anchor = 1;
range_set_init(&ranges, range_list.nr);
for (range_i = 0; range_i < range_list.nr; ++range_i) {
+ const char *arg = range_list.items[range_i].string;
long bottom, top;
- if (parse_range_arg(range_list.items[range_i].string,
- nth_line_cb, &sb, lno, anchor,
+ if (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,
&bottom, &top, sb.path,
the_repository->index))
- usage(blame_usage);
+ usage_msg_optf(_("failed to parse -L argument '%s'"),
+ blame_opt_usage, options, arg);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L
2022-09-30 18:07 ` [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:00 ` Junio C Hamano
2022-10-03 8:36 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:00 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Improve the error message emitted when there's a bad -L argument, and
> do so using the parse-options.c flavor of "usage()", instead of using
> the non-parse-options.c usage() function. This was the last user of
> usage() in this file.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> builtin/blame.c | 7 ++++---
> 1 file changed, 4 insertions(+), 3 deletions(-)
This may not be incorrect (I didn't spend time to see if this "while
at it" is truly an improvement) but clearly outside the scome of
"output from the -h option should match synopsis" theme.
> diff --git a/builtin/blame.c b/builtin/blame.c
> index a9fe8cf7a68..8ec59fa2096 100644
> --- a/builtin/blame.c
> +++ b/builtin/blame.c
> @@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
> anchor = 1;
> range_set_init(&ranges, range_list.nr);
> for (range_i = 0; range_i < range_list.nr; ++range_i) {
> + const char *arg = range_list.items[range_i].string;
> long bottom, top;
> - if (parse_range_arg(range_list.items[range_i].string,
> - nth_line_cb, &sb, lno, anchor,
> + if (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,
> &bottom, &top, sb.path,
> the_repository->index))
> - usage(blame_usage);
> + usage_msg_optf(_("failed to parse -L argument '%s'"),
> + blame_opt_usage, options, arg);
So, it used to be that it emitted only blame_usage which is a rough
match to the synopsis,
"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>"
but now we use blame_opt_usage + options, which means that the same
blame_usage, a blank line, and "<rev-opts> are documented in
git-rev-list(1)" is given, followed by the list of full options.
I do think saying "failed to parse -L" is an improvement, but it is
dubious it is a good idea to follow it with a wall of text that
comes from options[]. After all, if the user chose to use "-L 2,8"
and a typo replaced the comma with a full stop, which caused
parse_range_arg() to fail, does it make sense to scroll away the
message that helpfully points out that "-L argument '2.8'" was the
problem with other option descriptions?
This is why we shouldn't distract a series with "while at it"
changes that are outside the scope of the theme. Letting the patch
authors and reviewers concentrate on doing one thing well would
avoid mistakes, but mixing unrelated changes distracts them. Having
to think about the differences between usage() and usage_msg_optf()
with this change already distracted me and stopped my review on this
series in this sitting. The topic will need to wait for the next
time I decide to sit with it and start reading it from the next step.
And of course, a series like this, which is supposed to do the same
thing to many files for consistency, is better written and reviewed
in one sitting, because that will make it easier in reviewers' mind
to keep and apply the same review criteria consistently.
> if ((!lno && (top || bottom)) || lno < bottom)
> die(Q_("file %s has only %lu line",
> "file %s has only %lu lines",
^ permalink raw reply [flat|nested] 230+ messages in thread* Re: [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L
2022-09-30 21:00 ` Junio C Hamano
@ 2022-10-03 8:36 ` Ævar Arnfjörð Bjarmason
0 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-03 8:36 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
On Fri, Sep 30 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> Improve the error message emitted when there's a bad -L argument, and
>> do so using the parse-options.c flavor of "usage()", instead of using
>> the non-parse-options.c usage() function. This was the last user of
>> usage() in this file.
>>
>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
>> ---
>> builtin/blame.c | 7 ++++---
>> 1 file changed, 4 insertions(+), 3 deletions(-)
>
> This may not be incorrect (I didn't spend time to see if this "while
> at it" is truly an improvement) but clearly outside the scome of
> "output from the -h option should match synopsis" theme.
I'll eject this & rewrite a subsequent commit, as a re-roll will make
clear the choice was between "convert this last user of the API" early
on, or in a later commit have the "-h" output be correct for both
usage() and usage_with_options()>
>> diff --git a/builtin/blame.c b/builtin/blame.c
>> index a9fe8cf7a68..8ec59fa2096 100644
>> --- a/builtin/blame.c
>> +++ b/builtin/blame.c
>> @@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
>> anchor = 1;
>> range_set_init(&ranges, range_list.nr);
>> for (range_i = 0; range_i < range_list.nr; ++range_i) {
>> + const char *arg = range_list.items[range_i].string;
>> long bottom, top;
>> - if (parse_range_arg(range_list.items[range_i].string,
>> - nth_line_cb, &sb, lno, anchor,
>> + if (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,
>> &bottom, &top, sb.path,
>> the_repository->index))
>> - usage(blame_usage);
>> + usage_msg_optf(_("failed to parse -L argument '%s'"),
>> + blame_opt_usage, options, arg);
>
> So, it used to be that it emitted only blame_usage which is a rough
> match to the synopsis,
>
> "git blame [<options>] [<rev-opts>] [<rev>] [--] <file>"
>
> but now we use blame_opt_usage + options, which means that the same
> blame_usage, a blank line, and "<rev-opts> are documented in
> git-rev-list(1)" is given, followed by the list of full options.
>
> I do think saying "failed to parse -L" is an improvement, but it is
> dubious it is a good idea to follow it with a wall of text that
> comes from options[]. After all, if the user chose to use "-L 2,8"
> and a typo replaced the comma with a full stop, which caused
> parse_range_arg() to fail, does it make sense to scroll away the
> message that helpfully points out that "-L argument '2.8'" was the
> problem with other option descriptions?
As an aside: This is a good general observation about
usage_with_options(), and usage_msg_opt*() in particular. I.e. it would
be helpful to have a version of it that took a "-L" argument, so we
could know what option we're complaining about.
Then we could either show the usage message just for that option, or
highlight it in the full "-h" output we're showing.
But obviously all for some later date.
> This is why we shouldn't distract a series with "while at it"
> changes that are outside the scope of the theme. Letting the patch
> authors and reviewers concentrate on doing one thing well would
> avoid mistakes, but mixing unrelated changes distracts them. Having
> to think about the differences between usage() and usage_msg_optf()
> with this change already distracted me and stopped my review on this
> series in this sitting. The topic will need to wait for the next
> time I decide to sit with it and start reading it from the next step.
>
> And of course, a series like this, which is supposed to do the same
> thing to many files for consistency, is better written and reviewed
> in one sitting, because that will make it easier in reviewers' mind
> to keep and apply the same review criteria consistently.
Noted, FWIW I was assuming that as other commands make wide use of
usage_msg_opt*() for this sort of thing that the usage here & output
change didn't need too much rationalizing, but live & learn etc. Thanks.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:23 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 06/36] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
` (32 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Almost all of our documentation doesn't use "'" syntax for
subcommands, but these did, let's make them consistent with the
rest.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index db9d46edfa9..0537d4645be 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -17,7 +17,7 @@ The command takes various subcommands, and different options
depending on the subcommand:
[verse]
-'git reflog' ['show'] [<log-options>] [<ref>]
+'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4cfc8833780..4b613d4140c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
DESCRIPTION
-----------
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands
2022-09-30 18:07 ` [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:23 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:23 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Almost all of our documentation doesn't use "'" syntax for
> subcommands, but these did, let's make them consistent with the
> rest.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-reflog.txt | 2 +-
> Documentation/git-rerere.txt | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
Good.
> diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
> index db9d46edfa9..0537d4645be 100644
> --- a/Documentation/git-reflog.txt
> +++ b/Documentation/git-reflog.txt
> @@ -17,7 +17,7 @@ The command takes various subcommands, and different options
> depending on the subcommand:
>
> [verse]
> -'git reflog' ['show'] [<log-options>] [<ref>]
> +'git reflog' [show] [<log-options>] [<ref>]
> 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
> [--rewrite] [--updateref] [--stale-fix]
> [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
> index 4cfc8833780..4b613d4140c 100644
> --- a/Documentation/git-rerere.txt
> +++ b/Documentation/git-rerere.txt
> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
> SYNOPSIS
> --------
> [verse]
> -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
> +'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
>
> DESCRIPTION
> -----------
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 06/36] doc SYNOPSIS: consistently use ' for commands
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
` (31 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Most of our commands use ''-quotation only for the name of the command
itself, and not its (optional) arguments. Let's do the same for these.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-fast-export.txt | 2 +-
Documentation/git-sparse-checkout.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 1978dbdc6ad..4643ddbe68f 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -9,7 +9,7 @@ git-fast-export - Git data exporter
SYNOPSIS
--------
[verse]
-'git fast-export [<options>]' | 'git fast-import'
+'git fast-export' [<options>] | 'git fast-import'
DESCRIPTION
-----------
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 3776705bf53..872436d7426 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [<options>]'
+'git sparse-checkout' <subcommand> [<options>]
DESCRIPTION
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 06/36] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:28 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 08/36] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
` (30 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
This issue has been with us in both the "-h" and *.txt versions since
bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
There are also issues with the alternates syntax for "bugreport" and
"diagnose", but in those cases only for one of *.c or *.txt, not
both. Those issues will be fixed in a subsequent "consistency" commit.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 6 +++---
builtin/stash.c | 6 +++---
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index c5d70918283..4856f452511 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -14,12 +14,12 @@ SYNOPSIS
'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [-m|--message <message>]
+ [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
DESCRIPTION
-----------
@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
COMMANDS
--------
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
diff --git a/builtin/stash.c b/builtin/stash.c
index 2274aae2556..51d40efaac7 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [-m|--message <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax
2022-09-30 18:07 ` [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:28 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:28 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Fix the incorrect "[-o | --option <argument>]" syntax, which should be
> "[(-o | --option) <argument>]", we were previously claiming that only
> the long option accepted the "<argument>", which isn't what we meant.
It depends on which way you look at it ;-) namely, if vertical bar
binds tighter than option and its argument, then "-m|--message
<message>" and "(-m|--message) <message>" would mean the same thing.
Later in the series, we start insisting that the vertical bar must
have SP on both of its sides, which makes the vertical bar less
tightly binding visually, and at that point, adding parentheses
around the choices does become needed.
As long as these become consistent, the end result is happier than
the status quo.
> - [-u|--include-untracked] [-a|--all] [-m|--message <message>]
> + [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
> -'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
> +'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
Thanks.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 08/36] built-ins: consistently add "\n" between "usage" and options
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:31 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 09/36] doc SYNOPSIS & -h: word-wrap Ævar Arnfjörð Bjarmason
` (29 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change commands in the "diff" family and "rev-list" to separate the
usage information and option listing with an empty line.
In the case of "git diff -h" we did this already (but let's use a
consistent "\n" pattern there), for the rest these are now consistent
with how the parse_options() API would emit usage.
As we'll see in a subsequent commit this also helps to make the "git
<cmd> -h" output more easily machine-readable, as we can assume that
the usage information is separated from the options by an empty line.
Note that "COMMON_DIFF_OPTIONS_HELP" starts with a "\n", so the
seeming omission of a "\n" here is correct, the second one is provided
by the macro.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-files.c | 1 +
builtin/diff-index.c | 1 +
builtin/diff-tree.c | 1 +
builtin/diff.c | 3 ++-
builtin/rev-list.c | 1 +
5 files changed, 6 insertions(+), 1 deletion(-)
diff --git a/builtin/diff-files.c b/builtin/diff-files.c
index 92cf6e1e922..096ea2fedbc 100644
--- a/builtin/diff-files.c
+++ b/builtin/diff-files.c
@@ -15,6 +15,7 @@
static const char diff_files_usage[] =
"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_files(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index 7d158af6b6d..e667cf52e7d 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -11,6 +11,7 @@
static const char diff_cache_usage[] =
"git diff-index [-m] [--cached] "
"[<common-diff-options>] <tree-ish> [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_index(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 116097a404a..23f58702fa0 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)
static const char diff_tree_usage[] =
"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
" --cc show combined diff for merge commits removing uninteresting hunks\n"
diff --git a/builtin/diff.c b/builtin/diff.c
index 54bb3de964c..67760b67552 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =
" or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
" or: git diff [<options>] <commit>...<commit> [--] [<path>...]\n"
" or: git diff [<options>] <blob> <blob>\n"
-" or: git diff [<options>] --no-index [--] <path> <path>\n"
+" or: git diff [<options>] --no-index [--] <path> <path>"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
static const char *blob_path(struct object_array_entry *entry)
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index fba6f5d51f3..f67e2b33555 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -21,6 +21,7 @@
static const char rev_list_usage[] =
"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"\n"
" limiting output:\n"
" --max-count=<n>\n"
" --max-age=<epoch>\n"
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 09/36] doc SYNOPSIS & -h: word-wrap
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 08/36] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 10/36] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
` (28 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the documentation and -h output for those built-in commands
where both the -h output and *.txt were lacking in word-wrapping.
There are many more built-ins that could use this treatment, this
change is narrowed to those where this whitespace change is needed to
make the -h and *.txt consistent in the end.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-hash-object.txt | 3 ++-
builtin/hash-object.c | 3 ++-
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index df9e2c58bdb..58670ef12f7 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+ [--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
DESCRIPTION
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index fbae878c2b9..f7c16802f0c 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
+ " [--stdin] [--] <file>..."),
"git hash-object --stdin-paths",
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 10/36] doc txt & -h consistency: word-wrap
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 09/36] doc SYNOPSIS & -h: word-wrap Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
` (27 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the documentation and -h output for those built-in commands
where the *.txt and -h output didn't match as far as word-wrapping was
concerned.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-worktree.txt | 3 ++-
builtin/bugreport.c | 3 ++-
builtin/commit-graph.c | 8 ++++----
builtin/commit-tree.c | 4 ++--
builtin/diagnose.c | 3 ++-
builtin/init-db.c | 3 ++-
builtin/interpret-trailers.c | 4 +++-
builtin/read-tree.c | 4 +++-
builtin/show-branch.c | 3 ++-
builtin/show-ref.c | 4 +++-
10 files changed, 25 insertions(+), 14 deletions(-)
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index ada30c86a7c..063d6eeb99d 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees
SYNOPSIS
--------
[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+ [-b <new-branch>] <path> [<commit-ish>]
'git worktree list' [-v | --porcelain [-z]]
'git worktree lock' [--reason <string>] <worktree>
'git worktree move' <worktree> <new-path>
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 530895be55f..faa268f3cfb 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]"),
+ N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ " [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 51557fe786e..cd346f95f08 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -13,10 +13,10 @@
N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append] " \
- "[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] " \
- "[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] " \
- "<split options>")
+ N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
+ " <split options>")
static const char * builtin_commit_graph_verify_usage[] = {
BUILTIN_COMMIT_GRAPH_VERIFY_USAGE,
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 63ea3229333..e4b85d29d56 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,8 +15,8 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
- N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] "
- "[(-F <file>)...] <tree>"),
+ N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
+ " [(-F <file>)...] <tree>"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 576e0e8e385..28c394a62a5 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,8 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]"),
+ N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ " [--mode=<mode>]"),
NULL
};
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 546f9c595e7..08ba006d55e 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
}
static const char *const init_db_usage[] = {
- N_("git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]"),
+ N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 84748eafc01..4cf0cf265dc 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -13,7 +13,9 @@
#include "config.h"
static const char * const git_interpret_trailers_usage[] = {
- N_("git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]"),
+ N_("git interpret-trailers [--in-place] [--trim-empty]\n"
+ " [(--trailer <token>[(=|:)<value>])...]\n"
+ " [<file>...]"),
NULL
};
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index 9f1f33e9546..b3a389e1b1f 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)
}
static const char * const read_tree_usage[] = {
- N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) [-u | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
+ N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
+ " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
diff --git a/builtin/show-branch.c b/builtin/show-branch.c
index d3f5715e3e3..c013abaf942 100644
--- a/builtin/show-branch.c
+++ b/builtin/show-branch.c
@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {
N_("git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n"
" [--current] [--color[=<when>] | --no-color] [--sparse]\n"
" [--more=<n> | --list | --independent | --merge-base]\n"
- " [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]"),
+ " [--no-name | --sha1-name] [--topics]\n"
+ " [(<rev> | <glob>)...]"),
N_("git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]"),
NULL
};
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 48569061087..3af6a53ee97 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -9,7 +9,9 @@
#include "parse-options.h"
static const char * const show_ref_usage[] = {
- N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]"),
+ N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\n"
+ " [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n"
+ " [--heads] [--] [<pattern>...]"),
N_("git show-ref --exclude-existing[=<pattern>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 10/36] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 1:09 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 12/36] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
` (26 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
This syntax issue for "bugreport" originated in
238b439d698 (bugreport: add tool to generate debugging info,
2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
"bugreport" documentation and code.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bugreport.c | 2 +-
builtin/diagnose.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index faa268f3cfb..23170113cc8 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
" [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 28c394a62a5..474de9ec647 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax
2022-09-30 18:07 ` [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-10-01 1:09 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 1:09 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Fix the incorrect "[-o | --option <argument>]" syntax, which should be
> "[(-o | --option) <argument>]", we were previously claiming that only
> the long option accepted the "<argument>", which isn't what we meant.
>
> This syntax issue for "bugreport" originated in
> 238b439d698 (bugreport: add tool to generate debugging info,
> 2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
> create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
> "bugreport" documentation and code.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> builtin/bugreport.c | 2 +-
> builtin/diagnose.c | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
I think we saw exactly the same pattern in an earlier step. If the
patches in this series are split along the type of fix, then these
two and the other patch fall into the same category. Another way to
organize is to split per file boundary, but I think these two paths
are fixed up for different problem in later steps. I think split
along the type of fix makes much more sense, if we can, than split
per file, so I am almost OK with the current organization (probably
with this squashed into that earlier step).
> diff --git a/builtin/bugreport.c b/builtin/bugreport.c
> index faa268f3cfb..23170113cc8 100644
> --- a/builtin/bugreport.c
> +++ b/builtin/bugreport.c
> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
> }
>
> static const char * const bugreport_usage[] = {
> - N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
> + N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
> " [--diagnose[=<mode>]"),
> NULL
> };
> diff --git a/builtin/diagnose.c b/builtin/diagnose.c
> index 28c394a62a5..474de9ec647 100644
> --- a/builtin/diagnose.c
> +++ b/builtin/diagnose.c
> @@ -3,7 +3,7 @@
> #include "diagnose.h"
>
> static const char * const diagnose_usage[] = {
> - N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
> + N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
> " [--mode=<mode>]"),
> NULL
> };
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 12/36] doc txt & -h consistency: add "-z" to cat-file "-h"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (10 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 13/36] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
` (25 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited
input with `-z`, 2022-07-22), before that change the SYNOPSIS and "-h"
output were the same, but not afterwards.
That change followed a similar earlier divergence in
473fa2df08d (Documentation: add --batch-command to cat-file synopsis,
2022-04-07). Subsequent commits will fix this sort of thing more
systematically, but let's fix this one as a one-off.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/cat-file.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/cat-file.c b/builtin/cat-file.c
index 989eee0bb4c..fa7bd891692 100644
--- a/builtin/cat-file.c
+++ b/builtin/cat-file.c
@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)
N_("git cat-file (-t | -s) [--allow-unknown-type] <object>"),
N_("git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\n"
" [--buffer] [--follow-symlinks] [--unordered]\n"
- " [--textconv | --filters]"),
+ " [--textconv | --filters] [-z]"),
N_("git cat-file (--textconv | --filters)\n"
" [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]"),
NULL
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 13/36] doc txt & -h consistency: balance unbalanced "[" and "]"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (11 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 12/36] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 14/36] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
` (24 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a "-h" output syntax issue introduced when "--diagnose" was added
in aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,
2022-08-12): We need to close the "[" we opened. The
corresponding *.txt change did not have the same issue.
The "help -h" output then had one "]" too many, which is an issue
introduced in b40845293b5 (help: correct the usage string in -h and
documentation, 2021-09-10).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bugreport.c | 2 +-
builtin/help.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 23170113cc8..bb138161943 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
static const char * const bugreport_usage[] = {
N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
- " [--diagnose[=<mode>]"),
+ " [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/help.c b/builtin/help.c
index 6f2796f211e..53f2812dfb1 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {
};
static const char * const builtin_help_usage[] = {
- "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
+ "git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]",
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
"git help [-g|--guides]",
"git help [-c|--config]",
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 14/36] doc txt & -h consistency: correct padding around "[]()"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (12 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 13/36] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:40 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 15/36] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
` (23 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-diff-files.txt | 2 +-
Documentation/git-hash-object.txt | 2 +-
Documentation/git-merge-base.txt | 4 ++--
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-send-pack.txt | 2 +-
Documentation/git-show-branch.txt | 4 ++--
Documentation/git-show-ref.txt | 4 ++--
Documentation/git-var.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
builtin/bugreport.c | 2 +-
builtin/commit-graph.c | 2 +-
builtin/diagnose.c | 2 +-
builtin/sparse-checkout.c | 2 +-
15 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index bf1febb9ae7..591e3801b7b 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index
SYNOPSIS
--------
[verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 58670ef12f7..472b5bb995b 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]
[--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 2d944e0851f..b01ba3d3565 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
--------
[verse]
-'git merge-base' [-a|--all] <commit> <commit>...
-'git merge-base' [-a|--all] --octopus <commit>...
+'git merge-base' [-a | --all] <commit> <commit>...
+'git merge-base' [-a | --all] --octopus <commit>...
'git merge-base' --is-ancestor <commit> <commit>
'git merge-base' --independent <commit>...
'git merge-base' --fork-point <ref> [<commit>]
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index ee7034b5e52..dda80a740c8 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
SYNOPSIS
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
DESCRIPTION
-----------
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 9fed59a3172..844d6f808a0 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files
SYNOPSIS
--------
[verse]
-'git prune-packed' [-n|--dry-run] [-q|--quiet]
+'git prune-packed' [-n | --dry-run] [-q | --quiet]
DESCRIPTION
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4b613d4140c..9d0e6f53e7e 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
DESCRIPTION
-----------
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index be41f119740..e0c71623432 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
- [--[no-]signed|--signed=(true|false|if-asked)]
+ [--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
DESCRIPTION
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index e5ec6b467f9..71f608b1ff1 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits
SYNOPSIS
--------
[verse]
-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]
+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
[(<rev> | <glob>)...]
-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]
DESCRIPTION
-----------
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ab4d271925d..d1d56f68b43 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository
SYNOPSIS
--------
[verse]
-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]
- [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
'git show-ref' --exclude-existing[=<pattern>]
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 387cc1b9142..6aa521fab23 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -9,7 +9,7 @@ git-var - Show a Git logical variable
SYNOPSIS
--------
[verse]
-'git var' ( -l | <variable> )
+'git var' (-l | <variable>)
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 61ca6d04c20..b8720dce8ab 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files
SYNOPSIS
--------
[verse]
-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...
+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
DESCRIPTION
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index bb138161943..61d93383f51 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index cd346f95f08..13cbb75ca28 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -14,7 +14,7 @@
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
- " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 474de9ec647..d52015c67a4 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
+ N_("git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 287716db68e..aac0f708e42 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init|list|set|add|reapply|disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 14/36] doc txt & -h consistency: correct padding around "[]()"
2022-09-30 18:07 ` [PATCH v3 14/36] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:40 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:40 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> The whitespace padding of alternatives should be of the form "[-f |
> --force]" not "[-f|--force]". Likewise we should not have padding
> before the first option, so "(--all | <pack-filename>...)" is correct,
> not "( --all | <pack-filename>... )".
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-diff-files.txt | 2 +-
> Documentation/git-hash-object.txt | 2 +-
> Documentation/git-merge-base.txt | 4 ++--
> Documentation/git-pack-redundant.txt | 2 +-
> Documentation/git-prune-packed.txt | 2 +-
> Documentation/git-rerere.txt | 2 +-
> Documentation/git-send-pack.txt | 2 +-
> Documentation/git-show-branch.txt | 4 ++--
> Documentation/git-show-ref.txt | 4 ++--
> Documentation/git-var.txt | 2 +-
> Documentation/git-verify-pack.txt | 2 +-
> builtin/bugreport.c | 2 +-
> builtin/commit-graph.c | 2 +-
> builtin/diagnose.c | 2 +-
> builtin/sparse-checkout.c | 2 +-
> 15 files changed, 18 insertions(+), 18 deletions(-)
Consistency is good.
And ...
> [verse]
> -'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
> +'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
>
> DESCRIPTION
> -----------
> diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
> index 9fed59a3172..844d6f808a0 100644
> --- a/Documentation/git-prune-packed.txt
> +++ b/Documentation/git-prune-packed.txt
> @@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files
> SYNOPSIS
> --------
> [verse]
> -'git prune-packed' [-n|--dry-run] [-q|--quiet]
> +'git prune-packed' [-n | --dry-run] [-q | --quiet]
... these show that they are easier to read with the proposed spacing.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 15/36] stash doc SYNOPSIS & -h: correct padding around "[]()"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (13 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 14/36] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 16/36] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
` (22 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 12 ++++++------
builtin/stash.c | 28 ++++++++++++++--------------
2 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 4856f452511..ea16d2eae7c 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -9,17 +9,17 @@ SYNOPSIS
--------
[verse]
'git stash' list [<log-options>]
-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q|--quiet] [<stash>]
-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+'git stash' drop [-q | --quiet] [<stash>]
+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
DESCRIPTION
-----------
diff --git a/builtin/stash.c b/builtin/stash.c
index 51d40efaac7..d91cf5fd3e1 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -24,16 +24,16 @@
static const char * const git_stash_usage[] = {
N_("git stash list [<options>]"),
N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q|--quiet] [<stash>]"),
- N_("git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
+ N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
- N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
- N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
NULL
};
@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 16/36] doc txt & -h consistency: use "<options>", not "<options>..."
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (14 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 15/36] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:43 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 17/36] t/helper/test-proc-receive.c: " Ævar Arnfjörð Bjarmason
` (21 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
It's arguably more correct to say "[<option>...]" than either of these
forms, but the vast majority of our documentation uses the
"[<options>]" form to indicate an arbitrary number of options, let's
do the same in these cases, which were the odd ones out.
In the case of "mv" and "sparse-checkout" let's add the missing "[]"
to indicate that these are optional.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-mv.txt | 2 +-
Documentation/git-status.txt | 2 +-
builtin/pack-objects.c | 4 ++--
builtin/sparse-checkout.c | 2 +-
4 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 79449bf98fe..972a055fbd8 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' <options>... <args>...
+'git mv' [<options>] <args>...
DESCRIPTION
-----------
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 54a4b29b473..5e438a7fdc1 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -9,7 +9,7 @@ git-status - Show the working tree status
SYNOPSIS
--------
[verse]
-'git status' [<options>...] [--] [<pathspec>...]
+'git status' [<options>] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 3658c05cafc..573d0b20b76 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,
#define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)
static const char *pack_usage[] = {
- N_("git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]"),
- N_("git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index aac0f708e42..58a22503f04 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) [<options>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 16/36] doc txt & -h consistency: use "<options>", not "<options>..."
2022-09-30 18:07 ` [PATCH v3 16/36] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:43 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:43 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> It's arguably more correct to say "[<option>...]" than either of these
> forms, but the vast majority of our documentation uses the
> "[<options>]" form to indicate an arbitrary number of options, let's
> do the same in these cases, which were the odd ones out.
Yeah, I agree these should say [<option>...] to mean zero-or-more of
them. It may be fine, as long as it is clear that we use
[<options>] as a short-hand for it, though.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 17/36] t/helper/test-proc-receive.c: use "<options>", not "<options>..."
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (15 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 16/36] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 21:46 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
` (20 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
As in a preceding commit use "<options>", not "<options>...", in this
case there is no *.txt version, but let's fix this one too while we're
at it.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/helper/test-proc-receive.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c
index cc08506cf0b..a4b305f4947 100644
--- a/t/helper/test-proc-receive.c
+++ b/t/helper/test-proc-receive.c
@@ -6,7 +6,7 @@
#include "test-tool.h"
static const char *proc_receive_usage[] = {
- "test-tool proc-receive [<options>...]",
+ "test-tool proc-receive [<options>]",
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 17/36] t/helper/test-proc-receive.c: use "<options>", not "<options>..."
2022-09-30 18:07 ` [PATCH v3 17/36] t/helper/test-proc-receive.c: " Ævar Arnfjörð Bjarmason
@ 2022-09-30 21:46 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 21:46 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> As in a preceding commit use "<options>", not "<options>...", in this
> case there is no *.txt version, but let's fix this one too while we're
> at it.
I do not quite understand why these need to be separate steps. Some
may be supposed to have the same description in the code (help text)
and in the text (doc source), and among them, some may have both
code and text wrong, and some others may have only code wrong, and
even some others only text wrong. It appears to me that you are
throwing the first one (both wrong) into a single category, and the
latter two (only one wrong) into a separate "not consistent"
category, which does not make much sense to me.
The end result of this step is good. It is just seeing the split is
somewhat distracting while reviewing.
Thanks.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> t/helper/test-proc-receive.c | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c
> index cc08506cf0b..a4b305f4947 100644
> --- a/t/helper/test-proc-receive.c
> +++ b/t/helper/test-proc-receive.c
> @@ -6,7 +6,7 @@
> #include "test-tool.h"
>
> static const char *proc_receive_usage[] = {
> - "test-tool proc-receive [<options>...]",
> + "test-tool proc-receive [<options>]",
> NULL
> };
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (16 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 17/36] t/helper/test-proc-receive.c: " Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 22:04 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 19/36] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
` (19 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various inconsistencies between command SYNOPSIS and the
corresponding -h output where our translatable labels didn't match
up.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 6 +++---
Documentation/git-credential-cache--daemon.txt | 2 +-
Documentation/git-mv.txt | 2 +-
Documentation/git-receive-pack.txt | 2 +-
Documentation/git-tag.txt | 2 +-
Documentation/git-upload-archive.txt | 4 ++--
builtin/bugreport.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 4 ++--
builtin/credential-cache--daemon.c | 2 +-
builtin/for-each-repo.c | 2 +-
builtin/pack-redundant.c | 2 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/stash.c | 2 +-
builtin/unpack-file.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/worktree.c | 2 +-
19 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 91742633fa8..3f16f200d9a 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
DESCRIPTION
-----------
@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`
option is specified, ignored files are also removed. This can, for
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
+If any optional `<pathspec>...` arguments are given, only those paths
are affected.
OPTIONS
-------
-d::
- Normally, when no <path> is specified, git clean will not
+ Normally, when no <pathspec> is specified, git clean will not
recurse into untracked directories to avoid removing too much.
Specify -d to have it recurse into such directories as well.
If any paths are specified, -d is irrelevant; all untracked
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index 01e1c214dd8..74832d06806 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
SYNOPSIS
--------
[verse]
-'git credential-cache{litdd}daemon' [--debug] <socket>
+'git credential-cache{litdd}daemon' [--debug] <socket-path>
DESCRIPTION
-----------
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 972a055fbd8..c612a5fd5b9 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' [<options>] <args>...
+'git mv' [<options>] <source>... <destination>
DESCRIPTION
-----------
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 014a78409b9..eec1268b10f 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <directory>
+'git-receive-pack' <git-dir>
DESCRIPTION
-----------
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 31a97a1b6c5..c15ec895720 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
SYNOPSIS
--------
[verse]
-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index fba0f1c1b27..e8eb10baad7 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
SYNOPSIS
--------
[verse]
-'git upload-archive' <directory>
+'git upload-archive' <repository>
DESCRIPTION
-----------
@@ -54,7 +54,7 @@ access via non-smart-http.
OPTIONS
-------
-<directory>::
+<repository>::
The repository to get a tar archive from.
GIT
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 61d93383f51..96052541cbf 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/clean.c b/builtin/clean.c
index 5466636e666..6f039f555b2 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 13cbb75ca28..e8f77f535f3 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -10,10 +10,10 @@
#include "tag.h"
#define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \
- N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
+ N_("git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
" [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index 4c6c89ab0de..ca672a6a619 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket_path>",
+ "git-credential-cache--daemon [opts] <socket-path>",
NULL
};
int debug = 0;
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index fd86e5a8619..c6379b783c8 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <command-args>"),
+ N_("git for-each-repo --config=<config> <arguments>"),
NULL
};
diff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c
index ed9b9013a5f..ecd49ca268f 100644
--- a/builtin/pack-redundant.c
+++ b/builtin/pack-redundant.c
@@ -14,7 +14,7 @@
#define BLKSIZE 512
static const char pack_redundant_usage[] =
-"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)";
+"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)";
static int load_all_packs, verbose, alt_odb;
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 83d7a778e37..12570537d37 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <path>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
NULL,
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index f67e2b33555..ada68a4af5e 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [-- <path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/stash.c b/builtin/stash.c
index d91cf5fd3e1..83c9591ea6d 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -22,7 +22,7 @@
#define INCLUDE_ALL_FILES 2
static const char * const git_stash_usage[] = {
- N_("git stash list [<options>]"),
+ N_("git stash list [<log-options>]"),
N_("git stash show [<options>] [<stash>]"),
N_("git stash drop [-q | --quiet] [<stash>]"),
N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
diff --git a/builtin/unpack-file.c b/builtin/unpack-file.c
index 58652229f27..9e8119dd354 100644
--- a/builtin/unpack-file.c
+++ b/builtin/unpack-file.c
@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)
struct object_id oid;
if (argc != 2 || !strcmp(argv[1], "-h"))
- usage("git unpack-file <sha1>");
+ usage("git unpack-file <blob>");
if (get_oid(argv[1], &oid))
die("Not a valid object name %s", argv[1]);
diff --git a/builtin/upload-archive.c b/builtin/upload-archive.c
index 98d028dae67..945ee2b4126 100644
--- a/builtin/upload-archive.c
+++ b/builtin/upload-archive.c
@@ -10,7 +10,7 @@
#include "strvec.h"
static const char upload_archive_usage[] =
- "git upload-archive <repo>";
+ "git upload-archive <repository>";
static const char deadchild[] =
"git upload-archive: archiver died with error";
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index 05c52135946..db9ac5c4606 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
NULL
};
diff --git a/builtin/worktree.c b/builtin/worktree.c
index c6710b25520..5bfc18e5a24 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {
N_("git worktree prune [<options>]"),
N_("git worktree remove [<options>] <worktree>"),
N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <path>"),
+ N_("git worktree unlock <worktree>"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels
2022-09-30 18:07 ` [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
@ 2022-09-30 22:04 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 22:04 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
> +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
>
> DESCRIPTION
> -----------
> @@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`
> option is specified, ignored files are also removed. This can, for
> example, be useful to remove all build products.
>
> -If any optional `<path>...` arguments are given, only those paths
> +If any optional `<pathspec>...` arguments are given, only those paths
> are affected.
If you replace <path> with <pathspec>, then "only those paths are"
must be replaced with "only those paths that match the pathspec
are", because you are losing "those paths" from the sentence.
> diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
> index 01e1c214dd8..74832d06806 100644
> --- a/Documentation/git-credential-cache--daemon.txt
> +++ b/Documentation/git-credential-cache--daemon.txt
> @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
> SYNOPSIS
> --------
> [verse]
> -'git credential-cache{litdd}daemon' [--debug] <socket>
> +'git credential-cache{litdd}daemon' [--debug] <socket-path>
>
> DESCRIPTION
> -----------
The description text (outside the context of this hunk) still refers
to <socket>.
> diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
> index 972a055fbd8..c612a5fd5b9 100644
> --- a/Documentation/git-mv.txt
> +++ b/Documentation/git-mv.txt
> @@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
> SYNOPSIS
> --------
> [verse]
> -'git mv' [<options>] <args>...
> +'git mv' [<options>] <source>... <destination>
This one is good, as the rest of the document is written in terms of
the source and the destination. The description of --force may need
to rephrase "target" -> "destination", though.
> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
> index 014a78409b9..eec1268b10f 100644
> --- a/Documentation/git-receive-pack.txt
> +++ b/Documentation/git-receive-pack.txt
> @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
> SYNOPSIS
> --------
> [verse]
> -'git-receive-pack' <directory>
> +'git-receive-pack' <git-dir>
`upload-archive` below is updated to call this <repository>, and
that might be a better update, but the goal of this step is to use
the same word in both code and text, so changing to <git-dir> is OK.
But "OPTIONS" part of the document (outside the context of this
hunk) still says <directory>, which should be corrected.
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 31a97a1b6c5..c15ec895720 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
> SYNOPSIS
> --------
> [verse]
> -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
> +'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
> <tagname> [<commit> | <object>]
> 'git tag' -d <tagname>...
> 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
If you want to do "keyid" -> "key-id", then you'd need to update the
one in the DESCRIPTION part.
> diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
> index fba0f1c1b27..e8eb10baad7 100644
> --- a/Documentation/git-upload-archive.txt
> +++ b/Documentation/git-upload-archive.txt
> @@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
> SYNOPSIS
> --------
> [verse]
> -'git upload-archive' <directory>
> +'git upload-archive' <repository>
>
> DESCRIPTION
> -----------
> @@ -54,7 +54,7 @@ access via non-smart-http.
>
> OPTIONS
> -------
> -<directory>::
> +<repository>::
> The repository to get a tar archive from.
This is good.
> diff --git a/builtin/bugreport.c b/builtin/bugreport.c
> index 61d93383f51..96052541cbf 100644
> --- a/builtin/bugreport.c
> +++ b/builtin/bugreport.c
> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
> }
>
> static const char * const bugreport_usage[] = {
> - N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
> + N_("git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
> " [--diagnose[=<mode>]]"),
> NULL
> };
> diff --git a/builtin/clean.c b/builtin/clean.c
> index 5466636e666..6f039f555b2 100644
> --- a/builtin/clean.c
> +++ b/builtin/clean.c
> @@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
> static unsigned int colopts;
>
> static const char *const builtin_clean_usage[] = {
> - N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>..."),
> + N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
> NULL
> };
>
> diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
> index 13cbb75ca28..e8f77f535f3 100644
> --- a/builtin/commit-graph.c
> +++ b/builtin/commit-graph.c
> @@ -10,10 +10,10 @@
> #include "tag.h"
>
> #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \
> - N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
> + N_("git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]")
>
> #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
> - N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
> + N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
> " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
> " [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
> " <split options>")
> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
> index 4c6c89ab0de..ca672a6a619 100644
> --- a/builtin/credential-cache--daemon.c
> +++ b/builtin/credential-cache--daemon.c
> @@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
> const char *socket_path;
> int ignore_sighup = 0;
> static const char *usage[] = {
> - "git-credential-cache--daemon [opts] <socket_path>",
> + "git-credential-cache--daemon [opts] <socket-path>",
> NULL
> };
> int debug = 0;
Heh, so we are allowed to change _BOTH_ code and text to make them
consistent. We are not limited to pick the existing word used in
one or the other. If that is the case, using <repository> instead
of <git-dir> for receive-pack may be a good change to make here as
well.
In any case, reviewing code part of this step is far easier than the
documentation part, as the latter must be done more carefully to
spot the mention of the earlier word in the entire document.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 19/36] doc txt & -h consistency: add or fix optional "--" syntax
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (17 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 22:09 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 20/36] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
` (18 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add the "[--]" for those cases where the *.txt and -h were
inconsistent, or where we incorrectly stated in one but not the other
that the "--" was mandatory.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/for-each-repo.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/verify-pack.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index c6379b783c8..d45d873f579 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <arguments>"),
+ N_("git for-each-repo --config=<config> [--] <arguments>"),
NULL
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index ada68a4af5e..3cc8aad52ed 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [[--] <path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index db9ac5c4606..27d6f75fd8a 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx..."),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 19/36] doc txt & -h consistency: add or fix optional "--" syntax
2022-09-30 18:07 ` [PATCH v3 19/36] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
@ 2022-09-30 22:09 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-09-30 22:09 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> diff --git a/builtin/rev-list.c b/builtin/rev-list.c
> index ada68a4af5e..3cc8aad52ed 100644
> --- a/builtin/rev-list.c
> +++ b/builtin/rev-list.c
> @@ -20,7 +20,7 @@
> #include "packfile.h"
>
> static const char rev_list_usage[] =
> -"git rev-list [<options>] <commit>... [-- <path>...]\n"
> +"git rev-list [<options>] <commit>... [[--] <path>...]\n"
As rev-list requires at least one commit, so <commit>... means one
or more of <commit>. Now rev-list does not have to have pathspec,
but it is OK to have the double-dash, so
git rev-list [<options>] <commit>... [--] [<path>...]
would be more correct, no? <path>... may mean one or more pathspec
elements, but having it inside [] makes it zero or more. But it is
not a crime to have "--" without any pathspec, yet [[--] <path>...]
requires one or more paths if you want to write "--".
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 20/36] doc txt & -h consistency: make output order consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (18 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 19/36] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
` (17 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix cases where the SYNOPSIS and -h output was presented in a
different order.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/merge-base.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/merge-base.c b/builtin/merge-base.c
index a11f8c6e4bb..6f3941f2a49 100644
--- a/builtin/merge-base.c
+++ b/builtin/merge-base.c
@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)
static const char * const merge_base_usage[] = {
N_("git merge-base [-a | --all] <commit> <commit>..."),
N_("git merge-base [-a | --all] --octopus <commit>..."),
- N_("git merge-base --independent <commit>..."),
N_("git merge-base --is-ancestor <commit> <commit>"),
+ N_("git merge-base --independent <commit>..."),
N_("git merge-base --fork-point <ref> [<commit>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (19 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 20/36] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 18:43 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
` (16 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various issues of SYNOPSIS and -h output syntax where:
* Options such as --force were missing entirely
* ...or the short option, such as -f
* We said "opts" or "options", but could instead enumerate
the (small) set of supported options
* argument labels were missing entirely (ls-remote)
* How we referred to an argument was inconsistent between the two,
e.g. <pack> v.s. <pack>.idx.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-send-pack.txt | 3 ++-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-update-server-info.txt | 8 +++++++-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
builtin/credential-cache--daemon.c | 2 +-
builtin/describe.c | 5 +++--
builtin/diff-index.c | 2 +-
builtin/ls-remote.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/revert.c | 9 +++++----
builtin/send-pack.c | 1 +
builtin/symbolic-ref.c | 5 +++--
builtin/tag.c | 10 ++++++----
builtin/update-server-info.c | 2 +-
builtin/upload-pack.c | 3 ++-
help.c | 2 +-
17 files changed, 38 insertions(+), 24 deletions(-)
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index e0c71623432..595b002152f 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository
SYNOPSIS
--------
[verse]
-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+'git send-pack' [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
[--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 872436d7426..68392d2a56e 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout' <subcommand> [<options>]
+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]
DESCRIPTION
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
index 969bb2e15f1..4e6bf44427f 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.txt
@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
SYNOPSIS
--------
[verse]
-'git update-server-info'
+'git update-server-info' [-f | --force]
DESCRIPTION
-----------
@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
what references and packs the server has. This command
generates such auxiliary files.
+OPTIONS
+-------
+-f::
+--force::
+ Allow adding otherwise ignored files.
+
OUTPUT
------
diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt
index 92097f6673d..96d10cfdffe 100644
--- a/Documentation/git-verify-commit.txt
+++ b/Documentation/git-verify-commit.txt
@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits
SYNOPSIS
--------
[verse]
-'git verify-commit' <commit>...
+'git verify-commit' [-v | --verbose] <commit>...
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
index 0b8075dad96..a454df2711e 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.txt
@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags
SYNOPSIS
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index ca672a6a619..d4eb0097d24 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket-path>",
+ "git-credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
diff --git a/builtin/describe.c b/builtin/describe.c
index e17c4b4c69b..23e3f05fb10 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -23,8 +23,9 @@
define_commit_slab(commit_names, struct commit_name *);
static const char * const describe_usage[] = {
- N_("git describe [<options>] [<commit-ish>...]"),
- N_("git describe [<options>] --dirty"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]"),
+ N_("git describe <blob>"),
NULL
};
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index e667cf52e7d..aea139b9d8f 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -9,7 +9,7 @@
#include "submodule.h"
static const char diff_cache_usage[] =
-"git diff-index [-m] [--cached] "
+"git diff-index [-m] [--cached] [--merge-base] "
"[<common-diff-options>] <tree-ish> [<path>...]"
"\n"
COMMON_DIFF_OPTIONS_HELP;
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index df44e5cc0d1..5d5ac038716 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -7,7 +7,7 @@
static const char * const ls_remote_usage[] = {
N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
- " [-q | --quiet] [--exit-code] [--get-url]\n"
+ " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
" [--symref] [<repository> [<refs>...]]"),
NULL
};
diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c
index cfbd5c36c76..27c2ca06acb 100644
--- a/builtin/pack-refs.c
+++ b/builtin/pack-refs.c
@@ -5,7 +5,7 @@
#include "repository.h"
static char const * const pack_refs_usage[] = {
- N_("git pack-refs [<options>]"),
+ N_("git pack-refs [--all] [--no-prune]"),
NULL
};
diff --git a/builtin/revert.c b/builtin/revert.c
index ee2a0807f01..ee32c714a76 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -21,14 +21,15 @@
*/
static const char * const revert_usage[] = {
- N_("git revert [<options>] <commit-ish>..."),
- N_("git revert <subcommand>"),
+ N_("git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>..."),
+ N_("git revert (--continue | --skip | --abort | --quit)"),
NULL
};
static const char * const cherry_pick_usage[] = {
- N_("git cherry-pick [<options>] <commit-ish>..."),
- N_("git cherry-pick <subcommand>"),
+ N_("git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n"
+ " [-S[<keyid>]] <commit>..."),
+ N_("git cherry-pick (--continue | --skip | --abort | --quit)"),
NULL
};
diff --git a/builtin/send-pack.c b/builtin/send-pack.c
index 64962be0168..4c5d125fa0a 100644
--- a/builtin/send-pack.c
+++ b/builtin/send-pack.c
@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {
N_("git send-pack [--mirror] [--dry-run] [--force]\n"
" [--receive-pack=<git-receive-pack>]\n"
" [--verbose] [--thin] [--atomic]\n"
+ " [--[no-]signed | --signed=(true|false|if-asked)]\n"
" [<host>:]<directory> (--all | <ref>...)"),
NULL,
};
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index 1b0f10225f0..50b6df78df0 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -5,8 +5,9 @@
#include "parse-options.h"
static const char * const git_symbolic_ref_usage[] = {
- N_("git symbolic-ref [<options>] <name> [<ref>]"),
- N_("git symbolic-ref -d [-q] <name>"),
+ N_("git symbolic-ref [-m <reason>] <name> <ref>"),
+ N_("git symbolic-ref [-q] [--short] <name>"),
+ N_("git symbolic-ref --delete [-q] <name>"),
NULL
};
diff --git a/builtin/tag.c b/builtin/tag.c
index 75dece0e4f1..d428c45dc8d 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -23,11 +23,13 @@
#include "date.h"
static const char * const git_tag_usage[] = {
- N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\n"
- " <tagname> [<head>]"),
+ N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n"
+ " <tagname> [<commit> | <object>]"),
N_("git tag -d <tagname>..."),
- N_("git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\n"
- " [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
+ N_("git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n"
+ " [--points-at <object>] [--column[=<options>] | --no-column]\n"
+ " [--create-reflog] [--sort=<key>] [--format=<format>]\n"
+ " [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
N_("git tag -v [--format=<format>] <tagname>..."),
NULL
};
diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c
index 880fffec587..d2239c9ef4d 100644
--- a/builtin/update-server-info.c
+++ b/builtin/update-server-info.c
@@ -4,7 +4,7 @@
#include "parse-options.h"
static const char * const update_server_info_usage[] = {
- "git update-server-info [--force]",
+ "git update-server-info [-f | --force]",
NULL
};
diff --git a/builtin/upload-pack.c b/builtin/upload-pack.c
index 125af53885f..25b69da2bf2 100644
--- a/builtin/upload-pack.c
+++ b/builtin/upload-pack.c
@@ -8,7 +8,8 @@
#include "serve.h"
static const char * const upload_pack_usage[] = {
- N_("git upload-pack [<options>] <dir>"),
+ N_("git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\n"
+ " [--advertise-refs] <directory>"),
NULL
};
diff --git a/help.c b/help.c
index d04542d8261..f1e090a4428 100644
--- a/help.c
+++ b/help.c
@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
int build_options = 0;
const char * const usage[] = {
- N_("git version [<options>]"),
+ N_("git version [--build-options]"),
NULL
};
struct option options[] = {
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels
2022-09-30 18:07 ` [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
@ 2022-10-01 18:43 ` Junio C Hamano
2022-10-01 23:44 ` Junio C Hamano
2022-10-04 10:13 ` Ævar Arnfjörð Bjarmason
0 siblings, 2 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 18:43 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Fix various issues of SYNOPSIS and -h output syntax where:
>
> * Options such as --force were missing entirely
> * ...or the short option, such as -f
In the full option listing (e.g. what usage_with_options() gives for
options with both short and long form, such as "git commit -h"), it
indeed is good to show both, i.e.
-q, --quiet run quietly
-v, --verbose run verbosely
is good and we have enough room to do so.
But for commands with so small number of options that we cram the
options on the summary line without hiding them behind a single
"[<options>]" placeholder, I am not sure if it is a good idea to
show both and do
usage: git cmd [-f|--force] [-q|--quiet] [-v|--verbose] <pathspec>
in the first place. It would be easier to understand without
distracting choice, i.e.
usage: git cmd [--force] [--quiet] [--verbose] <pathspec>
or even with only the short-form (but that risks to become
unfriendly to new people who haven't learned what a single letter
option "-x" means, so I would not recommend it).
Especially with the mandatory space around vertical bar, it would
look horrible,
usage: git cmd [-f | --force] [-q | --quiet] [-v | --verbose] <pathspec>
as the visual binding between the short and long form of the same
option becomes weaker.
So, I dunno.
> * We said "opts" or "options", but could instead enumerate
> the (small) set of supported options
Yes, see above.
> * argument labels were missing entirely (ls-remote)
I do not know what an "argument label" is, but I can see that
ls-remote.c lacked the description for the --sort option.
> * How we referred to an argument was inconsistent between the two,
> e.g. <pack> v.s. <pack>.idx.
I didn't see anything in this category in this patch.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> -'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
> +'git send-pack' [--mirror] [--dry-run] [--force]
> + [--receive-pack=<git-receive-pack>]
It may not matter what order the options are given, but having
anything before "--dry-run" looks somewhat strange. It is not like
this list is given in the same order as they appear in the options[]
array.
I wonder if "--mirror" is the most closely related to (read: easier
to understand if it is listed close to) "--all" and <ref>,
i.e. immediately before the destination repository?
We do not really care about these commands that end-users will never
invoke themselves, so I'll let it pass, even though this one looks a
bit questionable.
> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
> index 872436d7426..68392d2a56e 100644
> --- a/Documentation/git-sparse-checkout.txt
> +++ b/Documentation/git-sparse-checkout.txt
> @@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
> SYNOPSIS
> --------
> [verse]
> -'git sparse-checkout' <subcommand> [<options>]
> +'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]
OK. We have only limited number that fits on a line; otherwise
"<subcommand>" -> "<command>" which refers reders to the COMMANDS
section of the documentation.
> diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
> index 969bb2e15f1..4e6bf44427f 100644
> --- a/Documentation/git-update-server-info.txt
> +++ b/Documentation/git-update-server-info.txt
> @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
> SYNOPSIS
> --------
> [verse]
> -'git update-server-info'
> +'git update-server-info' [-f | --force]
>
> DESCRIPTION
> -----------
> @@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
> what references and packs the server has. This command
> generates such auxiliary files.
>
> +OPTIONS
> +-------
> +-f::
> +--force::
> + Allow adding otherwise ignored files.
The option help text says this:
N_("update the info files from scratch"), 0),
> diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt
> index 92097f6673d..96d10cfdffe 100644
> --- a/Documentation/git-verify-commit.txt
> +++ b/Documentation/git-verify-commit.txt
> @@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits
> SYNOPSIS
> --------
> [verse]
> -'git verify-commit' <commit>...
> +'git verify-commit' [-v | --verbose] <commit>...
>
> DESCRIPTION
> -----------
The DESCRIPTION section also mentions "--raw".
> diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
> index 0b8075dad96..a454df2711e 100644
> --- a/Documentation/git-verify-tag.txt
> +++ b/Documentation/git-verify-tag.txt
> @@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags
> SYNOPSIS
> --------
> [verse]
> -'git verify-tag' [--format=<format>] <tag>...
> +'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...
>
> DESCRIPTION
> -----------
The DESCRIPTION section also mentions "--raw".
> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
> index ca672a6a619..d4eb0097d24 100644
> --- a/builtin/credential-cache--daemon.c
> +++ b/builtin/credential-cache--daemon.c
> @@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
> const char *socket_path;
> int ignore_sighup = 0;
> static const char *usage[] = {
> - "git-credential-cache--daemon [opts] <socket-path>",
> + "git-credential-cache--daemon [--debug] <socket-path>",
> NULL
> };
> int debug = 0;
OK.
> diff --git a/builtin/describe.c b/builtin/describe.c
> index e17c4b4c69b..23e3f05fb10 100644
> --- a/builtin/describe.c
> +++ b/builtin/describe.c
> @@ -23,8 +23,9 @@
> define_commit_slab(commit_names, struct commit_name *);
>
> static const char * const describe_usage[] = {
> - N_("git describe [<options>] [<commit-ish>...]"),
> - N_("git describe [<options>] --dirty"),
> + N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]"),
> + N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]"),
> + N_("git describe <blob>"),
> NULL
> };
OK.
> diff --git a/builtin/diff-index.c b/builtin/diff-index.c
> index e667cf52e7d..aea139b9d8f 100644
> --- a/builtin/diff-index.c
> +++ b/builtin/diff-index.c
> @@ -9,7 +9,7 @@
> #include "submodule.h"
>
> static const char diff_cache_usage[] =
> -"git diff-index [-m] [--cached] "
> +"git diff-index [-m] [--cached] [--merge-base] "
> "[<common-diff-options>] <tree-ish> [<path>...]"
> "\n"
> COMMON_DIFF_OPTIONS_HELP;
OK.
> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
> index df44e5cc0d1..5d5ac038716 100644
> --- a/builtin/ls-remote.c
> +++ b/builtin/ls-remote.c
> @@ -7,7 +7,7 @@
>
> static const char * const ls_remote_usage[] = {
> N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
> - " [-q | --quiet] [--exit-code] [--get-url]\n"
> + " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
> " [--symref] [<repository> [<refs>...]]"),
> NULL
> };
OK.
We do not need to express that --sort=<key0> --sort=<key1>... can be
given multiple times without triggering the usual last-one-wins? In
the documentation, the option description can say "this option can
be given multiple times", but here we cannot, so the best we could
do would be [--sort=<key>...] and I wonder if that is worth it.
> diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c
> index cfbd5c36c76..27c2ca06acb 100644
> --- a/builtin/pack-refs.c
> +++ b/builtin/pack-refs.c
> @@ -5,7 +5,7 @@
> #include "repository.h"
>
> static char const * const pack_refs_usage[] = {
> - N_("git pack-refs [<options>]"),
> + N_("git pack-refs [--all] [--no-prune]"),
> NULL
> };
Even though "[--[no-]all] [--[no-]prune" would be more complete, I
do not mind listing only the side that makes it behave differently
from the default. But if you reroll with a more complete version
with documentation updates, I wouldn't complain at all.
> diff --git a/builtin/revert.c b/builtin/revert.c
> index ee2a0807f01..ee32c714a76 100644
> --- a/builtin/revert.c
> +++ b/builtin/revert.c
> @@ -21,14 +21,15 @@
> */
>
> static const char * const revert_usage[] = {
> - N_("git revert [<options>] <commit-ish>..."),
> - N_("git revert <subcommand>"),
> + N_("git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>..."),
> + N_("git revert (--continue | --skip | --abort | --quit)"),
> NULL
> };
This one uses "[--[no-]edit]", which is OK. Also <keyid> unlike the
other ones I saw in my yesterdays review is not <key-id>, which is
somewhat curious.
> static const char * const cherry_pick_usage[] = {
> - N_("git cherry-pick [<options>] <commit-ish>..."),
> - N_("git cherry-pick <subcommand>"),
> + N_("git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n"
> + " [-S[<keyid>]] <commit>..."),
> + N_("git cherry-pick (--continue | --skip | --abort | --quit)"),
> NULL
> };
And here we see "[--edit]", which is not exactly consistent.
> diff --git a/builtin/send-pack.c b/builtin/send-pack.c
> index 64962be0168..4c5d125fa0a 100644
> --- a/builtin/send-pack.c
> +++ b/builtin/send-pack.c
> @@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {
> N_("git send-pack [--mirror] [--dry-run] [--force]\n"
> " [--receive-pack=<git-receive-pack>]\n"
> " [--verbose] [--thin] [--atomic]\n"
> + " [--[no-]signed | --signed=(true|false|if-asked)]\n"
> " [<host>:]<directory> (--all | <ref>...)"),
> NULL,
> };
Excellent.
> diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
> index 1b0f10225f0..50b6df78df0 100644
> --- a/builtin/symbolic-ref.c
> +++ b/builtin/symbolic-ref.c
> @@ -5,8 +5,9 @@
> #include "parse-options.h"
>
> static const char * const git_symbolic_ref_usage[] = {
> - N_("git symbolic-ref [<options>] <name> [<ref>]"),
> - N_("git symbolic-ref -d [-q] <name>"),
> + N_("git symbolic-ref [-m <reason>] <name> <ref>"),
> + N_("git symbolic-ref [-q] [--short] <name>"),
> + N_("git symbolic-ref --delete [-q] <name>"),
> NULL
> };
Why spell out --delete without allowing -d? Especially when listing
only -q for OPT__QUIET()?
git symbolic-ref (-d|--delete) [-q|--quiet] <name>
would be more complete but I think the original (i.e. "-d [-q]") is
more consistent.
> diff --git a/builtin/tag.c b/builtin/tag.c
> index 75dece0e4f1..d428c45dc8d 100644
> --- a/builtin/tag.c
> +++ b/builtin/tag.c
> @@ -23,11 +23,13 @@
> #include "date.h"
>
> static const char * const git_tag_usage[] = {
> - N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\n"
> - " <tagname> [<head>]"),
> + N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n"
> + " <tagname> [<commit> | <object>]"),
OK.
> N_("git tag -d <tagname>..."),
> - N_("git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\n"
> - " [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
> + N_("git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n"
> + " [--points-at <object>] [--column[=<options>] | --no-column]\n"
> + " [--create-reflog] [--sort=<key>] [--format=<format>]\n"
> + " [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
OK.
> N_("git tag -v [--format=<format>] <tagname>..."),
> NULL
> };
> diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c
> index 880fffec587..d2239c9ef4d 100644
> --- a/builtin/update-server-info.c
> +++ b/builtin/update-server-info.c
> @@ -4,7 +4,7 @@
> #include "parse-options.h"
>
> static const char * const update_server_info_usage[] = {
> - "git update-server-info [--force]",
> + "git update-server-info [-f | --force]",
> NULL
> };
>
> diff --git a/builtin/upload-pack.c b/builtin/upload-pack.c
> index 125af53885f..25b69da2bf2 100644
> --- a/builtin/upload-pack.c
> +++ b/builtin/upload-pack.c
> @@ -8,7 +8,8 @@
> #include "serve.h"
>
> static const char * const upload_pack_usage[] = {
> - N_("git upload-pack [<options>] <dir>"),
> + N_("git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\n"
> + " [--advertise-refs] <directory>"),
> NULL
> };
OK. We do not really care about these commands that end-users will
never invoke themselves, but these look good.
> diff --git a/help.c b/help.c
> index d04542d8261..f1e090a4428 100644
> --- a/help.c
> +++ b/help.c
> @@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)
> struct strbuf buf = STRBUF_INIT;
> int build_options = 0;
> const char * const usage[] = {
> - N_("git version [<options>]"),
> + N_("git version [--build-options]"),
> NULL
> };
> struct option options[] = {
OK.
^ permalink raw reply [flat|nested] 230+ messages in thread* Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels
2022-10-01 18:43 ` Junio C Hamano
@ 2022-10-01 23:44 ` Junio C Hamano
2022-10-02 4:52 ` Junio C Hamano
2022-10-04 10:13 ` Ævar Arnfjörð Bjarmason
1 sibling, 1 reply; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 23:44 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Instead of going over the patches in the rest of the series, I think
we'd probably need to step back a bit and give ourselves a general
guideline.
This list is a draft of things I have learned from reading the
series, many of them from this step 21/36 alone, but some are from
earlier steps. I think the ones with '*' in front of them are not
controversial, but others are merely my suggestions at this point:
* Use of spaces in optional [] and choose-from-one, both for
freestanding token and for a value (i.e. what immediately follows
an equal sign '='), are as specified in [PATCH 1/36].
* For a command "git cmd", the documentation in the SYNOPSIS
section and the usage string from "git cmd -h" ought to match.
Let's call them simply a "usage string".
* The usage string for a command that has majorly different
operating modes can and should enumerate the different forms
separately (cf. how "git diff -h" lists different modes).
* The usage string for a command with a large number of options can
and should use "[<options>]" placeholder in the SYNOPSIS and
"usage:" lines, i.e. "git cmd [<options>]", and let the
DESCRIPTION section (in documentation) and the option listing (in
the output from usage_with_options() function).
+ The usage string for a command with a small number of options can
enumerate individual options as long as the result (for each
operating modes) can fit on a single line.
+ When a usage string shows options individually (instead of using
[<options>] placeholder and leaving the listing to the latter
half of usage_with_options()):
- if an option has both long and short forms, only long form can
and should be shown if the resulting line would become overly
long with both listed as choices.
do : "git cmd [--quiet] [--verbose] [--dry-run] <pathspec>"
don't: "git cmd [--quiet | -q] [--verbose | -v] [--dry-run | -n] <pathspec>"
- when showing a Boolean option, show only the form that
countermands the default, unless the command can take a
different default depending on the context. When use of other
options or configuration can change the default value, show the
option as "--[no-]option".
do : "git pack-refs [--all] [--no-prune]"
don't: "git pack-refs [--[no-]all] [--[no-]prune]"
- when showing an option that can be given multiple times that
causes cumulative effect (as opposed to the "last one wins"),
signal that by saying "--option..." to signal that it is
meaningful to have one or more of them.
^ permalink raw reply [flat|nested] 230+ messages in thread* Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels
2022-10-01 23:44 ` Junio C Hamano
@ 2022-10-02 4:52 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-02 4:52 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Junio C Hamano <gitster@pobox.com> writes:
> Instead of going over the patches in the rest of the series, I think
> we'd probably need to step back a bit and give ourselves a general
> guideline.
Having said that, I am a bit torn on the next step.
The updates done in this series stops way short to make the usage
strings conform to the proposed guideline. We could include such
changes to make them conform, but that would make the series that is
already long even longer, which is not what I want to see.
My preference is to go in the other direction, i.e. make NO attempt
to improve usage strings in this series, the only change we will
make would be, except for documenting the coding guideline and
adding tests that ensure usage strings in the code and in the
document match for majority of commands, are to make sure the code
and the doc match (IOW, if an existing option is not described in
either, we leave it to a later round to add it, as long as the code
and the doc consistently fail to describe it). That may allow us to
make this series shorter than it currently is, hopefully? I dunno.
And a fix to the proposed guideline.
> * The usage string for a command with a large number of options can
> and should use "[<options>]" placeholder in the SYNOPSIS and
> "usage:" lines, i.e. "git cmd [<options>]", and let the
> DESCRIPTION section (in documentation) and the option listing (in
> the output from usage_with_options() function).
"... list and explain them" is missing from the end.
^ permalink raw reply [flat|nested] 230+ messages in thread
* Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels
2022-10-01 18:43 ` Junio C Hamano
2022-10-01 23:44 ` Junio C Hamano
@ 2022-10-04 10:13 ` Ævar Arnfjörð Bjarmason
1 sibling, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 10:13 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
On Sat, Oct 01 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> [...]
>> diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
>> index 969bb2e15f1..4e6bf44427f 100644
>> --- a/Documentation/git-update-server-info.txt
>> +++ b/Documentation/git-update-server-info.txt
>> @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
>> SYNOPSIS
>> --------
>> [verse]
>> -'git update-server-info'
>> +'git update-server-info' [-f | --force]
>>
>> DESCRIPTION
>> -----------
>> @@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
>> what references and packs the server has. This command
>> generates such auxiliary files.
>>
>> +OPTIONS
>> +-------
>> +-f::
>> +--force::
>> + Allow adding otherwise ignored files.
>
> The option help text says this:
>
> N_("update the info files from scratch"), 0),
That was a copy/paste error, thanks!
> [...]
>> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
>> index df44e5cc0d1..5d5ac038716 100644
>> --- a/builtin/ls-remote.c
>> +++ b/builtin/ls-remote.c
>> @@ -7,7 +7,7 @@
>>
>> static const char * const ls_remote_usage[] = {
>> N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
>> - " [-q | --quiet] [--exit-code] [--get-url]\n"
>> + " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
>> " [--symref] [<repository> [<refs>...]]"),
>> NULL
>> };
>
> OK.
I've triped to fix all the issues you noted above (including what I elided).
> We do not need to express that --sort=<key0> --sort=<key1>... can be
> given multiple times without triggering the usual last-one-wins? In
> the documentation, the option description can say "this option can
> be given multiple times", but here we cannot, so the best we could
> do would be [--sort=<key>...] and I wonder if that is worth it.
Yes, FWIW I've left this at an explanation in the commit message. It
should be [(--sort=<key>)...], but also far git-branch.txt etc., but
fixing everything everywhere is a much bigger change.
>> diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c
>> index cfbd5c36c76..27c2ca06acb 100644
>> --- a/builtin/pack-refs.c
>> +++ b/builtin/pack-refs.c
>> @@ -5,7 +5,7 @@
>> #include "repository.h"
>>
>> static char const * const pack_refs_usage[] = {
>> - N_("git pack-refs [<options>]"),
>> + N_("git pack-refs [--all] [--no-prune]"),
>> NULL
>> };
>
> Even though "[--[no-]all] [--[no-]prune" would be more complete, I
> do not mind listing only the side that makes it behave differently
> from the default. But if you reroll with a more complete version
> with documentation updates, I wouldn't complain at all.
For now I'm just trying to make commands consistent with their "other
side", but not all things consistent with all other things.
Having said that I really prefer when we have an "--all" as opposed to
"[--no-all | --all]", or the briefer "[--[no-]all]", it makes it clearer
that "--no-all" is the default, and that your "--all" is turning on the
non-default.
Likewise "--no-prune".
>> static const char * const cherry_pick_usage[] = {
>> - N_("git cherry-pick [<options>] <commit-ish>..."),
>> - N_("git cherry-pick <subcommand>"),
>> + N_("git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n"
>> + " [-S[<keyid>]] <commit>..."),
>> + N_("git cherry-pick (--continue | --skip | --abort | --quit)"),
>> NULL
>> };
>
> And here we see "[--edit]", which is not exactly consistent.
*Nod*, but I'll leave this, per the "not trying to make all things
consistent with everything else", it's now consistent with its own
other side.
>> diff --git a/builtin/send-pack.c b/builtin/send-pack.c
>> index 64962be0168..4c5d125fa0a 100644
>> --- a/builtin/send-pack.c
>> +++ b/builtin/send-pack.c
>> @@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {
>> N_("git send-pack [--mirror] [--dry-run] [--force]\n"
>> " [--receive-pack=<git-receive-pack>]\n"
>> " [--verbose] [--thin] [--atomic]\n"
>> + " [--[no-]signed | --signed=(true|false|if-asked)]\n"
>> " [<host>:]<directory> (--all | <ref>...)"),
>> NULL,
>> };
>
> Excellent.
>
>> diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
>> index 1b0f10225f0..50b6df78df0 100644
>> --- a/builtin/symbolic-ref.c
>> +++ b/builtin/symbolic-ref.c
>> @@ -5,8 +5,9 @@
>> #include "parse-options.h"
>>
>> static const char * const git_symbolic_ref_usage[] = {
>> - N_("git symbolic-ref [<options>] <name> [<ref>]"),
>> - N_("git symbolic-ref -d [-q] <name>"),
>> + N_("git symbolic-ref [-m <reason>] <name> <ref>"),
>> + N_("git symbolic-ref [-q] [--short] <name>"),
>> + N_("git symbolic-ref --delete [-q] <name>"),
>> NULL
>> };
>
> Why spell out --delete without allowing -d? Especially when listing
> only -q for OPT__QUIET()?
>
> git symbolic-ref (-d|--delete) [-q|--quiet] <name>
>
> would be more complete but I think the original (i.e. "-d [-q]") is
> more consistent.
I can do this if you'd like, but didn't per the above, i.e. the *.txt
uses just "symbolic-ref --delete".
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (20 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 18:45 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 23/36] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
` (15 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
For "rerere" say "pathspec" consistently, and list the subcommands in
the order that they're discussed in the "COMMANDS" section of the
documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-rerere.txt | 2 +-
builtin/rerere.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 9d0e6f53e7e..992b469270c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]
DESCRIPTION
-----------
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 12570537d37..8b7392d5b44 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]"),
NULL,
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-09-30 18:07 ` [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-01 18:45 ` Junio C Hamano
2022-10-03 9:00 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 18:45 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> For "rerere" say "pathspec" consistently, and list the subcommands in
> the order that they're discussed in the "COMMANDS" section of the
> documentation.
pathspec refers to the entire set of patterns, which consists of one
or more "pathspec element"s, so there is no need for "..." there.
Listing the commands in the order they are described does make
sense.
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-rerere.txt | 2 +-
> builtin/rerere.c | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
> index 9d0e6f53e7e..992b469270c 100644
> --- a/Documentation/git-rerere.txt
> +++ b/Documentation/git-rerere.txt
> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
> SYNOPSIS
> --------
> [verse]
> -'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
> +'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]
>
> DESCRIPTION
> -----------
> diff --git a/builtin/rerere.c b/builtin/rerere.c
> index 12570537d37..8b7392d5b44 100644
> --- a/builtin/rerere.c
> +++ b/builtin/rerere.c
> @@ -10,7 +10,7 @@
> #include "pathspec.h"
>
> static const char * const rerere_usage[] = {
> - N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
> + N_("git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]"),
> NULL,
> };
^ permalink raw reply [flat|nested] 230+ messages in thread* Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-10-01 18:45 ` Junio C Hamano
@ 2022-10-03 9:00 ` Ævar Arnfjörð Bjarmason
2022-10-03 15:55 ` Junio C Hamano
0 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-03 9:00 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
On Sat, Oct 01 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> For "rerere" say "pathspec" consistently, and list the subcommands in
>> the order that they're discussed in the "COMMANDS" section of the
>> documentation.
>
> pathspec refers to the entire set of patterns, which consists of one
> or more "pathspec element"s, so there is no need for "..." there.
Maybe I'm misreading this, but are you suggesting that whenever
"<pathspec>" appears in the text the user should understand it as
"<pathspec>...", i.e. as is the case with the special-case that is
"<options>".
I'm not opposet do that, but I really wish we could avoid further
special-cases, there's no current user of "<pathspecs>" (with an "s" for
plural.
If you're saying that "<pathspec>" now should be interpretet like that
then surely e.g.:
Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::
Should be read as supporting:
--recurse-submodules some/path some-other-path
We could say that using it in that option context is a further
special-case, but I think this way lies madness, it would mean that
e.g.:
git some-cmd [--option=<pathspec>] [-- <pathspec>]
would have "<pathspec>" mean different things in those two contexts.
We also have various examples of "<pathspec>..." meaning what it means
in the post-image here (including in one of the version of the "rerere"
docs):
Documentation/git-add.txt: [--] [<pathspec>...]
Documentation/git-commit.txt: [--] [<pathspec>...]
Documentation/git-reset.txt:'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
FWIW it should arguably be [<pathspec>...] here, but per 5d2c3b01604
(rerere forget: deprecate invocation without pathspec, 2011-03-01) it
looks as though we want to advertise the other usage.
^ permalink raw reply [flat|nested] 230+ messages in thread
* Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-10-03 9:00 ` Ævar Arnfjörð Bjarmason
@ 2022-10-03 15:55 ` Junio C Hamano
2022-10-04 7:50 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 230+ messages in thread
From: Junio C Hamano @ 2022-10-03 15:55 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> On Sat, Oct 01 2022, Junio C Hamano wrote:
>
>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>>
>>> For "rerere" say "pathspec" consistently, and list the subcommands in
>>> the order that they're discussed in the "COMMANDS" section of the
>>> documentation.
>>
>> pathspec refers to the entire set of patterns, which consists of one
>> or more "pathspec element"s, so there is no need for "..." there.
>
> Maybe I'm misreading this, but are you suggesting that whenever
> "<pathspec>" appears in the text the user should understand it as
> "<pathspec>...", i.e. as is the case with the special-case that is
> "<options>".
Not really. A <pathspec> is a set of <pathspec element>s, so
writing "<pathspec-element>..." and "<pathspec>" are equivalent.
> I'm not opposet do that, but I really wish we could avoid further
> special-cases, there's no current user of "<pathspecs>" (with an "s" for
> plural.
Presumably just like range-diff compares two ranges (which in the
normal command line syntax we would not have), some future commands
may need to take two pathspecs (that is two sets of patterns to
match paths) to do something interesting, but I do not think of
anything that does so in the current command set, so it is very good
that nobody claims to take <pathspecs> with an "s"for plural.
> Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::
>
> Should be read as supporting:
>
> --recurse-submodules some/path some-other-path
Yup, the option should support it, alternatively it could take
<path>. Or it could take multiple of these options in which case
each of them is taking a pathspec element.
^ permalink raw reply [flat|nested] 230+ messages in thread
* Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-10-03 15:55 ` Junio C Hamano
@ 2022-10-04 7:50 ` Ævar Arnfjörð Bjarmason
2022-10-05 17:20 ` Junio C Hamano
0 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 7:50 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
On Mon, Oct 03 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> On Sat, Oct 01 2022, Junio C Hamano wrote:
>>
>>> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>>>
>>>> For "rerere" say "pathspec" consistently, and list the subcommands in
>>>> the order that they're discussed in the "COMMANDS" section of the
>>>> documentation.
>>>
>>> pathspec refers to the entire set of patterns, which consists of one
>>> or more "pathspec element"s, so there is no need for "..." there.
>>
>> Maybe I'm misreading this, but are you suggesting that whenever
>> "<pathspec>" appears in the text the user should understand it as
>> "<pathspec>...", i.e. as is the case with the special-case that is
>> "<options>".
>
> Not really. A <pathspec> is a set of <pathspec element>s, so
> writing "<pathspec-element>..." and "<pathspec>" are equivalent.
So, "yes"? I.e. leaving aside "pathspec" or "pathspec-element"
"<pathspecs>" is redundant to "<pathspecs>..." in this intpreretation?
But for any given "<x>" the "<x>" is not the same as "<x>..."?
>> I'm not opposet do that, but I really wish we could avoid further
>> special-cases, there's no current user of "<pathspecs>" (with an "s" for
>> plural.
>
> Presumably just like range-diff compares two ranges (which in the
> normal command line syntax we would not have), some future commands
> may need to take two pathspecs (that is two sets of patterns to
> match paths) to do something interesting, but I do not think of
> anything that does so in the current command set, so it is very good
> that nobody claims to take <pathspecs> with an "s"for plural.
>
>> Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::
>>
>> Should be read as supporting:
>>
>> --recurse-submodules some/path some-other-path
>
> Yup, the option should support it, alternatively it could take
> <path>. Or it could take multiple of these options in which case
> each of them is taking a pathspec element.
In bourne shell syntax we're talking about the distinction between:
$ echo --opt {a,b}
--opt a b
And:
$ echo --opt={a,b}
--opt=a --opt=b
Which in the SYNOPSIS syntax are (asuming "a", and "b" are <byte>), respectively:
--opt <byte>...
And:
[--opt <byte>]...
If we maintain that for a given "<label>" that it has an implicit "..."
after it I don't see how you can distingish these two by way of
explaining how the command works via the syntax. I.e. it's possible (and
we even have some obscure code in-tree that does this) to support e.g.:
--opt a b c --opt d e f g h --opt i --opt j
Which, if (in my wordview) would be explained with this syntax:
[--opt <byte>...]...
But that's really not what we mean most of the time, we *don't* want
that "..." on the argument to "--opt", because it only takes one
argument.
^ permalink raw reply [flat|nested] 230+ messages in thread* Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
2022-10-04 7:50 ` Ævar Arnfjörð Bjarmason
@ 2022-10-05 17:20 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-05 17:20 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>> Not really. A <pathspec> is a set of <pathspec element>s, so
>> writing "<pathspec-element>..." and "<pathspec>" are equivalent.
>
> So, "yes"? I.e. leaving aside "pathspec" or "pathspec-element"
> "<pathspecs>" is redundant to "<pathspecs>..." in this intpreretation?
If you leave it aside, then the answer becomes meaningless, no?
> But for any given "<x>" the "<x>" is not the same as "<x>..."?
Correct. "<collection-of-xs>" is equivalent to "[<x>...]", but
"<x>" is not equivalent to "[<x>...]" (with or without [] around the
latter).
> But that's really not what we mean most of the time, we *don't* want
> that "..." on the argument to "--opt", because it only takes one
> argument.
Yes. So an option that takes a single pathspec element should say
as such, I would think.
But I thought that I have already said we should shrink the scope of
this series, concentrating on making -h output and doc match, while
adjusting the body text in the doc to match the phrasing used in the
SYNOPSIS updated to match -h output, so this whole thing is outside
the scope of this topic, I would say.
Thanks.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 23/36] doc txt & -h consistency: make "read-tree" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (21 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 18:48 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 24/36] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
` (14 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The C version was right to use "()" in place of "[]", let's update
the *.txt version accordingly, and furthermore list the *.c options in
the same order as the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-read-tree.txt | 2 +-
builtin/read-tree.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index b9bfdc0a319..7567955bad8 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index
SYNOPSIS
--------
[verse]
-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index b3a389e1b1f..f4cbe460b97 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)
static const char * const read_tree_usage[] = {
N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
- " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n"
" (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 23/36] doc txt & -h consistency: make "read-tree" consistent
2022-09-30 18:07 ` [PATCH v3 23/36] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-01 18:48 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 18:48 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> The C version was right to use "()" in place of "[]", let's update
Incomplete description: use () in place of [] around what?
> the *.txt version accordingly, and furthermore list the *.c options in
> the same order as the *.txt.
Good.
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-read-tree.txt | 2 +-
> builtin/read-tree.c | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> index b9bfdc0a319..7567955bad8 100644
> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index
> SYNOPSIS
> --------
> [verse]
> -'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
> +'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
> [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
> (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
>
> diff --git a/builtin/read-tree.c b/builtin/read-tree.c
> index b3a389e1b1f..f4cbe460b97 100644
> --- a/builtin/read-tree.c
> +++ b/builtin/read-tree.c
> @@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)
>
> static const char * const read_tree_usage[] = {
> N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
> - " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
> + " [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n"
> " (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
> NULL
> };
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 24/36] doc txt & -h consistency: make "bundle" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (22 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 23/36] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 18:51 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 25/36] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
` (13 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend the -h output to match that of the *.txt output, the differences
were fairly small. In the case of "[<options>]" we only have a few of
them, so let's exhaustively list them as in the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 1b08700bf9e..544c78a5f3a 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,13 +12,14 @@
*/
#define BUILTIN_BUNDLE_CREATE_USAGE \
- N_("git bundle create [<options>] <file> <git-rev-list args>")
+ N_("git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n" \
+ " [--version=<version>] <file> <git-rev-list-args>")
#define BUILTIN_BUNDLE_VERIFY_USAGE \
- N_("git bundle verify [<options>] <file>")
+ N_("git bundle verify [-q | --quiet] <file>")
#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
N_("git bundle list-heads <file> [<refname>...]")
#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
- N_("git bundle unbundle <file> [<refname>...]")
+ N_("git bundle unbundle [--progress] <file> [<refname>...]")
static char const * const builtin_bundle_usage[] = {
BUILTIN_BUNDLE_CREATE_USAGE,
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 24/36] doc txt & -h consistency: make "bundle" consistent
2022-09-30 18:07 ` [PATCH v3 24/36] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-01 18:51 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 18:51 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Amend the -h output to match that of the *.txt output, the differences
> were fairly small. In the case of "[<options>]" we only have a few of
> them, so let's exhaustively list them as in the *.txt.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> builtin/bundle.c | 7 ++++---
> 1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/builtin/bundle.c b/builtin/bundle.c
> index 1b08700bf9e..544c78a5f3a 100644
> --- a/builtin/bundle.c
> +++ b/builtin/bundle.c
> @@ -12,13 +12,14 @@
> */
>
> #define BUILTIN_BUNDLE_CREATE_USAGE \
> - N_("git bundle create [<options>] <file> <git-rev-list args>")
> + N_("git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n" \
> + " [--version=<version>] <file> <git-rev-list-args>")
This looks like getting a bit on the longer side. I think keeping
the original would be a far better option IF we can give the list of
options and their explanations like usage_with_options() does, and I
also think it would be the right thing in the longer term. As an
intermediate state before getting there, I do not think the
postimage of this patch hurts, but is one more thing we need to
maintain and get distracted. So, I dunno.
> #define BUILTIN_BUNDLE_VERIFY_USAGE \
> - N_("git bundle verify [<options>] <file>")
> + N_("git bundle verify [-q | --quiet] <file>")
> #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
> N_("git bundle list-heads <file> [<refname>...]")
> #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
> - N_("git bundle unbundle <file> [<refname>...]")
> + N_("git bundle unbundle [--progress] <file> [<refname>...]")
>
> static char const * const builtin_bundle_usage[] = {
> BUILTIN_BUNDLE_CREATE_USAGE,
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 25/36] doc txt & -h consistency: use "git foo" form, not "git-foo"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (23 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 24/36] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-01 18:59 ` Junio C Hamano
2022-09-30 18:07 ` [PATCH v3 26/36] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
` (12 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Use the "git cmd" form instead of "git-cmd" for both "git
receive-pack" and "git credential-cache--daemon".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-receive-pack.txt | 2 +-
builtin/credential-cache--daemon.c | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index eec1268b10f..92452334ac4 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <git-dir>
+'git receive-pack' <git-dir>
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index d4eb0097d24..f3c89831d4a 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [--debug] <socket-path>",
+ "git credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
{
const char * const usage[] = {
- "git credential-cache--daemon [options] <action>",
+ "git credential-cache--daemon [--debug] <socket-path>",
"",
"credential-cache--daemon is disabled in this build of Git",
NULL
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 25/36] doc txt & -h consistency: use "git foo" form, not "git-foo"
2022-09-30 18:07 ` [PATCH v3 25/36] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
@ 2022-10-01 18:59 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-01 18:59 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Use the "git cmd" form instead of "git-cmd" for both "git
> receive-pack" and "git credential-cache--daemon".
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-receive-pack.txt | 2 +-
> builtin/credential-cache--daemon.c | 4 ++--
> 2 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
> index eec1268b10f..92452334ac4 100644
> --- a/Documentation/git-receive-pack.txt
> +++ b/Documentation/git-receive-pack.txt
> @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
> SYNOPSIS
> --------
> [verse]
> -'git-receive-pack' <git-dir>
> +'git receive-pack' <git-dir>
I think this, together with git-upload-pack, was very much
intentional, at least when it was written, because it is the way we
invoked the command on the other side of the connection that goes
over the wire. I suspect git-upload-archive falls into the same
category, even though it seems to lack the dash there.
> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
This one is reasonable, on the other hand. That is how
credential-cache.c::spawn_daemon() runs it.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 26/36] doc txt & -h consistency: add missing options
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (24 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 25/36] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 27/36] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
` (11 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change those built-in commands that were attempting to exhaustively
list the options in the "-h" output to actually do so, and always
have *.txt documentation know about the exhaustive list of options.
Let's also fix the documentation and -h output for those built-in
commands where the *.txt and -h output was a mismatch of missing
options on both sides.
In the case of "interpret-trailers" fixing the missing options reveals
that the *.txt version was implicitly claiming that the command had
two operating modes, which a look at the -h version (and studying the
documentation) will show is not the case.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-commit-graph.txt | 5 ++++-
Documentation/git-interpret-trailers.txt | 5 +++--
builtin/commit-tree.c | 1 +
builtin/fsck.c | 5 ++++-
builtin/hash-object.c | 4 ++--
builtin/init-db.c | 2 ++
builtin/interpret-trailers.c | 2 +-
builtin/rm.c | 4 +++-
8 files changed, 20 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 36fe56c2c71..c8dbceba014 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -10,7 +10,10 @@ SYNOPSIS
--------
[verse]
'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]
+'git commit-graph write' [--object-dir <dir>] [--append]
+ [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
DESCRIPTION
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 6d6197cd0a4..22ff3a603e0 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages
SYNOPSIS
--------
[verse]
-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
-'git interpret-trailers' [<options>] [--parse] [<file>...]
+'git interpret-trailers' [--in-place] [--trim-empty]
+ [(--trailer <token>[(=|:)<value>])...]
+ [--parse] [<file>...]
DESCRIPTION
-----------
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index e4b85d29d56..cc8d584be2f 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,6 +15,7 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
+ N_("git commit-tree <tree> [(-p <parent>)...]"),
N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
" [(-F <file>)...] <tree>"),
NULL
diff --git a/builtin/fsck.c b/builtin/fsck.c
index f7916f06ed5..ef273321d0b 100644
--- a/builtin/fsck.c
+++ b/builtin/fsck.c
@@ -821,7 +821,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,
}
static char const * const fsck_usage[] = {
- N_("git fsck [<options>] [<object>...]"),
+ N_("git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n"
+ " [--[no-]full] [--strict] [--verbose] [--lost-found]\n"
+ " [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n"
+ " [--[no-]name-objects] [<object>...]"),
NULL
};
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index f7c16802f0c..b5063815020 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
- " [--stdin] [--] <file>..."),
- "git hash-object --stdin-paths",
+ " [--stdin [--literally]] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]"),
NULL
};
const char *type = blob_type;
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 08ba006d55e..dcaaf102eaf 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
static const char *const init_db_usage[] = {
N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--separate-git-dir <git-dir>] [--object-format=<format>]\n"
+ " [-b <branch-name> | --initial-branch=<branch-name>]\n"
" [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 4cf0cf265dc..e58627c72a9 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -15,7 +15,7 @@
static const char * const git_interpret_trailers_usage[] = {
N_("git interpret-trailers [--in-place] [--trim-empty]\n"
" [(--trailer <token>[(=|:)<value>])...]\n"
- " [<file>...]"),
+ " [--parse] [<file>...]"),
NULL
};
diff --git a/builtin/rm.c b/builtin/rm.c
index b6ba859fe42..f0d025a4e23 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -17,7 +17,9 @@
#include "pathspec.h"
static const char * const builtin_rm_usage[] = {
- N_("git rm [<options>] [--] <file>..."),
+ N_("git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n"
+ " [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 27/36] doc txt & -h consistency: make "stash" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (25 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 26/36] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 28/36] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
` (10 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend both the -h output and *.txt to match one another. In this case
the *.txt didn't list the "save" subcommand, and the "-h" was
similarly missing some commands.
Let's also convert the *.c code to use a macro definition, similar to
that used in preceding commits. This avoids duplication.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 5 ++-
builtin/stash.c | 73 ++++++++++++++++++++++++-------------
2 files changed, 52 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index ea16d2eae7c..f4bb6114d91 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -11,12 +11,15 @@ SYNOPSIS
'git stash' list [<log-options>]
'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
'git stash' drop [-q | --quiet] [<stash>]
-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
+'git stash' pop [--index] [-q | --quiet] [<stash>]
+'git stash' apply [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
[-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [<message>]
'git stash' clear
'git stash' create [<message>]
'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
diff --git a/builtin/stash.c b/builtin/stash.c
index 83c9591ea6d..bb5485b4095 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -21,72 +21,95 @@
#define INCLUDE_ALL_FILES 2
+#define BUILTIN_STASH_LIST_USAGE \
+ N_("git stash list [<log-options>]")
+#define BUILTIN_STASH_SHOW_USAGE \
+ N_("git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]")
+#define BUILTIN_STASH_DROP_USAGE \
+ N_("git stash drop [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_POP_USAGE \
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_APPLY_USAGE \
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_BRANCH_USAGE \
+ N_("git stash branch <branchname> [<stash>]")
+#define BUILTIN_STASH_STORE_USAGE \
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
+#define BUILTIN_STASH_PUSH_USAGE \
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
+ " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
+ " [--] [<pathspec>...]]")
+#define BUILTIN_STASH_SAVE_USAGE \
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [<message>]")
+#define BUILTIN_STASH_CREATE_USAGE \
+ N_("git stash create [<message>]")
+#define BUILTIN_STASH_CLEAR_USAGE \
+ "git stash clear"
+
static const char * const git_stash_usage[] = {
- N_("git stash list [<log-options>]"),
- N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q | --quiet] [<stash>]"),
- N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
- N_("git stash branch <branchname> [<stash>]"),
- "git stash clear",
- N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
- " [--] [<pathspec>...]]"),
- N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_LIST_USAGE,
+ BUILTIN_STASH_SHOW_USAGE,
+ BUILTIN_STASH_DROP_USAGE,
+ BUILTIN_STASH_POP_USAGE,
+ BUILTIN_STASH_APPLY_USAGE,
+ BUILTIN_STASH_BRANCH_USAGE,
+ BUILTIN_STASH_PUSH_USAGE,
+ BUILTIN_STASH_SAVE_USAGE,
+ BUILTIN_STASH_CLEAR_USAGE,
+ BUILTIN_STASH_CREATE_USAGE,
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_list_usage[] = {
- N_("git stash list [<options>]"),
+ BUILTIN_STASH_LIST_USAGE,
NULL
};
static const char * const git_stash_show_usage[] = {
- N_("git stash show [<options>] [<stash>]"),
+ BUILTIN_STASH_SHOW_USAGE,
NULL
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_DROP_USAGE,
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_POP_USAGE,
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_APPLY_USAGE,
NULL
};
static const char * const git_stash_branch_usage[] = {
- N_("git stash branch <branchname> [<stash>]"),
+ BUILTIN_STASH_BRANCH_USAGE,
NULL
};
static const char * const git_stash_clear_usage[] = {
- "git stash clear",
+ BUILTIN_STASH_CLEAR_USAGE,
NULL
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--] [<pathspec>...]]"),
+ BUILTIN_STASH_PUSH_USAGE,
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_SAVE_USAGE,
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 28/36] doc txt & -h consistency: make "annotate" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (26 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 27/36] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 29/36] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The cmd_blame() already detected whether it was processing "blame" or
"annotate", but it didn't adjust its usage output accordingly. Let's
do that.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-annotate.txt | 2 +-
builtin/blame.c | 21 +++++++++++++++------
2 files changed, 16 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index e44a831339d..5ae8aabe0f8 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
SYNOPSIS
--------
[verse]
-'git annotate' [<options>] <file> [<revision>]
+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>
DESCRIPTION
-----------
diff --git a/builtin/blame.c b/builtin/blame.c
index 8ec59fa2096..be9e091a86b 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -30,6 +30,7 @@
#include "tag.h"
static char blame_usage[] = N_("git blame [<options>] [<rev-opts>] [<rev>] [--] <file>");
+static char annotate_usage[] = N_("git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>");
static const char *blame_opt_usage[] = {
blame_usage,
@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {
NULL
};
+static const char *annotate_opt_usage[] = {
+ annotate_usage,
+ "",
+ N_("<rev-opts> are documented in git-rev-list(1)"),
+ NULL
+};
+
static int longest_file;
static int longest_author;
static int max_orig_digits;
@@ -899,6 +907,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
long anchor;
const int hexsz = the_hash_algo->hexsz;
long num_lines = 0;
+ const char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
setup_default_color_by_age();
git_config(git_blame_config, &output_option);
@@ -914,7 +923,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
parse_options_start(&ctx, argc, argv, prefix, options,
PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);
for (;;) {
- switch (parse_options_step(&ctx, options, blame_opt_usage)) {
+ switch (parse_options_step(&ctx, options, usage)) {
case PARSE_OPT_NON_OPTION:
case PARSE_OPT_UNKNOWN:
break;
@@ -934,7 +943,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
ctx.argv[0] = "--children";
reverse = 1;
}
- parse_revision_opt(&revs, &ctx, options, blame_opt_usage);
+ parse_revision_opt(&revs, &ctx, options, usage);
}
parse_done:
revision_opts_finish(&revs);
@@ -1040,7 +1049,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
switch (argc - dashdash_pos - 1) {
case 2: /* (1b) */
if (argc != 4)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(usage, options);
/* reorder for the new way: <rev> -- <path> */
argv[1] = argv[3];
argv[3] = argv[2];
@@ -1051,11 +1060,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
argv[argc] = NULL;
break;
default:
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(usage, options);
}
} else {
if (argc < 2)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(usage, options);
if (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */
path = add_prefix(prefix, argv[1]);
argv[1] = argv[2];
@@ -1114,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
&bottom, &top, sb.path,
the_repository->index))
usage_msg_optf(_("failed to parse -L argument '%s'"),
- blame_opt_usage, options, arg);
+ usage, options, arg);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 29/36] doc txt & -h consistency: use "[<label>...]" for "zero or more"
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (27 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 28/36] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 30/36] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Correct uses of "<label>..." where we really meant to say
"[<label>...]", i.e. the command in question taken an optional set of
"<label>". As the CodingGuidelines notes "[o]ptional parts [should be]
enclosed in square brackets".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 2 +-
builtin/clean.c | 2 +-
builtin/commit.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 3f16f200d9a..db996a15e23 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/clean.c b/builtin/clean.c
index 6f039f555b2..40ff2c578de 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]"),
NULL
};
diff --git a/builtin/commit.c b/builtin/commit.c
index fcf9c85947e..21ad4ccbf87 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {
};
static const char * const builtin_status_usage[] = {
- N_("git status [<options>] [--] <pathspec>..."),
+ N_("git status [<options>] [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 30/36] doc txt & -h consistency: make "diff-tree" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (28 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 29/36] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 31/36] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "diff-tree -h" output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-tree.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 23f58702fa0..85e8c81e594 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)
}
static const char diff_tree_usage[] =
-"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
-"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n"
+" [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\n"
+" [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 31/36] doc txt & -h consistency: make "commit" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (29 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 30/36] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 32/36] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "-h" output of "git commit" consistent with the *.txt version
by exhaustively listing the options that it takes.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/commit.c | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/builtin/commit.c b/builtin/commit.c
index 21ad4ccbf87..64f420bcbf6 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -40,7 +40,14 @@
#include "pretty.h"
static const char * const builtin_commit_usage[] = {
- N_("git commit [<options>] [--] <pathspec>..."),
+ N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\n"
+ " [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\n"
+ " [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\n"
+ " [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\n"
+ " [--date=<date>] [--cleanup=<mode>] [--[no-]status]\n"
+ " [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 32/36] reflog doc: list real subcommands up-front
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (30 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 31/36] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 33/36] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the "git reflog" documentation to exhaustively list the
subcommands it accepts in the SYNOPSIS, as opposed to leaving that for
a "[verse]" in the DESCRIPTION section. This documentation style was
added in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how
other commands which take subcommands are documented.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 0537d4645be..ec64cbff4c6 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -8,14 +8,6 @@ git-reflog - Manage reflog information
SYNOPSIS
--------
-[verse]
-'git reflog' <subcommand> <options>
-
-DESCRIPTION
------------
-The command takes various subcommands, and different options
-depending on the subcommand:
-
[verse]
'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
@@ -25,6 +17,10 @@ depending on the subcommand:
[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
'git reflog exists' <ref>
+DESCRIPTION
+-----------
+This command manages the information recorded in the reflogs.
+
Reference logs, or "reflogs", record when the tips of branches and
other references were updated in the local repository. Reflogs are
useful in various Git commands, to specify the old value of a
@@ -33,7 +29,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point
to one week ago in this local repository", and so on. See
linkgit:gitrevisions[7] for more details.
-This command manages the information recorded in the reflogs.
+The command takes various subcommands, and different options
+depending on the subcommand:
The "show" subcommand (which is also the default, in the absence of
any subcommands) shows the log of the reference provided in the
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 33/36] worktree: define subcommand -h in terms of command -h
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (31 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 32/36] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 34/36] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git worktree" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------
1 file changed, 84 insertions(+), 25 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 5bfc18e5a24..ba6846c3788 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -15,15 +15,72 @@
#include "worktree.h"
#include "quote.h"
-static const char * const worktree_usage[] = {
- N_("git worktree add [<options>] <path> [<commit-ish>]"),
- N_("git worktree list [<options>]"),
- N_("git worktree lock [<options>] <path>"),
- N_("git worktree move <worktree> <new-path>"),
- N_("git worktree prune [<options>]"),
- N_("git worktree remove [<options>] <worktree>"),
- N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <worktree>"),
+#define BUILTIN_WORKTREE_ADD_USAGE \
+ N_("git worktree add [<options>] <path> [<commit-ish>]")
+#define BUILTIN_WORKTREE_LIST_USAGE \
+ N_("git worktree list [<options>]")
+#define BUILTIN_WORKTREE_LOCK_USAGE \
+ N_("git worktree lock [<options>] <path>")
+#define BUILTIN_WORKTREE_MOVE_USAGE \
+ N_("git worktree move <worktree> <new-path>")
+#define BUILTIN_WORKTREE_PRUNE_USAGE \
+ N_("git worktree prune [<options>]")
+#define BUILTIN_WORKTREE_REMOVE_USAGE \
+ N_("git worktree remove [<options>] <worktree>")
+#define BUILTIN_WORKTREE_REPAIR_USAGE \
+ N_("git worktree repair [<path>...]")
+#define BUILTIN_WORKTREE_UNLOCK_USAGE \
+ N_("git worktree unlock <worktree>")
+
+static const char * const git_worktree_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ BUILTIN_WORKTREE_LIST_USAGE,
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_add_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ NULL,
+};
+
+static const char * const git_worktree_list_usage[] = {
+ BUILTIN_WORKTREE_LIST_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_lock_usage[] = {
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_move_usage[] = {
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_prune_usage[] = {
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_remove_usage[] = {
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_repair_usage[] = {
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_unlock_usage[] = {
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
NULL
};
@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,
+ 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_prune_usage, options);
prune_worktrees();
return 0;
}
@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)
memset(&opts, 0, sizeof(opts));
opts.checkout = 1;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);
if (!!opts.detach + !!new_branch + !!new_branch_force > 1)
die(_("options '%s', '%s', and '%s' cannot be used together"), "-b", "-B", "--detach");
if (lock_reason && !keep_locked)
@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)
opts.keep_locked = _("added with --lock");
if (ac < 1 || ac > 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_add_usage, options);
path = prefix_filename(prefix, av[0]);
branch = ac < 2 ? "HEAD" : av[1];
@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_list_usage, options);
else if (verbose && porcelain)
die(_("options '%s' and '%s' cannot be used together"), "--verbose", "--porcelain");
else if (!line_terminator && !porcelain)
@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)
};
struct worktree **worktrees, *wt;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_lock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)
struct worktree **worktrees, *wt;
int ret;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_unlock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
char *path;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_move_usage,
+ 0);
if (ac != 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_move_usage, options);
path = prefix_filename(prefix, av[1]);
strbuf_addstr(&dst, path);
@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
int ret = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_remove_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)
};
int rc = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);
p = ac > 0 ? av : self;
for (; *p; p++)
repair_worktree_at_path(*p, report_repair, &rc);
@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)
if (!prefix)
prefix = "";
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);
return fn(ac, av, prefix);
}
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 34/36] doc txt & -h consistency: make "worktree" consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (32 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 33/36] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-09-30 18:07 ` [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
37 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "worktree" -h output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index ba6846c3788..4a24d53be15 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -16,17 +16,18 @@
#include "quote.h"
#define BUILTIN_WORKTREE_ADD_USAGE \
- N_("git worktree add [<options>] <path> [<commit-ish>]")
+ N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \
+ " [-b <new-branch>] <path> [<commit-ish>]")
#define BUILTIN_WORKTREE_LIST_USAGE \
- N_("git worktree list [<options>]")
+ N_("git worktree list [-v | --porcelain [-z]]")
#define BUILTIN_WORKTREE_LOCK_USAGE \
- N_("git worktree lock [<options>] <path>")
+ N_("git worktree lock [--reason <string>] <worktree>")
#define BUILTIN_WORKTREE_MOVE_USAGE \
N_("git worktree move <worktree> <new-path>")
#define BUILTIN_WORKTREE_PRUNE_USAGE \
- N_("git worktree prune [<options>]")
+ N_("git worktree prune [-n] [-v] [--expire <expire>]")
#define BUILTIN_WORKTREE_REMOVE_USAGE \
- N_("git worktree remove [<options>] <worktree>")
+ N_("git worktree remove [-f] <worktree>")
#define BUILTIN_WORKTREE_REPAIR_USAGE \
N_("git worktree repair [<path>...]")
#define BUILTIN_WORKTREE_UNLOCK_USAGE \
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (33 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 34/36] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-02 1:25 ` Eric Sunshine
2022-09-30 18:07 ` [PATCH v3 36/36] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
There's been a lot of incremental effort to make the SYNOPSIS output
in our documentation consistent with the -h output,
e.g. cbe485298bf (git reflog [expire|delete]: make -h output
consistent with SYNOPSIS, 2022-03-17) is one recent example, but that
effort has been an uphill battle due to the lack of regression
testing.
This adds such regression testing, we can parse out the SYNOPSIS
output with "sed", and is turns out it's relatively easy to normalize
it and the "-h" output to match on another.
We now ensure that we won't have regressions when it comes to the list
of commands in "expect_help_to_match_txt" below, and in subsequent
commits we'll make more of them consistent.
The naïve parser here gets quite a few things wrong, but it doesn't
need to be perfect, just good enough that we can compare /some/ of
this help output. There's no cases where the output would match except
for the parser's stupidity, it's all cases of e.g. comparing the *.txt
to non-parse_options() output.
Since that output is wildly different than the *.txt anyway let's
leave this for now, we can fix the parser some other time, or it won't
become necessary as we'll e.g. convert more things to using
parse_options().
Having a special-case for "merge-tree"'s 1f0c3a29da3 (merge-tree:
implement real merges, 2022-06-18) is a bit ugly, but preferred to
blessing that " (deprecated)" pattern for other commands. We'd
probably want to add some other way of marking deprecated commands in
the SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is
indistinguishable from the command taking an optional literal
"deprecated" string as an argument.
Some of the issues that are left:
* "git show -h", "git whatchanged -h" and "git reflog --oneline -h"
all showing "git log" and "git show" usage output. I.e. the
"builtin_log_usage" in builtin/log.c doesn't take into account what
command we're running.
* Likewise "git stage -h" shows "git add" usage, but should be aware
of what command it's running. The same for "annotate" and "blame".
* Commands which implement subcommands such as like
"multi-pack-index", "notes", "remote" etc. having their subcommands
in a very different order in the *.txt and *.c. Fixing it would
require some verbose diffs, so it's been left alone for onw.
* Commands such as "format-patch" have a very long argument list in
the *.txt, but just "[<options>]" in the *.c.
What to do about these has been left out of this series, except to
the extent that preceding commits changed "[<options>]" (or
equivalent) to the list of options in cases where that list of
options was tiny, or we clearly meant to exhaustively list the
options in both *.txt and *.c.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 121 ++++++++++++++++++++++++++++++++++++
t/t0450/txt-help-mismatches | 58 +++++++++++++++++
2 files changed, 179 insertions(+)
create mode 100755 t/t0450-txt-doc-vs-help.sh
create mode 100644 t/t0450/txt-help-mismatches
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
new file mode 100755
index 00000000000..6a710b07408
--- /dev/null
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -0,0 +1,121 @@
+#!/bin/sh
+
+test_description='compare (unbuilt) Documentation/*.txt to -h output
+
+Run this with --debug to see a summary of where we still fail to make
+the two versions consistent with one another.'
+
+. ./test-lib.sh
+
+test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+'
+
+test_expect_success 'list of txt and help mismatches is sorted' '
+ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
+ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ BUG "please keep the list of txt and help mismatches sorted"
+ fi
+'
+
+builtin_to_synopsis () {
+ builtin="$1" &&
+ test_when_finished "rm -f out" &&
+ test_expect_code 129 git $builtin -h >out 2>&1 &&
+ sed -n \
+ -e '1,/^$/ {
+ /^$/d;
+ s/^usage: //;
+ s/^ *or: //;
+ p;
+ }' <out
+}
+
+builtin_to_txt () {
+ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
+}
+
+txt_synopsis () {
+ sed -n \
+ -e '/^\[verse\]$/,/^$/ {
+ /^$/d;
+ /^\[verse\]$/d;
+ s/{litdd}/--/g;
+
+ s/'\''\(git[ a-z-]*\)'\''/\1/g;
+ p;
+ }' \
+ <"$1"
+}
+
+HT=" "
+align_after_nl () {
+ builtin="$1" &&
+ len=$(printf "git %s " "$builtin" | wc -c) &&
+ pad=$(printf "%${len}s" "") &&
+
+ sed "s/^[ $HT][ $HT]*/$pad/"
+}
+
+test_debug '>failing'
+while read builtin
+do
+ test_expect_success "$builtin -h output has no \t" '
+ builtin_to_synopsis "$builtin" >help.raw &&
+ ! grep "$HT" help.raw
+ '
+
+ txt="$(builtin_to_txt "$builtin")" &&
+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
+
+ if test -f "$txt"
+ then
+ test_set_prereq "$preq"
+ fi &&
+
+ result=
+ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ result=failure
+ else
+ result=success
+ fi &&
+
+ test_expect_$result "$preq" "$builtin -h output and SYNOPSIS agree" '
+ txt_synopsis "$txt" >txt.raw &&
+ if test "$builtin" = "merge-tree"
+ then
+ sed -e '\''s/ (deprecated)$//g'\'' <txt.raw >txt.raw.new &&
+ mv txt.raw.new txt.raw
+ fi &&
+ builtin_to_synopsis "$builtin" >help.raw &&
+
+ # The *.txt and -h use different spacing for the
+ # alignment of continued usage output, normalize it.
+ align_after_nl "$builtin" <txt.raw >txt &&
+ align_after_nl "$builtin" <help.raw >help &&
+ test_cmp txt help
+ '
+
+ if test_have_prereq "$preq" && test -e txt && test -e help
+ then
+ test_debug '
+ if test_cmp txt help >cmp 2>/dev/null
+ then
+ echo "=== DONE: $builtin ==="
+ else
+ echo "=== TODO: $builtin ===" &&
+ cat cmp
+ fi >>failing
+ '
+
+ # Not in test_expect_success in case --run is being
+ # used with --debug
+ rm -f txt help tmp 2>/dev/null
+ fi
+done <builtins
+
+test_debug 'say "$(cat failing)"'
+
+test_done
diff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches
new file mode 100644
index 00000000000..a0777acd667
--- /dev/null
+++ b/t/t0450/txt-help-mismatches
@@ -0,0 +1,58 @@
+add
+am
+apply
+archive
+bisect
+blame
+branch
+check-ref-format
+checkout
+checkout-index
+clone
+column
+config
+credential
+credential-cache
+credential-store
+fast-export
+fast-import
+fetch-pack
+fmt-merge-msg
+for-each-ref
+format-patch
+fsck-objects
+fsmonitor--daemon
+gc
+grep
+index-pack
+init-db
+log
+ls-files
+ls-tree
+mailinfo
+mailsplit
+maintenance
+merge
+merge-file
+merge-index
+merge-one-file
+multi-pack-index
+name-rev
+notes
+pack-objects
+push
+range-diff
+rebase
+remote
+remote-ext
+remote-fd
+repack
+reset
+restore
+rev-parse
+show
+stage
+switch
+update-index
+update-ref
+whatchanged
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output
2022-09-30 18:07 ` [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
@ 2022-10-02 1:25 ` Eric Sunshine
0 siblings, 0 replies; 230+ messages in thread
From: Eric Sunshine @ 2022-10-02 1:25 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: Git List, Junio C Hamano, Victoria Dye, Taylor Blau,
Emily Shaffer, Jonathan Nieder, John Cai
On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> There's been a lot of incremental effort to make the SYNOPSIS output
> in our documentation consistent with the -h output,
> e.g. cbe485298bf (git reflog [expire|delete]: make -h output
> consistent with SYNOPSIS, 2022-03-17) is one recent example, but that
> effort has been an uphill battle due to the lack of regression
> testing.
>
> This adds such regression testing, we can parse out the SYNOPSIS
> output with "sed", and is turns out it's relatively easy to normalize
s/is/it/
> it and the "-h" output to match on another.
>
> Some of the issues that are left:
>
> * "git show -h", "git whatchanged -h" and "git reflog --oneline -h"
> all showing "git log" and "git show" usage output. I.e. the
> "builtin_log_usage" in builtin/log.c doesn't take into account what
> command we're running.
>
> * Likewise "git stage -h" shows "git add" usage, but should be aware
> of what command it's running. The same for "annotate" and "blame".
Is this mention of annotate/blame out of date? Doesn't [28/36] make
these commands emit the correct usage text? Or am I misunderstanding
what this is saying?
> * Commands which implement subcommands such as like
> "multi-pack-index", "notes", "remote" etc. having their subcommands
> in a very different order in the *.txt and *.c. Fixing it would
> require some verbose diffs, so it's been left alone for onw.
s/onw/now/
> * Commands such as "format-patch" have a very long argument list in
> the *.txt, but just "[<options>]" in the *.c.
>
> What to do about these has been left out of this series, except to
> the extent that preceding commits changed "[<options>]" (or
> equivalent) to the list of options in cases where that list of
> options was tiny, or we clearly meant to exhaustively list the
> options in both *.txt and *.c.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 36/36] tests: assert consistent whitespace in -h output
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (34 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
@ 2022-09-30 18:07 ` Ævar Arnfjörð Bjarmason
2022-10-02 1:29 ` Eric Sunshine
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
37 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-30 18:07 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test for the *.txt and *.c output assertions which asserts that
for "-h" lines that aren't the "usage: " or " or: " lines they start
with the same amount of whitespace. This ensures that we won't have
buggy output like:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
Which should instead be like this instead, i.e. the options lines
should be aligned:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
It would be better to be able to use "test_cmp" here, i.e. to
construct the output we expect, and compare it against the actual
output.
For most built-in commands this would be rather straightforward. In
"t0450-txt-doc-vs-help.sh" we already compute the whitespace that a
"git-$builtin" needs, and strip away "usage: " or " or: " from the
start of lines. The problem is:
* For commands that implement subcommands, such as "git bundle", we
don't know whether e.g. "git bundle create" is the subcommand
"create", or the argument "create" to "bundle" for the purposes of
alignment.
We *do* have that information from the *.txt version, since the
part within the ''-quotes should be the command & subcommand, but
that isn't consistent (e.g. see "git bundle" and "git
commit-graph", only the latter is correct), and parsing that out
would be non-trivial.
* If we were to make this stricter we have various
non-parse_options() users (e.g. "git diff-tree") that don't have the
nicely aligned output which we've had since
4631cfc20bd (parse-options: properly align continued usage output,
2021-09-21).
So rather than make perfect the enemy of the good let's assert that
for those lines that are indented they should all use the same
indentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 6a710b07408..adc81ec590b 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -66,6 +66,21 @@ do
! grep "$HT" help.raw
'
+ test_expect_success "$builtin -h output has consistent spacing" '
+ builtin_to_synopsis "$builtin" >help.raw &&
+ sed -n \
+ -e "/^ / {
+ s/[^ ].*//;
+ p;
+ }" \
+ <help.raw >help &&
+ sort -u help >help.ws &&
+ if test -s help.ws
+ then
+ test_line_count = 1 help.ws
+ fi
+ '
+
txt="$(builtin_to_txt "$builtin")" &&
preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v3 36/36] tests: assert consistent whitespace in -h output
2022-09-30 18:07 ` [PATCH v3 36/36] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
@ 2022-10-02 1:29 ` Eric Sunshine
0 siblings, 0 replies; 230+ messages in thread
From: Eric Sunshine @ 2022-10-02 1:29 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: Git List, Junio C Hamano, Victoria Dye, Taylor Blau,
Emily Shaffer, Jonathan Nieder, John Cai
On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> Add a test for the *.txt and *.c output assertions which asserts that
> for "-h" lines that aren't the "usage: " or " or: " lines they start
> with the same amount of whitespace. This ensures that we won't have
> buggy output like:
>
> [...]
> or: git tag [-n[<num>]]
> [...]
> [--create-reflog] [...]
>
> Which should instead be like this instead, i.e. the options lines
> should be aligned:
Too many "instead"s.
> [...]
> or: git tag [-n[<num>]]
> [...]
> [--create-reflog] [...]
>
> It would be better to be able to use "test_cmp" here, i.e. to
> construct the output we expect, and compare it against the actual
> output.
>
> For most built-in commands this would be rather straightforward. In
> "t0450-txt-doc-vs-help.sh" we already compute the whitespace that a
> "git-$builtin" needs, and strip away "usage: " or " or: " from the
> start of lines. The problem is:
>
> * For commands that implement subcommands, such as "git bundle", we
> don't know whether e.g. "git bundle create" is the subcommand
> "create", or the argument "create" to "bundle" for the purposes of
> alignment.
>
> We *do* have that information from the *.txt version, since the
> part within the ''-quotes should be the command & subcommand, but
> that isn't consistent (e.g. see "git bundle" and "git
> commit-graph", only the latter is correct), and parsing that out
> would be non-trivial.
>
> * If we were to make this stricter we have various
> non-parse_options() users (e.g. "git diff-tree") that don't have the
> nicely aligned output which we've had since
> 4631cfc20bd (parse-options: properly align continued usage output,
> 2021-09-21).
>
> So rather than make perfect the enemy of the good let's assert that
> for those lines that are indented they should all use the same
> indentation.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v3 00/34] doc/UX: make txt & -h output more consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (35 preceding siblings ...)
2022-09-30 18:07 ` [PATCH v3 36/36] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:20 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
` (3 more replies)
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
37 siblings, 4 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
We are currently wildly inconsistent in whether the SYNOPSIS in the
manual page matches the first line of the -h output, and as we add new
options we routinely forget to add them to one or the other (or both).
Without a more complex approach it's hard to do something about the
"or both" case. But we can rather easily test whether the -h output
matches the *.txt version, and report differences.
As this series shows that allows us to fix a lot of issues we've
effectively already "fixed", we just fixed them in one version, but
not the other.
For the rest of the general overview (the first paragraphs are
copy/pasted) see the v1 at:
https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/ [1];
For v3 see:
http://lore.kernel.org/git/cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com
Changes since v3:
* Added a commit to put a small portion of the the new tests first,
we then add a bit to it as we go along.
* Squashed some changes as requested, now some of the "doc txt & -h
consistency" commits have changes that were previously split up,
but that's noted in the commit message.
* Ejected the "blame" usage_msg_optf() change, instead the relevant
later commit just supports both usage() and usage_with_options().
* Consistently use [<options>], not "[<options...]"
* Various squshes/fix-ups suggested by Eric & Junio, thanks both!
* The new test now runs much faster, since we cache the "sed"
commands that extract the "-h" and "*.txt" output
Ævar Arnfjörð Bjarmason (34):
tests: assert *.txt SYNOPSIS and -h output
CodingGuidelines: update and clarify command-line conventions
builtin/bundle.c: indent with tabs
bundle: define subcommand -h in terms of command -h
doc SYNOPSIS: don't use ' for subcommands
doc SYNOPSIS: consistently use ' for commands
built-ins: consistently add "\n" between "usage" and options
doc txt & -h consistency: word-wrap
doc txt & -h consistency: fix incorrect alternates syntax
doc txt & -h consistency: add "-z" to cat-file "-h"
doc txt & -h consistency: balance unbalanced "[" and "]"
doc txt & -h consistency: correct padding around "[]()"
stash doc SYNOPSIS & -h: correct padding around "[]()"
doc txt & -h consistency: use "<options>", not "<options>..."
doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
doc txt & -h consistency: fix mismatching labels
doc txt & -h consistency: add or fix optional "--" syntax
doc txt & -h consistency: make output order consistent
doc txt & -h consistency: add missing options and labels
doc txt & -h consistency: make "rerere" consistent
doc txt & -h consistency: make "read-tree" consistent
doc txt & -h consistency: make "bundle" consistent
doc txt & -h consistency: use "git foo" form, not "git-foo"
doc txt & -h consistency: add missing options
doc txt & -h consistency: make "stash" consistent
doc txt & -h consistency: make "annotate" consistent
doc txt & -h consistency: use "[<label>...]" for "zero or more"
doc txt & -h consistency: make "diff-tree" consistent
doc txt & -h consistency: make "commit" consistent
reflog doc: list real subcommands up-front
worktree: define subcommand -h in terms of command -h
doc txt & -h consistency: make "worktree" consistent
tests: start asserting that *.txt SYNOPSIS matches -h output
tests: assert consistent whitespace in -h output
Documentation/CodingGuidelines | 14 +-
Documentation/git-annotate.txt | 2 +-
Documentation/git-clean.txt | 8 +-
Documentation/git-commit-graph.txt | 5 +-
.../git-credential-cache--daemon.txt | 4 +-
Documentation/git-diff-files.txt | 2 +-
Documentation/git-fast-export.txt | 2 +-
Documentation/git-hash-object.txt | 3 +-
Documentation/git-interpret-trailers.txt | 5 +-
Documentation/git-merge-base.txt | 4 +-
Documentation/git-mv.txt | 4 +-
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-read-tree.txt | 2 +-
Documentation/git-receive-pack.txt | 4 +-
Documentation/git-reflog.txt | 17 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-rev-list.txt | 2 +-
Documentation/git-send-pack.txt | 5 +-
Documentation/git-show-branch.txt | 4 +-
Documentation/git-show-ref.txt | 4 +-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-stash.txt | 17 +-
Documentation/git-status.txt | 2 +-
Documentation/git-tag.txt | 18 +-
Documentation/git-update-server-info.txt | 8 +-
Documentation/git-upload-archive.txt | 4 +-
Documentation/git-var.txt | 2 +-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
Documentation/git-worktree.txt | 3 +-
builtin/blame.c | 22 ++-
builtin/bugreport.c | 3 +-
builtin/bundle.c | 38 ++--
builtin/cat-file.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 10 +-
builtin/commit-tree.c | 5 +-
builtin/commit.c | 11 +-
builtin/credential-cache--daemon.c | 4 +-
builtin/describe.c | 5 +-
builtin/diagnose.c | 3 +-
builtin/diff-files.c | 1 +
builtin/diff-index.c | 3 +-
builtin/diff-tree.c | 6 +-
builtin/diff.c | 3 +-
builtin/for-each-repo.c | 2 +-
builtin/fsck.c | 5 +-
builtin/hash-object.c | 5 +-
builtin/help.c | 2 +-
builtin/init-db.c | 5 +-
builtin/interpret-trailers.c | 4 +-
builtin/ls-remote.c | 2 +-
builtin/merge-base.c | 2 +-
builtin/pack-objects.c | 4 +-
builtin/pack-redundant.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/read-tree.c | 4 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 3 +-
builtin/revert.c | 9 +-
builtin/rm.c | 4 +-
builtin/send-pack.c | 1 +
builtin/show-branch.c | 3 +-
builtin/show-ref.c | 4 +-
builtin/sparse-checkout.c | 2 +-
builtin/stash.c | 73 +++++---
builtin/symbolic-ref.c | 5 +-
builtin/tag.c | 10 +-
builtin/unpack-file.c | 2 +-
builtin/update-server-info.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/upload-pack.c | 3 +-
builtin/verify-commit.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/verify-tag.c | 2 +-
builtin/worktree.c | 110 ++++++++---
help.c | 2 +-
t/helper/test-proc-receive.c | 2 +-
t/t0450-txt-doc-vs-help.sh | 172 ++++++++++++++++++
t/t0450/txt-help-mismatches | 58 ++++++
82 files changed, 593 insertions(+), 198 deletions(-)
create mode 100755 t/t0450-txt-doc-vs-help.sh
create mode 100644 t/t0450/txt-help-mismatches
Range-diff against v2:
-: ----------- > 1: f76804fe9ae tests: assert *.txt SYNOPSIS and -h output
1: 1611913e321 = 2: c95d3b9ad42 CodingGuidelines: update and clarify command-line conventions
2: b2d76494a34 = 3: b7c98a40393 builtin/bundle.c: indent with tabs
3: 953a72abee1 = 4: 522d7fbb0a3 bundle: define subcommand -h in terms of command -h
4: a8312c50f01 < -: ----------- blame: use a more detailed usage_msg_optf() error on bad -L
5: ec977f7c8fe = 5: ac437d4eee5 doc SYNOPSIS: don't use ' for subcommands
6: b0ae035500c = 6: f20cbb661c6 doc SYNOPSIS: consistently use ' for commands
8: e9924890620 = 7: ecdc14f6dfe built-ins: consistently add "\n" between "usage" and options
10: 1a02f7c76cd ! 8: 1b9b6a91916 doc txt & -h consistency: word-wrap
@@ Commit message
doc txt & -h consistency: word-wrap
Change the documentation and -h output for those built-in commands
- where the *.txt and -h output didn't match as far as word-wrapping was
- concerned.
+ where both the -h output and *.txt were lacking in word-wrapping.
+
+ There are many more built-ins that could use this treatment, this
+ change is narrowed to those where this whitespace change is needed to
+ make the -h and *.txt consistent in the end.
+
+ In the case of "Documentation/git-hash-object.txt" and
+ "builtin/hash-object.c" this is not a "doc txt & -h consistency"
+ change, as we're changing both versions, doing so here makes a
+ subsequent change smaller.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+ ## Documentation/git-hash-object.txt ##
+@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file
+ SYNOPSIS
+ --------
+ [verse]
+-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
++'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
++ [--stdin [--literally]] [--] <file>...
+ 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
+
+ DESCRIPTION
+
## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees
SYNOPSIS
@@ builtin/diagnose.c
};
+ ## builtin/hash-object.c ##
+@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
+ int cmd_hash_object(int argc, const char **argv, const char *prefix)
+ {
+ static const char * const hash_object_usage[] = {
+- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
++ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
++ " [--stdin] [--] <file>..."),
+ "git hash-object --stdin-paths",
+ NULL
+ };
+
## builtin/init-db.c ##
@@ builtin/init-db.c: static int shared_callback(const struct option *opt, const char *arg, int unset)
}
7: 829bdf58499 ! 9: f4598ca1899 doc SYNOPSIS & -h: fix incorrect alternates syntax
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- doc SYNOPSIS & -h: fix incorrect alternates syntax
+ doc txt & -h consistency: fix incorrect alternates syntax
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
- This issue has been with us in both the "-h" and *.txt versions since
- bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
+ This syntax issue for "bugreport" originated in
+ 238b439d698 (bugreport: add tool to generate debugging info,
+ 2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
+ create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
+ "bugreport" documentation and code.
- There are also issues with the alternates syntax for "bugreport" and
- "diagnose", but in those cases only for one of *.c or *.txt, not
- both. Those issues will be fixed in a subsequent "consistency" commit.
+ In the case of "Documentation/git-stash.txt" and "builtin/stash.c"
+ this is not a "doc txt & -h consistency" change, as we're changing
+ both versions, doing so here makes a subsequent change smaller.
+
+ In that case fix the incorrect "[-o | --option <argument>]" syntax,
+ which should be "[(-o | --option) <argument>]", we were previously
+ claiming that only the long option accepted the "<argument>", which
+ isn't what we meant.
+
+ The "stash" issue has been with us in both the "-h" and *.txt versions
+ since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
+
+ We could claim that this isn't a syntax issue if a "vertical bar binds
+ tighter than option and its argument", but such a rule would change
+ e.g. this "cat-file" SYNOPSIS example to mean something we don't:
+
+ ... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
+
+ We have various other examples where the post-image here is already
+ used, e.g. for "format-patch" ("-o"), "grep" ("-m"),
+ "submodule" ("set-branch -b") etc.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-stash.txt: stash index (e.g. the integer `n` is equivalent to
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
+ ## builtin/bugreport.c ##
+@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, int nongit)
+ }
+
+ static const char * const bugreport_usage[] = {
+- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
++ N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
+ " [--diagnose[=<mode>]"),
+ NULL
+ };
+
+ ## builtin/diagnose.c ##
+@@
+ #include "diagnose.h"
+
+ static const char * const diagnose_usage[] = {
+- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
++ N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
+ " [--mode=<mode>]"),
+ NULL
+ };
+
## builtin/stash.c ##
@@ builtin/stash.c: static const char * const git_stash_usage[] = {
N_("git stash branch <branchname> [<stash>]"),
9: 516af07e8a8 < -: ----------- doc SYNOPSIS & -h: word-wrap
11: 7794c3d6ef5 < -: ----------- doc txt & -h consistency: fix incorrect alternates syntax
12: 357a228000c = 10: 0e955f294cd doc txt & -h consistency: add "-z" to cat-file "-h"
13: 57cbaee9826 = 11: aa2f9325839 doc txt & -h consistency: balance unbalanced "[" and "]"
14: a29af2dcc4f = 12: 009a0e586e9 doc txt & -h consistency: correct padding around "[]()"
15: 589705cf6fa = 13: b568189532f stash doc SYNOPSIS & -h: correct padding around "[]()"
16: db850539d2a ! 14: e5cb5c91b82 doc txt & -h consistency: use "<options>", not "<options>..."
@@ Commit message
In the case of "mv" and "sparse-checkout" let's add the missing "[]"
to indicate that these are optional.
+ In the case of "t/helper/test-proc-receive.c" there is no *.txt
+ version, making it the only hunk in this commit that's not a "doc txt
+ & -h consistency" change.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-mv.txt ##
@@ builtin/sparse-checkout.c
NULL
};
+
+ ## t/helper/test-proc-receive.c ##
+@@
+ #include "test-tool.h"
+
+ static const char *proc_receive_usage[] = {
+- "test-tool proc-receive [<options>...]",
++ "test-tool proc-receive [<options>]",
+ NULL
+ };
+
17: 041aa64f3c7 ! 15: 403e7ceb449 t/helper/test-proc-receive.c: use "<options>", not "<options>..."
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- t/helper/test-proc-receive.c: use "<options>", not "<options>..."
+ doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
- As in a preceding commit use "<options>", not "<options>...", in this
- case there is no *.txt version, but let's fix this one too while we're
- at it.
+ Change "builtin/credential-cache--daemon.c" to use "<socket-path>" not
+ "<socket_path>" in a placeholder label, almost all of our
+ documentation uses this form.
+
+ This is now consistent with the "If a placeholder has multiple words,
+ they are separated by dashes" guideline added in
+ 9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's
+ add a now-passing test to assert that that's the case.
+
+ To do this we need to introduce a very sed-powered parser to extract
+ the SYNOPSIS from the *.txt, and handle not all commands with "-h"
+ having a corresponding *.txt (e.g. "bisect--helper"). We'll still want
+ to handle syntax edge cases in the *.txt in subsequent commits for
+ other checks, but let's do that then.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## t/helper/test-proc-receive.c ##
-@@
- #include "test-tool.h"
+ ## builtin/credential-cache--daemon.c ##
+@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
+ const char *socket_path;
+ int ignore_sighup = 0;
+ static const char *usage[] = {
+- "git-credential-cache--daemon [opts] <socket_path>",
++ "git-credential-cache--daemon [opts] <socket-path>",
+ NULL
+ };
+ int debug = 0;
+
+ ## t/t0450-txt-doc-vs-help.sh ##
+@@ t/t0450-txt-doc-vs-help.sh: help_to_synopsis () {
+ echo "$out"
+ }
+
++builtin_to_txt () {
++ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
++}
++
++txt_to_synopsis () {
++ builtin="$1" &&
++ out_dir="out/$builtin" &&
++ out="$out_dir/txt.synopsis" &&
++ if test -f "$out"
++ then
++ echo "$out" &&
++ return 0
++ fi &&
++ b2t="$(builtin_to_txt "$builtin")" &&
++ sed -n \
++ -e '/^\[verse\]$/,/^$/ {
++ /^$/d;
++ /^\[verse\]$/d;
++
++ p;
++ }' \
++ <"$b2t" >"$out" &&
++ echo "$out"
++}
++
++check_dashed_labels () {
++ ! grep -E "<[^>_-]+_" "$1"
++}
++
+ HT=" "
- static const char *proc_receive_usage[] = {
-- "test-tool proc-receive [<options>...]",
-+ "test-tool proc-receive [<options>]",
- NULL
- };
+ while read builtin
+@@ t/t0450-txt-doc-vs-help.sh: do
+ h2s="$(help_to_synopsis "$builtin")" &&
+ ! grep "$HT" "$h2s"
+ '
++
++ test_expect_success "$builtin -h output has dashed labels" '
++ check_dashed_labels "$(help_to_synopsis "$builtin")"
++ '
++
++ txt="$(builtin_to_txt "$builtin")" &&
++ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
++
++ if test -f "$txt"
++ then
++ test_set_prereq "$preq"
++ fi &&
++
++ # *.txt output assertions
++ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
++ check_dashed_labels "$(txt_to_synopsis "$builtin")"
++ '
+ done <builtins
+ test_done
18: 3a439c4401d ! 16: 563ccaab6a9 doc txt & -h consistency: fix mismatching labels
@@ Commit message
corresponding -h output where our translatable labels didn't match
up.
+ In some cases we need to adjust the prose that follows the SYNOPSIS
+ accordingly, as it refers back to the changed label.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-clean.txt ##
@@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
+-are affected.
+If any optional `<pathspec>...` arguments are given, only those paths
- are affected.
++that match the pathspec are affected.
OPTIONS
-------
@@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - T
DESCRIPTION
-----------
+@@ Documentation/git-credential-cache--daemon.txt: DESCRIPTION
+ NOTE: You probably don't want to invoke this command yourself; it is
+ started automatically when you use linkgit:git-credential-cache[1].
+
+-This command listens on the Unix domain socket specified by `<socket>`
++This command listens on the Unix domain socket specified by `<socket-path>`
+ for `git-credential-cache` clients. Clients may store and retrieve
+ credentials. Each credential is held for a timeout specified by the
+ client; once no credentials are held, the daemon exits.
## Documentation/git-mv.txt ##
@@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a symlink
@@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a syml
DESCRIPTION
-----------
+@@ Documentation/git-mv.txt: OPTIONS
+ -------
+ -f::
+ --force::
+- Force renaming or moving of a file even if the target exists
++ Force renaming or moving of a file even if the <destination> exists.
+ -k::
+ Skip move or rename actions which would lead to an error
+ condition. An error happens when a source is neither existing nor
## Documentation/git-receive-pack.txt ##
@@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed into the repository
@@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed in
DESCRIPTION
-----------
+@@ Documentation/git-receive-pack.txt: its behavior, see linkgit:git-config[1].
+
+ OPTIONS
+ -------
+-<directory>::
++<git-dir>::
+ The repository to sync into.
+
+ --http-backend-info-refs::
## Documentation/git-tag.txt ##
@@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object signed with GPG
@@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
+@@ Documentation/git-tag.txt: to delete, list or verify tags.
+
+ Unless `-f` is given, the named tag must not yet exist.
+
+-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
++If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
+ creates a 'tag' object, and requires a tag message. Unless
+ `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
+ in the tag message.
+
+-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
++If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
+ are absent, `-a` is implied.
+
+ Otherwise, a tag reference that points directly at the given object
+ (i.e., a lightweight tag) is created.
+
+ A GnuPG signed tag object will be created when `-s` or `-u
+-<keyid>` is used. When `-u <keyid>` is not used, the
++<key-id>` is used. When `-u <key-id>` is not used, the
+ committer identity for the current user is used to find the
+ GnuPG key for signing. The configuration variable `gpg.program`
+ is used to specify custom GnuPG binary.
+@@ Documentation/git-tag.txt: OPTIONS
+ Override `tag.gpgSign` configuration variable that is
+ set to force each and every tag to be signed.
+
+--u <keyid>::
+---local-user=<keyid>::
++-u <key-id>::
++--local-user=<key-id>::
+ Make a GPG-signed tag, using the given key.
+
+ -f::
+@@ Documentation/git-tag.txt: This option is only applicable when listing tags without annotation lines.
+ Use the given tag message (instead of prompting).
+ If multiple `-m` options are given, their values are
+ concatenated as separate paragraphs.
+- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
++ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ is given.
+
+ -F <file>::
+ --file=<file>::
+ Take the tag message from the given file. Use '-' to
+ read the message from the standard input.
+- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
++ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ is given.
+
+ -e::
+@@ Documentation/git-tag.txt: it in the repository configuration as follows:
+
+ -------------------------------------
+ [user]
+- signingKey = <gpg-keyid>
++ signingKey = <gpg-key_id>
+ -------------------------------------
+
+ `pager.tag` is only respected when listing tags, i.e., when `-l` is
## Documentation/git-upload-archive.txt ##
@@ Documentation/git-upload-archive.txt: git-upload-archive - Send archive back to git-archive
@@ builtin/commit-graph.c
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
- ## builtin/credential-cache--daemon.c ##
-@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
- const char *socket_path;
- int ignore_sighup = 0;
- static const char *usage[] = {
-- "git-credential-cache--daemon [opts] <socket_path>",
-+ "git-credential-cache--daemon [opts] <socket-path>",
- NULL
- };
- int debug = 0;
-
## builtin/for-each-repo.c ##
@@
#include "string-list.h"
19: 3bfdd3fb79e ! 17: e6ef67f1c4f doc txt & -h consistency: add or fix optional "--" syntax
@@ Commit message
inconsistent, or where we incorrectly stated in one but not the other
that the "--" was mandatory.
+ In the case of "rev-list" both sides were wrong, as we we don't
+ require one or more paths if "--" is used, e.g. this is OK:
+
+ git rev-list HEAD --
+
+ That part of this change is not a "doc txt & -h consistency" change,
+ as we're changing both versions, doing so here makes both sides
+ consistent.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+ ## Documentation/git-rev-list.txt ##
+@@ Documentation/git-rev-list.txt: git-rev-list - Lists commit objects in reverse chronological order
+ SYNOPSIS
+ --------
+ [verse]
+-'git rev-list' [<options>] <commit>... [[--] <path>...]
++'git rev-list' [<options>] <commit>... [--] [<path>...]
+
+ DESCRIPTION
+ -----------
+
## builtin/for-each-repo.c ##
@@
#include "string-list.h"
@@ builtin/rev-list.c
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit>... [-- <path>...]\n"
-+"git rev-list [<options>] <commit>... [[--] <path>...]\n"
++"git rev-list [<options>] <commit>... [--] [<path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
20: 98bdd0353cf = 18: 766bafcde05 doc txt & -h consistency: make output order consistent
21: 1713227d497 ! 19: fb95d7a9f86 doc txt & -h consistency: add missing options and labels
@@ Commit message
* We said "opts" or "options", but could instead enumerate
the (small) set of supported options
- * argument labels were missing entirely (ls-remote)
+ * Options that were missing entirely (ls-remote's --sort=<key>)
- * How we referred to an argument was inconsistent between the two,
- e.g. <pack> v.s. <pack>.idx.
+ As we can specify "--sort" multiple times (it's backed by a
+ string-list" it should really be "[(--sort=<key>)...]", which is
+ what "git for-each-ref" lists it as, but let's leave that issue for
+ a subsequent cleanup, and stop at making these consistent. Other
+ "ref-filter.h" users share the same issue, e.g. "git-branch.txt".
+
+ * For "verify-tag" and "verify-commit" we were missing the "--raw"
+ option.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-update-server-info.txt: $GIT_OBJECT_DIRECTORY/info directories
+-------
+-f::
+--force::
-+ Allow adding otherwise ignored files.
++ update the info files from scratch.
+
OUTPUT
------
@@ Documentation/git-verify-commit.txt: git-verify-commit - Check the GPG signature
--------
[verse]
-'git verify-commit' <commit>...
-+'git verify-commit' [-v | --verbose] <commit>...
++'git verify-commit' [-v | --verbose] [--raw] <commit>...
DESCRIPTION
-----------
@@ Documentation/git-verify-tag.txt: git-verify-tag - Check the GPG signature of ta
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
-+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...
++'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
DESCRIPTION
-----------
@@ builtin/upload-pack.c
};
+ ## builtin/verify-commit.c ##
+@@
+ #include "gpg-interface.h"
+
+ static const char * const verify_commit_usage[] = {
+- N_("git verify-commit [-v | --verbose] <commit>..."),
++ N_("git verify-commit [-v | --verbose] [--raw] <commit>..."),
+ NULL
+ };
+
+
+ ## builtin/verify-tag.c ##
+@@
+ #include "ref-filter.h"
+
+ static const char * const verify_tag_usage[] = {
+- N_("git verify-tag [-v | --verbose] [--format=<format>] <tag>..."),
++ N_("git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>..."),
+ NULL
+ };
+
+
## help.c ##
@@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
22: 702eb747c0f = 20: 729029f49c3 doc txt & -h consistency: make "rerere" consistent
23: 01e20b8e452 ! 21: 2d4fdbd1aa1 doc txt & -h consistency: make "read-tree" consistent
@@ Metadata
## Commit message ##
doc txt & -h consistency: make "read-tree" consistent
- The C version was right to use "()" in place of "[]", let's update
- the *.txt version accordingly, and furthermore list the *.c options in
- the same order as the *.txt.
+ The C version was right to use "()" in place of "[]" around the option
+ listing, let's update the *.txt version accordingly, and furthermore
+ list the *.c options in the same order as the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
24: 7f93da79fee = 22: c3d227c17c6 doc txt & -h consistency: make "bundle" consistent
25: ab109f73264 ! 23: 02e450ea39b doc txt & -h consistency: use "git foo" form, not "git-foo"
@@ Commit message
Use the "git cmd" form instead of "git-cmd" for both "git
receive-pack" and "git credential-cache--daemon".
+ For "git-receive-pack" we do have a binary with that name, even when
+ installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes
+ of the SYNOPSIS let's use the "git cmd" form like everywhere else. It
+ can be invoked like that (and our tests do so), the parts of our
+ documentation that explain when you need to use the dashed form do so,
+ and use it.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-receive-pack.txt ##
26: d57635b2707 = 24: 430d40d3083 doc txt & -h consistency: add missing options
27: ac959d0cfc1 = 25: acd6e1f2632 doc txt & -h consistency: make "stash" consistent
28: f617375ea9e ! 26: c02fc626542 doc txt & -h consistency: make "annotate" consistent
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
long anchor;
const int hexsz = the_hash_algo->hexsz;
long num_lines = 0;
-+ const char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
++ const char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;
++ const char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
setup_default_color_by_age();
git_config(git_blame_config, &output_option);
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);
for (;;) {
- switch (parse_options_step(&ctx, options, blame_opt_usage)) {
-+ switch (parse_options_step(&ctx, options, usage)) {
++ switch (parse_options_step(&ctx, options, opt_usage)) {
case PARSE_OPT_NON_OPTION:
case PARSE_OPT_UNKNOWN:
break;
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
reverse = 1;
}
- parse_revision_opt(&revs, &ctx, options, blame_opt_usage);
-+ parse_revision_opt(&revs, &ctx, options, usage);
++ parse_revision_opt(&revs, &ctx, options, opt_usage);
}
parse_done:
revision_opts_finish(&revs);
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
case 2: /* (1b) */
if (argc != 4)
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
/* reorder for the new way: <rev> -- <path> */
argv[1] = argv[3];
argv[3] = argv[2];
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
break;
default:
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
}
} else {
if (argc < 2)
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
if (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */
path = add_prefix(prefix, argv[1]);
argv[1] = argv[2];
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
+ nth_line_cb, &sb, lno, anchor,
&bottom, &top, sb.path,
the_repository->index))
- usage_msg_optf(_("failed to parse -L argument '%s'"),
-- blame_opt_usage, options, arg);
-+ usage, options, arg);
+- usage(blame_usage);
++ usage(str_usage);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
29: c96c3fc6d8d = 27: d991b9ef611 doc txt & -h consistency: use "[<label>...]" for "zero or more"
30: 34b778dd176 = 28: dd7d2f0b167 doc txt & -h consistency: make "diff-tree" consistent
31: 336fc749f1c = 29: 3c8154151f3 doc txt & -h consistency: make "commit" consistent
32: 81024d1c3cd = 30: 2452157548b reflog doc: list real subcommands up-front
33: 76e6b7d296a = 31: dbcabff3421 worktree: define subcommand -h in terms of command -h
34: efd0c2c634d = 32: ea82721b057 doc txt & -h consistency: make "worktree" consistent
35: 22da68abce3 ! 33: a2abf7a1161 tests: start asserting that *.txt SYNOPSIS matches -h output
@@ Commit message
testing.
This adds such regression testing, we can parse out the SYNOPSIS
- output with "sed", and is turns out it's relatively easy to normalize
+ output with "sed", and it turns out it's relatively easy to normalize
it and the "-h" output to match on another.
We now ensure that we won't have regressions when it comes to the list
@@ Commit message
"builtin_log_usage" in builtin/log.c doesn't take into account what
command we're running.
- * Likewise "git stage -h" shows "git add" usage, but should be aware
- of what command it's running. The same for "annotate" and "blame".
-
* Commands which implement subcommands such as like
"multi-pack-index", "notes", "remote" etc. having their subcommands
in a very different order in the *.txt and *.c. Fixing it would
- require some verbose diffs, so it's been left alone for onw.
+ require some verbose diffs, so it's been left alone for now.
* Commands such as "format-patch" have a very long argument list in
the *.txt, but just "[<options>]" in the *.c.
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## t/t0450-txt-doc-vs-help.sh (new) ##
+ ## t/t0450-txt-doc-vs-help.sh ##
@@
-+#!/bin/sh
-+
-+test_description='compare (unbuilt) Documentation/*.txt to -h output
+ #!/bin/sh
+
+-test_description='assert (unbuilt) Documentation/*.txt and -h output'
++test_description='assert (unbuilt) Documentation/*.txt and -h output
+
+Run this with --debug to see a summary of where we still fail to make
+the two versions consistent with one another.'
-+
-+. ./test-lib.sh
-+
-+test_expect_success 'setup: list of builtins' '
-+ git --list-cmds=builtins >builtins
-+'
-+
+
+ TEST_PASSES_SANITIZE_LEAK=true
+ . ./test-lib.sh
+@@ t/t0450-txt-doc-vs-help.sh: test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+ '
+
+test_expect_success 'list of txt and help mismatches is sorted' '
+ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
+ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
@@ t/t0450-txt-doc-vs-help.sh (new)
+ fi
+'
+
-+builtin_to_synopsis () {
-+ builtin="$1" &&
-+ test_when_finished "rm -f out" &&
-+ test_expect_code 129 git $builtin -h >out 2>&1 &&
-+ sed -n \
-+ -e '1,/^$/ {
-+ /^$/d;
-+ s/^usage: //;
-+ s/^ *or: //;
-+ p;
-+ }' <out
-+}
-+
-+builtin_to_txt () {
-+ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
-+}
-+
-+txt_synopsis () {
-+ sed -n \
-+ -e '/^\[verse\]$/,/^$/ {
-+ /^$/d;
-+ /^\[verse\]$/d;
+ help_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+@@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {
+ /^$/d;
+ /^\[verse\]$/d;
+
+ s/{litdd}/--/g;
-+
+ s/'\''\(git[ a-z-]*\)'\''/\1/g;
-+ p;
-+ }' \
-+ <"$1"
-+}
+
-+HT=" "
+ p;
+ }' \
+ <"$b2t" >"$out" &&
+@@ t/t0450-txt-doc-vs-help.sh: check_dashed_labels () {
+
+ HT=" "
+
+align_after_nl () {
+ builtin="$1" &&
+ len=$(printf "git %s " "$builtin" | wc -c) &&
@@ t/t0450-txt-doc-vs-help.sh (new)
+}
+
+test_debug '>failing'
-+while read builtin
-+do
-+ test_expect_success "$builtin -h output has no \t" '
-+ builtin_to_synopsis "$builtin" >help.raw &&
-+ ! grep "$HT" help.raw
-+ '
-+
-+ txt="$(builtin_to_txt "$builtin")" &&
-+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
-+
-+ if test -f "$txt"
-+ then
-+ test_set_prereq "$preq"
-+ fi &&
-+
+ while read builtin
+ do
+ # -h output assertions
+@@ t/t0450-txt-doc-vs-help.sh: do
+ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
+ check_dashed_labels "$(txt_to_synopsis "$builtin")"
+ '
++
++ # *.txt output consistency assertions
+ result=
+ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
@@ t/t0450-txt-doc-vs-help.sh (new)
+ else
+ result=success
+ fi &&
-+
+ test_expect_$result "$preq" "$builtin -h output and SYNOPSIS agree" '
-+ txt_synopsis "$txt" >txt.raw &&
++ t2s="$(txt_to_synopsis "$builtin")" &&
+ if test "$builtin" = "merge-tree"
+ then
-+ sed -e '\''s/ (deprecated)$//g'\'' <txt.raw >txt.raw.new &&
-+ mv txt.raw.new txt.raw
++ test_when_finished "rm -f t2s.new" &&
++ sed -e '\''s/ (deprecated)$//g'\'' <"$t2s" >t2s.new
++ t2s=t2s.new
+ fi &&
-+ builtin_to_synopsis "$builtin" >help.raw &&
++ h2s="$(help_to_synopsis "$builtin")" &&
+
+ # The *.txt and -h use different spacing for the
+ # alignment of continued usage output, normalize it.
-+ align_after_nl "$builtin" <txt.raw >txt &&
-+ align_after_nl "$builtin" <help.raw >help &&
++ align_after_nl "$builtin" <"$t2s" >txt &&
++ align_after_nl "$builtin" <"$h2s" >help &&
+ test_cmp txt help
+ '
+
@@ t/t0450-txt-doc-vs-help.sh (new)
+ # used with --debug
+ rm -f txt help tmp 2>/dev/null
+ fi
-+done <builtins
-+
+ done <builtins
+
+test_debug 'say "$(cat failing)"'
+
-+test_done
+ test_done
## t/t0450/txt-help-mismatches (new) ##
@@
36: b56113dd620 ! 34: 3443ae7ee6b tests: assert consistent whitespace in -h output
@@ Commit message
[...]
[--create-reflog] [...]
- Which should instead be like this instead, i.e. the options lines
- should be aligned:
+ Which should instead be like this, i.e. the options lines should be
+ aligned:
[...]
or: git tag [-n[<num>]]
@@ Commit message
## t/t0450-txt-doc-vs-help.sh ##
@@ t/t0450-txt-doc-vs-help.sh: do
- ! grep "$HT" help.raw
+ check_dashed_labels "$(help_to_synopsis "$builtin")"
'
+ test_expect_success "$builtin -h output has consistent spacing" '
-+ builtin_to_synopsis "$builtin" >help.raw &&
++ h2s="$(help_to_synopsis "$builtin")" &&
+ sed -n \
+ -e "/^ / {
+ s/[^ ].*//;
+ p;
+ }" \
-+ <help.raw >help &&
++ <"$h2s" >help &&
+ sort -u help >help.ws &&
+ if test -s help.ws
+ then
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply [flat|nested] 230+ messages in thread* [PATCH v3 01/34] tests: assert *.txt SYNOPSIS and -h output
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:20 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
3 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test to assert basic compliance with the CodingGuidelines in the
SYNOPSIS and builtin -h output. For now we only assert that the "-h"
output doesn't have "\t" characters, as a very basic syntax check.
Subsequent commits will expand on the checks here as various issues
are fixed, but let's first add the test scaffolding.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
create mode 100755 t/t0450-txt-doc-vs-help.sh
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
new file mode 100755
index 00000000000..c8820bdd38f
--- /dev/null
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+
+test_description='assert (unbuilt) Documentation/*.txt and -h output'
+
+TEST_PASSES_SANITIZE_LEAK=true
+. ./test-lib.sh
+
+test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+'
+
+help_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+ out="$out_dir/help.synopsis" &&
+ if test -f "$out"
+ then
+ echo "$out" &&
+ return 0
+ fi &&
+ mkdir -p "$out_dir" &&
+ test_expect_code 129 git $builtin -h >"$out.raw" 2>&1 &&
+ sed -n \
+ -e '1,/^$/ {
+ /^$/d;
+ s/^usage: //;
+ s/^ *or: //;
+ p;
+ }' <"$out.raw" >"$out" &&
+ echo "$out"
+}
+
+HT=" "
+
+while read builtin
+do
+ # -h output assertions
+ test_expect_success "$builtin -h output has no \t" '
+ h2s="$(help_to_synopsis "$builtin")" &&
+ ! grep "$HT" "$h2s"
+ '
+done <builtins
+
+test_done
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 02/34] CodingGuidelines: update and clarify command-line conventions
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:20 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Edit the section which explains how to create a good SYNOPSIS section
for clarity and accuracy, it was mostly introduced in
c455bd8950e (CodingGuidelines: Add a section on writing documentation,
2010-11-04):
* Change "extra" example to "file", which now naturally follows from
previous "<file>..." example (one or more) to "[<file>...]" (zero or
more).
* Explain how we prefer spacing around "[]()" tokens and "|"
alternatives, this is not a new policy, but just codifies what's
already the pattern in the most wide use in the documentation.
Having a space around " | " for flags, but not for flag values is
inconsistent, but this style guide codifies existing
patterns. Grepping shows that we don't have any instance matching the
second "Don't" example:
git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/CodingGuidelines | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 9fca21cc5f9..3d3bdeba9e4 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -650,8 +650,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -665,6 +665,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v3 03/34] builtin/bundle.c: indent with tabs
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
2022-10-04 13:20 ` [PATCH v3 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:20 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix indentation issues introduced with 73c3253d75e (bundle: framework
for options before bundle file, 2019-11-10), and carried forward in
some subsequent commits.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index e80efce3a42..5c78894afd5 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,31 +12,31 @@
*/
static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ N_("git bundle verify [<options>] <file>"),
+ N_("git bundle list-heads <file> [<refname>...]"),
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
- NULL
+ N_("git bundle verify [<options>] <file>"),
+ NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
- NULL
+ N_("git bundle list-heads <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static int parse_options_cmd_bundle(int argc,
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 00/34] doc/UX: make txt & -h output more consistent
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-10-04 13:20 ` [PATCH v3 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
` (34 more replies)
3 siblings, 35 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
We are currently wildly inconsistent in whether the SYNOPSIS in the
manual page matches the first line of the -h output, and as we add new
options we routinely forget to add them to one or the other (or both).
Without a more complex approach it's hard to do something about the
"or both" case. But we can rather easily test whether the -h output
matches the *.txt version, and report differences.
As this series shows that allows us to fix a lot of issues we've
effectively already "fixed", we just fixed them in one version, but
not the other.
For the rest of the general overview (the first paragraphs are
copy/pasted) see the v1 at:
https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com
For v3 see:
https://lore.kernel.org/git/cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com/
Junio: A trivial v5 re your
https://lore.kernel.org/git/xmqqlepvsgeo.fsf@gitster.g/; FWIW I saw
that existing prose, but figured we could continue to use "any paths",
but it's rephrased to incorporate "<pathspec>" here, no other changes.
I'm aware of the minor merge conflict with the builtin/symbolic-ref.c
topic of yours, but I see you've resolved it on your side, so this is
still based on "master".
Ævar Arnfjörð Bjarmason (34):
tests: assert *.txt SYNOPSIS and -h output
CodingGuidelines: update and clarify command-line conventions
builtin/bundle.c: indent with tabs
bundle: define subcommand -h in terms of command -h
doc SYNOPSIS: don't use ' for subcommands
doc SYNOPSIS: consistently use ' for commands
built-ins: consistently add "\n" between "usage" and options
doc txt & -h consistency: word-wrap
doc txt & -h consistency: fix incorrect alternates syntax
doc txt & -h consistency: add "-z" to cat-file "-h"
doc txt & -h consistency: balance unbalanced "[" and "]"
doc txt & -h consistency: correct padding around "[]()"
stash doc SYNOPSIS & -h: correct padding around "[]()"
doc txt & -h consistency: use "<options>", not "<options>..."
doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
doc txt & -h consistency: fix mismatching labels
doc txt & -h consistency: add or fix optional "--" syntax
doc txt & -h consistency: make output order consistent
doc txt & -h consistency: add missing options and labels
doc txt & -h consistency: make "rerere" consistent
doc txt & -h consistency: make "read-tree" consistent
doc txt & -h consistency: make "bundle" consistent
doc txt & -h consistency: use "git foo" form, not "git-foo"
doc txt & -h consistency: add missing options
doc txt & -h consistency: make "stash" consistent
doc txt & -h consistency: make "annotate" consistent
doc txt & -h consistency: use "[<label>...]" for "zero or more"
doc txt & -h consistency: make "diff-tree" consistent
doc txt & -h consistency: make "commit" consistent
reflog doc: list real subcommands up-front
worktree: define subcommand -h in terms of command -h
doc txt & -h consistency: make "worktree" consistent
tests: start asserting that *.txt SYNOPSIS matches -h output
tests: assert consistent whitespace in -h output
Documentation/CodingGuidelines | 14 +-
Documentation/git-annotate.txt | 2 +-
Documentation/git-clean.txt | 10 +-
Documentation/git-commit-graph.txt | 5 +-
.../git-credential-cache--daemon.txt | 4 +-
Documentation/git-diff-files.txt | 2 +-
Documentation/git-fast-export.txt | 2 +-
Documentation/git-hash-object.txt | 3 +-
Documentation/git-interpret-trailers.txt | 5 +-
Documentation/git-merge-base.txt | 4 +-
Documentation/git-mv.txt | 4 +-
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-read-tree.txt | 2 +-
Documentation/git-receive-pack.txt | 4 +-
Documentation/git-reflog.txt | 17 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-rev-list.txt | 2 +-
Documentation/git-send-pack.txt | 5 +-
Documentation/git-show-branch.txt | 4 +-
Documentation/git-show-ref.txt | 4 +-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-stash.txt | 17 +-
Documentation/git-status.txt | 2 +-
Documentation/git-tag.txt | 18 +-
Documentation/git-update-server-info.txt | 8 +-
Documentation/git-upload-archive.txt | 4 +-
Documentation/git-var.txt | 2 +-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
Documentation/git-worktree.txt | 3 +-
builtin/blame.c | 22 ++-
builtin/bugreport.c | 3 +-
builtin/bundle.c | 38 ++--
builtin/cat-file.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 10 +-
builtin/commit-tree.c | 5 +-
builtin/commit.c | 11 +-
builtin/credential-cache--daemon.c | 4 +-
builtin/describe.c | 5 +-
builtin/diagnose.c | 3 +-
builtin/diff-files.c | 1 +
builtin/diff-index.c | 3 +-
builtin/diff-tree.c | 6 +-
builtin/diff.c | 3 +-
builtin/for-each-repo.c | 2 +-
builtin/fsck.c | 5 +-
builtin/hash-object.c | 5 +-
builtin/help.c | 2 +-
builtin/init-db.c | 5 +-
builtin/interpret-trailers.c | 4 +-
builtin/ls-remote.c | 2 +-
builtin/merge-base.c | 2 +-
builtin/pack-objects.c | 4 +-
builtin/pack-redundant.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/read-tree.c | 4 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 3 +-
builtin/revert.c | 9 +-
builtin/rm.c | 4 +-
builtin/send-pack.c | 1 +
builtin/show-branch.c | 3 +-
builtin/show-ref.c | 4 +-
builtin/sparse-checkout.c | 2 +-
builtin/stash.c | 73 +++++---
builtin/symbolic-ref.c | 5 +-
builtin/tag.c | 10 +-
builtin/unpack-file.c | 2 +-
builtin/update-server-info.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/upload-pack.c | 3 +-
builtin/verify-commit.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/verify-tag.c | 2 +-
builtin/worktree.c | 110 ++++++++---
help.c | 2 +-
t/helper/test-proc-receive.c | 2 +-
t/t0450-txt-doc-vs-help.sh | 172 ++++++++++++++++++
t/t0450/txt-help-mismatches | 58 ++++++
82 files changed, 594 insertions(+), 199 deletions(-)
create mode 100755 t/t0450-txt-doc-vs-help.sh
create mode 100644 t/t0450/txt-help-mismatches
Range-diff against v4:
1: f76804fe9ae = 1: cb0e2ffcd2c tests: assert *.txt SYNOPSIS and -h output
2: c95d3b9ad42 = 2: 998cd47045b CodingGuidelines: update and clarify command-line conventions
3: b7c98a40393 = 3: dadae0d364f builtin/bundle.c: indent with tabs
4: 522d7fbb0a3 = 4: 7c9b42d8a9b bundle: define subcommand -h in terms of command -h
5: ac437d4eee5 = 5: 88fdaff4f28 doc SYNOPSIS: don't use ' for subcommands
6: f20cbb661c6 = 6: 7a4e244b261 doc SYNOPSIS: consistently use ' for commands
7: ecdc14f6dfe = 7: c31e6eba62d built-ins: consistently add "\n" between "usage" and options
8: 1b9b6a91916 = 8: e029f1303af doc txt & -h consistency: word-wrap
9: f4598ca1899 = 9: d878b1fd91d doc txt & -h consistency: fix incorrect alternates syntax
10: 0e955f294cd = 10: 323afb78f75 doc txt & -h consistency: add "-z" to cat-file "-h"
11: aa2f9325839 = 11: 84a81046a95 doc txt & -h consistency: balance unbalanced "[" and "]"
12: 009a0e586e9 = 12: f5bd52cb103 doc txt & -h consistency: correct padding around "[]()"
13: b568189532f = 13: 83d53381165 stash doc SYNOPSIS & -h: correct padding around "[]()"
14: e5cb5c91b82 = 14: 760bc0a6727 doc txt & -h consistency: use "<options>", not "<options>..."
15: 403e7ceb449 = 15: 00b4cc7dfcc doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
16: 563ccaab6a9 ! 16: 503bd076a6b doc txt & -h consistency: fix mismatching labels
@@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu
+ Normally, when no <pathspec> is specified, git clean will not
recurse into untracked directories to avoid removing too much.
Specify -d to have it recurse into such directories as well.
- If any paths are specified, -d is irrelevant; all untracked
+- If any paths are specified, -d is irrelevant; all untracked
++ If a <pathspec> is specified, -d is irrelevant; all untracked
+ files matching the specified paths (with exceptions for nested
+ git directories mentioned under `--force`) will be removed.
+
## Documentation/git-credential-cache--daemon.txt ##
@@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - Temporarily store user credentials in memory
17: e6ef67f1c4f = 17: a27ce91d9b3 doc txt & -h consistency: add or fix optional "--" syntax
18: 766bafcde05 = 18: 517ff5a4565 doc txt & -h consistency: make output order consistent
19: fb95d7a9f86 = 19: f5ad5f0a87f doc txt & -h consistency: add missing options and labels
20: 729029f49c3 = 20: 058b22e22f7 doc txt & -h consistency: make "rerere" consistent
21: 2d4fdbd1aa1 = 21: 2c4c48792b3 doc txt & -h consistency: make "read-tree" consistent
22: c3d227c17c6 = 22: c616f2e9129 doc txt & -h consistency: make "bundle" consistent
23: 02e450ea39b = 23: 1a49bbd1f6a doc txt & -h consistency: use "git foo" form, not "git-foo"
24: 430d40d3083 = 24: bacce14d438 doc txt & -h consistency: add missing options
25: acd6e1f2632 = 25: 89ad801409d doc txt & -h consistency: make "stash" consistent
26: c02fc626542 = 26: a7762e82f71 doc txt & -h consistency: make "annotate" consistent
27: d991b9ef611 = 27: 6c68125f191 doc txt & -h consistency: use "[<label>...]" for "zero or more"
28: dd7d2f0b167 = 28: abaffb0b0df doc txt & -h consistency: make "diff-tree" consistent
29: 3c8154151f3 = 29: 65cd6340726 doc txt & -h consistency: make "commit" consistent
30: 2452157548b = 30: f8f716e6ff5 reflog doc: list real subcommands up-front
31: dbcabff3421 = 31: fd2d358fc05 worktree: define subcommand -h in terms of command -h
32: ea82721b057 = 32: 48c1bb97a91 doc txt & -h consistency: make "worktree" consistent
33: a2abf7a1161 = 33: 099998e8cba tests: start asserting that *.txt SYNOPSIS matches -h output
34: 3443ae7ee6b = 34: 4de83d3d89a tests: assert consistent whitespace in -h output
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply [flat|nested] 230+ messages in thread* [PATCH v5 01/34] tests: assert *.txt SYNOPSIS and -h output
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
` (33 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test to assert basic compliance with the CodingGuidelines in the
SYNOPSIS and builtin -h output. For now we only assert that the "-h"
output doesn't have "\t" characters, as a very basic syntax check.
Subsequent commits will expand on the checks here as various issues
are fixed, but let's first add the test scaffolding.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
create mode 100755 t/t0450-txt-doc-vs-help.sh
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
new file mode 100755
index 00000000000..c8820bdd38f
--- /dev/null
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+
+test_description='assert (unbuilt) Documentation/*.txt and -h output'
+
+TEST_PASSES_SANITIZE_LEAK=true
+. ./test-lib.sh
+
+test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+'
+
+help_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+ out="$out_dir/help.synopsis" &&
+ if test -f "$out"
+ then
+ echo "$out" &&
+ return 0
+ fi &&
+ mkdir -p "$out_dir" &&
+ test_expect_code 129 git $builtin -h >"$out.raw" 2>&1 &&
+ sed -n \
+ -e '1,/^$/ {
+ /^$/d;
+ s/^usage: //;
+ s/^ *or: //;
+ p;
+ }' <"$out.raw" >"$out" &&
+ echo "$out"
+}
+
+HT=" "
+
+while read builtin
+do
+ # -h output assertions
+ test_expect_success "$builtin -h output has no \t" '
+ h2s="$(help_to_synopsis "$builtin")" &&
+ ! grep "$HT" "$h2s"
+ '
+done <builtins
+
+test_done
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 02/34] CodingGuidelines: update and clarify command-line conventions
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
` (32 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Edit the section which explains how to create a good SYNOPSIS section
for clarity and accuracy, it was mostly introduced in
c455bd8950e (CodingGuidelines: Add a section on writing documentation,
2010-11-04):
* Change "extra" example to "file", which now naturally follows from
previous "<file>..." example (one or more) to "[<file>...]" (zero or
more).
* Explain how we prefer spacing around "[]()" tokens and "|"
alternatives, this is not a new policy, but just codifies what's
already the pattern in the most wide use in the documentation.
Having a space around " | " for flags, but not for flag values is
inconsistent, but this style guide codifies existing
patterns. Grepping shows that we don't have any instance matching the
second "Don't" example:
git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/CodingGuidelines | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index cb7a367ea08..2a03f748551 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -648,8 +648,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -663,6 +663,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 03/34] builtin/bundle.c: indent with tabs
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 04/34] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (31 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix indentation issues introduced with 73c3253d75e (bundle: framework
for options before bundle file, 2019-11-10), and carried forward in
some subsequent commits.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index e80efce3a42..5c78894afd5 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,31 +12,31 @@
*/
static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ N_("git bundle verify [<options>] <file>"),
+ N_("git bundle list-heads <file> [<refname>...]"),
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
- NULL
+ N_("git bundle verify [<options>] <file>"),
+ NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
- NULL
+ N_("git bundle list-heads <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static int parse_options_cmd_bundle(int argc,
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 04/34] bundle: define subcommand -h in terms of command -h
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-10-13 15:38 ` [PATCH v5 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:38 ` [PATCH v5 05/34] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
` (30 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git bundle" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 29 +++++++++++++++++++----------
1 file changed, 19 insertions(+), 10 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 5c78894afd5..1b08700bf9e 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -11,31 +11,40 @@
* bundle supporting "fetch", "pull", and "ls-remote".
*/
-static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+#define BUILTIN_BUNDLE_CREATE_USAGE \
+ N_("git bundle create [<options>] <file> <git-rev-list args>")
+#define BUILTIN_BUNDLE_VERIFY_USAGE \
+ N_("git bundle verify [<options>] <file>")
+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
+ N_("git bundle list-heads <file> [<refname>...]")
+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
+ N_("git bundle unbundle <file> [<refname>...]")
+
+static char const * const builtin_bundle_usage[] = {
+ BUILTIN_BUNDLE_CREATE_USAGE,
+ BUILTIN_BUNDLE_VERIFY_USAGE,
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
+ NULL,
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ BUILTIN_BUNDLE_CREATE_USAGE,
NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
+ BUILTIN_BUNDLE_VERIFY_USAGE,
NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 05/34] doc SYNOPSIS: don't use ' for subcommands
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-10-13 15:38 ` [PATCH v5 04/34] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:38 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 06/34] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
` (29 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:38 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Almost all of our documentation doesn't use "'" syntax for
subcommands, but these did, let's make them consistent with the
rest.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index db9d46edfa9..0537d4645be 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -17,7 +17,7 @@ The command takes various subcommands, and different options
depending on the subcommand:
[verse]
-'git reflog' ['show'] [<log-options>] [<ref>]
+'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4cfc8833780..4b613d4140c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
DESCRIPTION
-----------
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 06/34] doc SYNOPSIS: consistently use ' for commands
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-10-13 15:38 ` [PATCH v5 05/34] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 07/34] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
` (28 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Most of our commands use ''-quotation only for the name of the command
itself, and not its (optional) arguments. Let's do the same for these.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-fast-export.txt | 2 +-
Documentation/git-sparse-checkout.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 1978dbdc6ad..4643ddbe68f 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -9,7 +9,7 @@ git-fast-export - Git data exporter
SYNOPSIS
--------
[verse]
-'git fast-export [<options>]' | 'git fast-import'
+'git fast-export' [<options>] | 'git fast-import'
DESCRIPTION
-----------
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 3776705bf53..872436d7426 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [<options>]'
+'git sparse-checkout' <subcommand> [<options>]
DESCRIPTION
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 07/34] built-ins: consistently add "\n" between "usage" and options
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 06/34] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 08/34] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
` (27 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change commands in the "diff" family and "rev-list" to separate the
usage information and option listing with an empty line.
In the case of "git diff -h" we did this already (but let's use a
consistent "\n" pattern there), for the rest these are now consistent
with how the parse_options() API would emit usage.
As we'll see in a subsequent commit this also helps to make the "git
<cmd> -h" output more easily machine-readable, as we can assume that
the usage information is separated from the options by an empty line.
Note that "COMMON_DIFF_OPTIONS_HELP" starts with a "\n", so the
seeming omission of a "\n" here is correct, the second one is provided
by the macro.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-files.c | 1 +
builtin/diff-index.c | 1 +
builtin/diff-tree.c | 1 +
builtin/diff.c | 3 ++-
builtin/rev-list.c | 1 +
5 files changed, 6 insertions(+), 1 deletion(-)
diff --git a/builtin/diff-files.c b/builtin/diff-files.c
index 92cf6e1e922..096ea2fedbc 100644
--- a/builtin/diff-files.c
+++ b/builtin/diff-files.c
@@ -15,6 +15,7 @@
static const char diff_files_usage[] =
"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_files(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index 7d158af6b6d..e667cf52e7d 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -11,6 +11,7 @@
static const char diff_cache_usage[] =
"git diff-index [-m] [--cached] "
"[<common-diff-options>] <tree-ish> [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_index(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 116097a404a..23f58702fa0 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)
static const char diff_tree_usage[] =
"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
" --cc show combined diff for merge commits removing uninteresting hunks\n"
diff --git a/builtin/diff.c b/builtin/diff.c
index 54bb3de964c..67760b67552 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =
" or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
" or: git diff [<options>] <commit>...<commit> [--] [<path>...]\n"
" or: git diff [<options>] <blob> <blob>\n"
-" or: git diff [<options>] --no-index [--] <path> <path>\n"
+" or: git diff [<options>] --no-index [--] <path> <path>"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
static const char *blob_path(struct object_array_entry *entry)
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index fba6f5d51f3..f67e2b33555 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -21,6 +21,7 @@
static const char rev_list_usage[] =
"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"\n"
" limiting output:\n"
" --max-count=<n>\n"
" --max-age=<epoch>\n"
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 08/34] doc txt & -h consistency: word-wrap
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 07/34] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 09/34] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
` (26 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the documentation and -h output for those built-in commands
where both the -h output and *.txt were lacking in word-wrapping.
There are many more built-ins that could use this treatment, this
change is narrowed to those where this whitespace change is needed to
make the -h and *.txt consistent in the end.
In the case of "Documentation/git-hash-object.txt" and
"builtin/hash-object.c" this is not a "doc txt & -h consistency"
change, as we're changing both versions, doing so here makes a
subsequent change smaller.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-hash-object.txt | 3 ++-
Documentation/git-worktree.txt | 3 ++-
builtin/bugreport.c | 3 ++-
builtin/commit-graph.c | 8 ++++----
builtin/commit-tree.c | 4 ++--
builtin/diagnose.c | 3 ++-
builtin/hash-object.c | 3 ++-
builtin/init-db.c | 3 ++-
builtin/interpret-trailers.c | 4 +++-
builtin/read-tree.c | 4 +++-
builtin/show-branch.c | 3 ++-
builtin/show-ref.c | 4 +++-
12 files changed, 29 insertions(+), 16 deletions(-)
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index df9e2c58bdb..58670ef12f7 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+ [--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
DESCRIPTION
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index ada30c86a7c..063d6eeb99d 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees
SYNOPSIS
--------
[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+ [-b <new-branch>] <path> [<commit-ish>]
'git worktree list' [-v | --porcelain [-z]]
'git worktree lock' [--reason <string>] <worktree>
'git worktree move' <worktree> <new-path>
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 530895be55f..faa268f3cfb 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]"),
+ N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ " [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 51557fe786e..cd346f95f08 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -13,10 +13,10 @@
N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append] " \
- "[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] " \
- "[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] " \
- "<split options>")
+ N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
+ " <split options>")
static const char * builtin_commit_graph_verify_usage[] = {
BUILTIN_COMMIT_GRAPH_VERIFY_USAGE,
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 63ea3229333..e4b85d29d56 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,8 +15,8 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
- N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] "
- "[(-F <file>)...] <tree>"),
+ N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
+ " [(-F <file>)...] <tree>"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 576e0e8e385..28c394a62a5 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,8 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]"),
+ N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ " [--mode=<mode>]"),
NULL
};
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index fbae878c2b9..f7c16802f0c 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
+ " [--stdin] [--] <file>..."),
"git hash-object --stdin-paths",
NULL
};
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 546f9c595e7..08ba006d55e 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
}
static const char *const init_db_usage[] = {
- N_("git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]"),
+ N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 84748eafc01..4cf0cf265dc 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -13,7 +13,9 @@
#include "config.h"
static const char * const git_interpret_trailers_usage[] = {
- N_("git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]"),
+ N_("git interpret-trailers [--in-place] [--trim-empty]\n"
+ " [(--trailer <token>[(=|:)<value>])...]\n"
+ " [<file>...]"),
NULL
};
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index 9f1f33e9546..b3a389e1b1f 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)
}
static const char * const read_tree_usage[] = {
- N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) [-u | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
+ N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
+ " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
diff --git a/builtin/show-branch.c b/builtin/show-branch.c
index d3f5715e3e3..c013abaf942 100644
--- a/builtin/show-branch.c
+++ b/builtin/show-branch.c
@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {
N_("git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n"
" [--current] [--color[=<when>] | --no-color] [--sparse]\n"
" [--more=<n> | --list | --independent | --merge-base]\n"
- " [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]"),
+ " [--no-name | --sha1-name] [--topics]\n"
+ " [(<rev> | <glob>)...]"),
N_("git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]"),
NULL
};
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 48569061087..3af6a53ee97 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -9,7 +9,9 @@
#include "parse-options.h"
static const char * const show_ref_usage[] = {
- N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]"),
+ N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\n"
+ " [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n"
+ " [--heads] [--] [<pattern>...]"),
N_("git show-ref --exclude-existing[=<pattern>]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 09/34] doc txt & -h consistency: fix incorrect alternates syntax
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 08/34] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 10/34] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
` (25 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
This syntax issue for "bugreport" originated in
238b439d698 (bugreport: add tool to generate debugging info,
2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
"bugreport" documentation and code.
In the case of "Documentation/git-stash.txt" and "builtin/stash.c"
this is not a "doc txt & -h consistency" change, as we're changing
both versions, doing so here makes a subsequent change smaller.
In that case fix the incorrect "[-o | --option <argument>]" syntax,
which should be "[(-o | --option) <argument>]", we were previously
claiming that only the long option accepted the "<argument>", which
isn't what we meant.
The "stash" issue has been with us in both the "-h" and *.txt versions
since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
We could claim that this isn't a syntax issue if a "vertical bar binds
tighter than option and its argument", but such a rule would change
e.g. this "cat-file" SYNOPSIS example to mean something we don't:
... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
We have various other examples where the post-image here is already
used, e.g. for "format-patch" ("-o"), "grep" ("-m"),
"submodule" ("set-branch -b") etc.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 6 +++---
builtin/bugreport.c | 2 +-
builtin/diagnose.c | 2 +-
builtin/stash.c | 6 +++---
4 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index c5d70918283..4856f452511 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -14,12 +14,12 @@ SYNOPSIS
'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [-m|--message <message>]
+ [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
DESCRIPTION
-----------
@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
COMMANDS
--------
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index faa268f3cfb..23170113cc8 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
" [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 28c394a62a5..474de9ec647 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
diff --git a/builtin/stash.c b/builtin/stash.c
index 2274aae2556..51d40efaac7 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [-m|--message <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 10/34] doc txt & -h consistency: add "-z" to cat-file "-h"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 09/34] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 11/34] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
` (24 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited
input with `-z`, 2022-07-22), before that change the SYNOPSIS and "-h"
output were the same, but not afterwards.
That change followed a similar earlier divergence in
473fa2df08d (Documentation: add --batch-command to cat-file synopsis,
2022-04-07). Subsequent commits will fix this sort of thing more
systematically, but let's fix this one as a one-off.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/cat-file.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/cat-file.c b/builtin/cat-file.c
index 989eee0bb4c..fa7bd891692 100644
--- a/builtin/cat-file.c
+++ b/builtin/cat-file.c
@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)
N_("git cat-file (-t | -s) [--allow-unknown-type] <object>"),
N_("git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\n"
" [--buffer] [--follow-symlinks] [--unordered]\n"
- " [--textconv | --filters]"),
+ " [--textconv | --filters] [-z]"),
N_("git cat-file (--textconv | --filters)\n"
" [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]"),
NULL
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 11/34] doc txt & -h consistency: balance unbalanced "[" and "]"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 10/34] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 12/34] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
` (23 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a "-h" output syntax issue introduced when "--diagnose" was added
in aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,
2022-08-12): We need to close the "[" we opened. The
corresponding *.txt change did not have the same issue.
The "help -h" output then had one "]" too many, which is an issue
introduced in b40845293b5 (help: correct the usage string in -h and
documentation, 2021-09-10).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bugreport.c | 2 +-
builtin/help.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 23170113cc8..bb138161943 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
static const char * const bugreport_usage[] = {
N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
- " [--diagnose[=<mode>]"),
+ " [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/help.c b/builtin/help.c
index 6f2796f211e..53f2812dfb1 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {
};
static const char * const builtin_help_usage[] = {
- "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
+ "git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]",
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
"git help [-g|--guides]",
"git help [-c|--config]",
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 12/34] doc txt & -h consistency: correct padding around "[]()"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (10 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 11/34] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 13/34] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
` (22 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-diff-files.txt | 2 +-
Documentation/git-hash-object.txt | 2 +-
Documentation/git-merge-base.txt | 4 ++--
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-send-pack.txt | 2 +-
Documentation/git-show-branch.txt | 4 ++--
Documentation/git-show-ref.txt | 4 ++--
Documentation/git-var.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
builtin/bugreport.c | 2 +-
builtin/commit-graph.c | 2 +-
builtin/diagnose.c | 2 +-
builtin/sparse-checkout.c | 2 +-
15 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index bf1febb9ae7..591e3801b7b 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index
SYNOPSIS
--------
[verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 58670ef12f7..472b5bb995b 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]
[--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 2d944e0851f..b01ba3d3565 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
--------
[verse]
-'git merge-base' [-a|--all] <commit> <commit>...
-'git merge-base' [-a|--all] --octopus <commit>...
+'git merge-base' [-a | --all] <commit> <commit>...
+'git merge-base' [-a | --all] --octopus <commit>...
'git merge-base' --is-ancestor <commit> <commit>
'git merge-base' --independent <commit>...
'git merge-base' --fork-point <ref> [<commit>]
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index ee7034b5e52..dda80a740c8 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
SYNOPSIS
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
DESCRIPTION
-----------
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 9fed59a3172..844d6f808a0 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files
SYNOPSIS
--------
[verse]
-'git prune-packed' [-n|--dry-run] [-q|--quiet]
+'git prune-packed' [-n | --dry-run] [-q | --quiet]
DESCRIPTION
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4b613d4140c..9d0e6f53e7e 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
DESCRIPTION
-----------
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index be41f119740..e0c71623432 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
- [--[no-]signed|--signed=(true|false|if-asked)]
+ [--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
DESCRIPTION
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index e5ec6b467f9..71f608b1ff1 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits
SYNOPSIS
--------
[verse]
-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]
+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
[(<rev> | <glob>)...]
-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]
DESCRIPTION
-----------
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ab4d271925d..d1d56f68b43 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository
SYNOPSIS
--------
[verse]
-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]
- [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
'git show-ref' --exclude-existing[=<pattern>]
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 387cc1b9142..6aa521fab23 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -9,7 +9,7 @@ git-var - Show a Git logical variable
SYNOPSIS
--------
[verse]
-'git var' ( -l | <variable> )
+'git var' (-l | <variable>)
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 61ca6d04c20..b8720dce8ab 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files
SYNOPSIS
--------
[verse]
-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...
+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
DESCRIPTION
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index bb138161943..61d93383f51 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index cd346f95f08..13cbb75ca28 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -14,7 +14,7 @@
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
- " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 474de9ec647..d52015c67a4 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
+ N_("git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 287716db68e..aac0f708e42 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init|list|set|add|reapply|disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 13/34] stash doc SYNOPSIS & -h: correct padding around "[]()"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (11 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 12/34] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 14/34] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
` (21 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 12 ++++++------
builtin/stash.c | 28 ++++++++++++++--------------
2 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 4856f452511..ea16d2eae7c 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -9,17 +9,17 @@ SYNOPSIS
--------
[verse]
'git stash' list [<log-options>]
-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q|--quiet] [<stash>]
-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+'git stash' drop [-q | --quiet] [<stash>]
+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
DESCRIPTION
-----------
diff --git a/builtin/stash.c b/builtin/stash.c
index 51d40efaac7..d91cf5fd3e1 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -24,16 +24,16 @@
static const char * const git_stash_usage[] = {
N_("git stash list [<options>]"),
N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q|--quiet] [<stash>]"),
- N_("git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
+ N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
- N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
- N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
NULL
};
@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 14/34] doc txt & -h consistency: use "<options>", not "<options>..."
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (12 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 13/34] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" Ævar Arnfjörð Bjarmason
` (20 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
It's arguably more correct to say "[<option>...]" than either of these
forms, but the vast majority of our documentation uses the
"[<options>]" form to indicate an arbitrary number of options, let's
do the same in these cases, which were the odd ones out.
In the case of "mv" and "sparse-checkout" let's add the missing "[]"
to indicate that these are optional.
In the case of "t/helper/test-proc-receive.c" there is no *.txt
version, making it the only hunk in this commit that's not a "doc txt
& -h consistency" change.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-mv.txt | 2 +-
Documentation/git-status.txt | 2 +-
builtin/pack-objects.c | 4 ++--
builtin/sparse-checkout.c | 2 +-
t/helper/test-proc-receive.c | 2 +-
5 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 79449bf98fe..972a055fbd8 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' <options>... <args>...
+'git mv' [<options>] <args>...
DESCRIPTION
-----------
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 54a4b29b473..5e438a7fdc1 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -9,7 +9,7 @@ git-status - Show the working tree status
SYNOPSIS
--------
[verse]
-'git status' [<options>...] [--] [<pathspec>...]
+'git status' [<options>] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 3658c05cafc..573d0b20b76 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,
#define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)
static const char *pack_usage[] = {
- N_("git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]"),
- N_("git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index aac0f708e42..58a22503f04 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) [<options>]"),
NULL
};
diff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c
index cc08506cf0b..a4b305f4947 100644
--- a/t/helper/test-proc-receive.c
+++ b/t/helper/test-proc-receive.c
@@ -6,7 +6,7 @@
#include "test-tool.h"
static const char *proc_receive_usage[] = {
- "test-tool proc-receive [<options>...]",
+ "test-tool proc-receive [<options>]",
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (13 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 14/34] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 16/34] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
` (19 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change "builtin/credential-cache--daemon.c" to use "<socket-path>" not
"<socket_path>" in a placeholder label, almost all of our
documentation uses this form.
This is now consistent with the "If a placeholder has multiple words,
they are separated by dashes" guideline added in
9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's
add a now-passing test to assert that that's the case.
To do this we need to introduce a very sed-powered parser to extract
the SYNOPSIS from the *.txt, and handle not all commands with "-h"
having a corresponding *.txt (e.g. "bisect--helper"). We'll still want
to handle syntax edge cases in the *.txt in subsequent commits for
other checks, but let's do that then.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/credential-cache--daemon.c | 2 +-
t/t0450-txt-doc-vs-help.sh | 46 ++++++++++++++++++++++++++++++
2 files changed, 47 insertions(+), 1 deletion(-)
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index 4c6c89ab0de..ca672a6a619 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket_path>",
+ "git-credential-cache--daemon [opts] <socket-path>",
NULL
};
int debug = 0;
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index c8820bdd38f..efd00cfc51a 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -30,6 +30,35 @@ help_to_synopsis () {
echo "$out"
}
+builtin_to_txt () {
+ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
+}
+
+txt_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+ out="$out_dir/txt.synopsis" &&
+ if test -f "$out"
+ then
+ echo "$out" &&
+ return 0
+ fi &&
+ b2t="$(builtin_to_txt "$builtin")" &&
+ sed -n \
+ -e '/^\[verse\]$/,/^$/ {
+ /^$/d;
+ /^\[verse\]$/d;
+
+ p;
+ }' \
+ <"$b2t" >"$out" &&
+ echo "$out"
+}
+
+check_dashed_labels () {
+ ! grep -E "<[^>_-]+_" "$1"
+}
+
HT=" "
while read builtin
@@ -39,6 +68,23 @@ do
h2s="$(help_to_synopsis "$builtin")" &&
! grep "$HT" "$h2s"
'
+
+ test_expect_success "$builtin -h output has dashed labels" '
+ check_dashed_labels "$(help_to_synopsis "$builtin")"
+ '
+
+ txt="$(builtin_to_txt "$builtin")" &&
+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
+
+ if test -f "$txt"
+ then
+ test_set_prereq "$preq"
+ fi &&
+
+ # *.txt output assertions
+ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
+ check_dashed_labels "$(txt_to_synopsis "$builtin")"
+ '
done <builtins
test_done
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 16/34] doc txt & -h consistency: fix mismatching labels
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (14 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 17/34] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
` (18 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various inconsistencies between command SYNOPSIS and the
corresponding -h output where our translatable labels didn't match
up.
In some cases we need to adjust the prose that follows the SYNOPSIS
accordingly, as it refers back to the changed label.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 10 +++++-----
Documentation/git-credential-cache--daemon.txt | 4 ++--
Documentation/git-mv.txt | 4 ++--
Documentation/git-receive-pack.txt | 4 ++--
Documentation/git-tag.txt | 18 +++++++++---------
Documentation/git-upload-archive.txt | 4 ++--
builtin/bugreport.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 4 ++--
builtin/for-each-repo.c | 2 +-
builtin/pack-redundant.c | 2 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/stash.c | 2 +-
builtin/unpack-file.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/worktree.c | 2 +-
18 files changed, 35 insertions(+), 35 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 91742633fa8..8347c6eed79 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
DESCRIPTION
-----------
@@ -20,16 +20,16 @@ Normally, only files unknown to Git are removed, but if the `-x`
option is specified, ignored files are also removed. This can, for
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
-are affected.
+If any optional `<pathspec>...` arguments are given, only those paths
+that match the pathspec are affected.
OPTIONS
-------
-d::
- Normally, when no <path> is specified, git clean will not
+ Normally, when no <pathspec> is specified, git clean will not
recurse into untracked directories to avoid removing too much.
Specify -d to have it recurse into such directories as well.
- If any paths are specified, -d is irrelevant; all untracked
+ If a <pathspec> is specified, -d is irrelevant; all untracked
files matching the specified paths (with exceptions for nested
git directories mentioned under `--force`) will be removed.
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index 01e1c214dd8..650a15a7edf 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
SYNOPSIS
--------
[verse]
-'git credential-cache{litdd}daemon' [--debug] <socket>
+'git credential-cache{litdd}daemon' [--debug] <socket-path>
DESCRIPTION
-----------
@@ -16,7 +16,7 @@ DESCRIPTION
NOTE: You probably don't want to invoke this command yourself; it is
started automatically when you use linkgit:git-credential-cache[1].
-This command listens on the Unix domain socket specified by `<socket>`
+This command listens on the Unix domain socket specified by `<socket-path>`
for `git-credential-cache` clients. Clients may store and retrieve
credentials. Each credential is held for a timeout specified by the
client; once no credentials are held, the daemon exits.
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 972a055fbd8..fb0220fd18d 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' [<options>] <args>...
+'git mv' [<options>] <source>... <destination>
DESCRIPTION
-----------
@@ -30,7 +30,7 @@ OPTIONS
-------
-f::
--force::
- Force renaming or moving of a file even if the target exists
+ Force renaming or moving of a file even if the <destination> exists.
-k::
Skip move or rename actions which would lead to an error
condition. An error happens when a source is neither existing nor
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 014a78409b9..5c297db1a4b 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <directory>
+'git-receive-pack' <git-dir>
DESCRIPTION
-----------
@@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1].
OPTIONS
-------
-<directory>::
+<git-dir>::
The repository to sync into.
--http-backend-info-refs::
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 31a97a1b6c5..fdc72b5875a 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
SYNOPSIS
--------
[verse]
-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
@@ -26,19 +26,19 @@ to delete, list or verify tags.
Unless `-f` is given, the named tag must not yet exist.
-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
+If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
creates a 'tag' object, and requires a tag message. Unless
`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
in the tag message.
-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
are absent, `-a` is implied.
Otherwise, a tag reference that points directly at the given object
(i.e., a lightweight tag) is created.
A GnuPG signed tag object will be created when `-s` or `-u
-<keyid>` is used. When `-u <keyid>` is not used, the
+<key-id>` is used. When `-u <key-id>` is not used, the
committer identity for the current user is used to find the
GnuPG key for signing. The configuration variable `gpg.program`
is used to specify custom GnuPG binary.
@@ -72,8 +72,8 @@ OPTIONS
Override `tag.gpgSign` configuration variable that is
set to force each and every tag to be signed.
--u <keyid>::
---local-user=<keyid>::
+-u <key-id>::
+--local-user=<key-id>::
Make a GPG-signed tag, using the given key.
-f::
@@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines.
Use the given tag message (instead of prompting).
If multiple `-m` options are given, their values are
concatenated as separate paragraphs.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-F <file>::
--file=<file>::
Take the tag message from the given file. Use '-' to
read the message from the standard input.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-e::
@@ -220,7 +220,7 @@ it in the repository configuration as follows:
-------------------------------------
[user]
- signingKey = <gpg-keyid>
+ signingKey = <gpg-key_id>
-------------------------------------
`pager.tag` is only respected when listing tags, i.e., when `-l` is
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index fba0f1c1b27..e8eb10baad7 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
SYNOPSIS
--------
[verse]
-'git upload-archive' <directory>
+'git upload-archive' <repository>
DESCRIPTION
-----------
@@ -54,7 +54,7 @@ access via non-smart-http.
OPTIONS
-------
-<directory>::
+<repository>::
The repository to get a tar archive from.
GIT
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 61d93383f51..96052541cbf 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/clean.c b/builtin/clean.c
index 5466636e666..6f039f555b2 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 13cbb75ca28..e8f77f535f3 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -10,10 +10,10 @@
#include "tag.h"
#define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \
- N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
+ N_("git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
" [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index fd86e5a8619..c6379b783c8 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <command-args>"),
+ N_("git for-each-repo --config=<config> <arguments>"),
NULL
};
diff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c
index ed9b9013a5f..ecd49ca268f 100644
--- a/builtin/pack-redundant.c
+++ b/builtin/pack-redundant.c
@@ -14,7 +14,7 @@
#define BLKSIZE 512
static const char pack_redundant_usage[] =
-"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)";
+"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)";
static int load_all_packs, verbose, alt_odb;
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 83d7a778e37..12570537d37 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <path>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
NULL,
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index f67e2b33555..ada68a4af5e 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [-- <path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/stash.c b/builtin/stash.c
index d91cf5fd3e1..83c9591ea6d 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -22,7 +22,7 @@
#define INCLUDE_ALL_FILES 2
static const char * const git_stash_usage[] = {
- N_("git stash list [<options>]"),
+ N_("git stash list [<log-options>]"),
N_("git stash show [<options>] [<stash>]"),
N_("git stash drop [-q | --quiet] [<stash>]"),
N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
diff --git a/builtin/unpack-file.c b/builtin/unpack-file.c
index 58652229f27..9e8119dd354 100644
--- a/builtin/unpack-file.c
+++ b/builtin/unpack-file.c
@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)
struct object_id oid;
if (argc != 2 || !strcmp(argv[1], "-h"))
- usage("git unpack-file <sha1>");
+ usage("git unpack-file <blob>");
if (get_oid(argv[1], &oid))
die("Not a valid object name %s", argv[1]);
diff --git a/builtin/upload-archive.c b/builtin/upload-archive.c
index 98d028dae67..945ee2b4126 100644
--- a/builtin/upload-archive.c
+++ b/builtin/upload-archive.c
@@ -10,7 +10,7 @@
#include "strvec.h"
static const char upload_archive_usage[] =
- "git upload-archive <repo>";
+ "git upload-archive <repository>";
static const char deadchild[] =
"git upload-archive: archiver died with error";
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index 05c52135946..db9ac5c4606 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
NULL
};
diff --git a/builtin/worktree.c b/builtin/worktree.c
index c6710b25520..5bfc18e5a24 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {
N_("git worktree prune [<options>]"),
N_("git worktree remove [<options>] <worktree>"),
N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <path>"),
+ N_("git worktree unlock <worktree>"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 17/34] doc txt & -h consistency: add or fix optional "--" syntax
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (15 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 16/34] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 18/34] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
` (17 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add the "[--]" for those cases where the *.txt and -h were
inconsistent, or where we incorrectly stated in one but not the other
that the "--" was mandatory.
In the case of "rev-list" both sides were wrong, as we we don't
require one or more paths if "--" is used, e.g. this is OK:
git rev-list HEAD --
That part of this change is not a "doc txt & -h consistency" change,
as we're changing both versions, doing so here makes both sides
consistent.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-rev-list.txt | 2 +-
builtin/for-each-repo.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/verify-pack.c | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 20bb8e82176..51029a22715 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order
SYNOPSIS
--------
[verse]
-'git rev-list' [<options>] <commit>... [[--] <path>...]
+'git rev-list' [<options>] <commit>... [--] [<path>...]
DESCRIPTION
-----------
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index c6379b783c8..d45d873f579 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <arguments>"),
+ N_("git for-each-repo --config=<config> [--] <arguments>"),
NULL
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index ada68a4af5e..3acd93f71e1 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [--] [<path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index db9ac5c4606..27d6f75fd8a 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx..."),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 18/34] doc txt & -h consistency: make output order consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (16 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 17/34] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 19/34] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
` (16 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix cases where the SYNOPSIS and -h output was presented in a
different order.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/merge-base.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/merge-base.c b/builtin/merge-base.c
index a11f8c6e4bb..6f3941f2a49 100644
--- a/builtin/merge-base.c
+++ b/builtin/merge-base.c
@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)
static const char * const merge_base_usage[] = {
N_("git merge-base [-a | --all] <commit> <commit>..."),
N_("git merge-base [-a | --all] --octopus <commit>..."),
- N_("git merge-base --independent <commit>..."),
N_("git merge-base --is-ancestor <commit> <commit>"),
+ N_("git merge-base --independent <commit>..."),
N_("git merge-base --fork-point <ref> [<commit>]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 19/34] doc txt & -h consistency: add missing options and labels
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (17 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 18/34] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 20/34] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
` (15 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various issues of SYNOPSIS and -h output syntax where:
* Options such as --force were missing entirely
* ...or the short option, such as -f
* We said "opts" or "options", but could instead enumerate
the (small) set of supported options
* Options that were missing entirely (ls-remote's --sort=<key>)
As we can specify "--sort" multiple times (it's backed by a
string-list" it should really be "[(--sort=<key>)...]", which is
what "git for-each-ref" lists it as, but let's leave that issue for
a subsequent cleanup, and stop at making these consistent. Other
"ref-filter.h" users share the same issue, e.g. "git-branch.txt".
* For "verify-tag" and "verify-commit" we were missing the "--raw"
option.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-send-pack.txt | 3 ++-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-update-server-info.txt | 8 +++++++-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
builtin/credential-cache--daemon.c | 2 +-
builtin/describe.c | 5 +++--
builtin/diff-index.c | 2 +-
builtin/ls-remote.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/revert.c | 9 +++++----
builtin/send-pack.c | 1 +
builtin/symbolic-ref.c | 5 +++--
builtin/tag.c | 10 ++++++----
builtin/update-server-info.c | 2 +-
builtin/upload-pack.c | 3 ++-
builtin/verify-commit.c | 2 +-
builtin/verify-tag.c | 2 +-
help.c | 2 +-
19 files changed, 40 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index e0c71623432..595b002152f 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository
SYNOPSIS
--------
[verse]
-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+'git send-pack' [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
[--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 872436d7426..68392d2a56e 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout' <subcommand> [<options>]
+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]
DESCRIPTION
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
index 969bb2e15f1..17e429dbd09 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.txt
@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
SYNOPSIS
--------
[verse]
-'git update-server-info'
+'git update-server-info' [-f | --force]
DESCRIPTION
-----------
@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
what references and packs the server has. This command
generates such auxiliary files.
+OPTIONS
+-------
+-f::
+--force::
+ update the info files from scratch.
+
OUTPUT
------
diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt
index 92097f6673d..aee4c40eac4 100644
--- a/Documentation/git-verify-commit.txt
+++ b/Documentation/git-verify-commit.txt
@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits
SYNOPSIS
--------
[verse]
-'git verify-commit' <commit>...
+'git verify-commit' [-v | --verbose] [--raw] <commit>...
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
index 0b8075dad96..81d50ecc4c6 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.txt
@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags
SYNOPSIS
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
+'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index ca672a6a619..d4eb0097d24 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket-path>",
+ "git-credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
diff --git a/builtin/describe.c b/builtin/describe.c
index e17c4b4c69b..23e3f05fb10 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -23,8 +23,9 @@
define_commit_slab(commit_names, struct commit_name *);
static const char * const describe_usage[] = {
- N_("git describe [<options>] [<commit-ish>...]"),
- N_("git describe [<options>] --dirty"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]"),
+ N_("git describe <blob>"),
NULL
};
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index e667cf52e7d..aea139b9d8f 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -9,7 +9,7 @@
#include "submodule.h"
static const char diff_cache_usage[] =
-"git diff-index [-m] [--cached] "
+"git diff-index [-m] [--cached] [--merge-base] "
"[<common-diff-options>] <tree-ish> [<path>...]"
"\n"
COMMON_DIFF_OPTIONS_HELP;
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index df44e5cc0d1..5d5ac038716 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -7,7 +7,7 @@
static const char * const ls_remote_usage[] = {
N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
- " [-q | --quiet] [--exit-code] [--get-url]\n"
+ " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
" [--symref] [<repository> [<refs>...]]"),
NULL
};
diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c
index cfbd5c36c76..27c2ca06acb 100644
--- a/builtin/pack-refs.c
+++ b/builtin/pack-refs.c
@@ -5,7 +5,7 @@
#include "repository.h"
static char const * const pack_refs_usage[] = {
- N_("git pack-refs [<options>]"),
+ N_("git pack-refs [--all] [--no-prune]"),
NULL
};
diff --git a/builtin/revert.c b/builtin/revert.c
index ee2a0807f01..ee32c714a76 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -21,14 +21,15 @@
*/
static const char * const revert_usage[] = {
- N_("git revert [<options>] <commit-ish>..."),
- N_("git revert <subcommand>"),
+ N_("git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>..."),
+ N_("git revert (--continue | --skip | --abort | --quit)"),
NULL
};
static const char * const cherry_pick_usage[] = {
- N_("git cherry-pick [<options>] <commit-ish>..."),
- N_("git cherry-pick <subcommand>"),
+ N_("git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n"
+ " [-S[<keyid>]] <commit>..."),
+ N_("git cherry-pick (--continue | --skip | --abort | --quit)"),
NULL
};
diff --git a/builtin/send-pack.c b/builtin/send-pack.c
index 64962be0168..4c5d125fa0a 100644
--- a/builtin/send-pack.c
+++ b/builtin/send-pack.c
@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {
N_("git send-pack [--mirror] [--dry-run] [--force]\n"
" [--receive-pack=<git-receive-pack>]\n"
" [--verbose] [--thin] [--atomic]\n"
+ " [--[no-]signed | --signed=(true|false|if-asked)]\n"
" [<host>:]<directory> (--all | <ref>...)"),
NULL,
};
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index 1b0f10225f0..50b6df78df0 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -5,8 +5,9 @@
#include "parse-options.h"
static const char * const git_symbolic_ref_usage[] = {
- N_("git symbolic-ref [<options>] <name> [<ref>]"),
- N_("git symbolic-ref -d [-q] <name>"),
+ N_("git symbolic-ref [-m <reason>] <name> <ref>"),
+ N_("git symbolic-ref [-q] [--short] <name>"),
+ N_("git symbolic-ref --delete [-q] <name>"),
NULL
};
diff --git a/builtin/tag.c b/builtin/tag.c
index 75dece0e4f1..d428c45dc8d 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -23,11 +23,13 @@
#include "date.h"
static const char * const git_tag_usage[] = {
- N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\n"
- " <tagname> [<head>]"),
+ N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n"
+ " <tagname> [<commit> | <object>]"),
N_("git tag -d <tagname>..."),
- N_("git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\n"
- " [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
+ N_("git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n"
+ " [--points-at <object>] [--column[=<options>] | --no-column]\n"
+ " [--create-reflog] [--sort=<key>] [--format=<format>]\n"
+ " [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
N_("git tag -v [--format=<format>] <tagname>..."),
NULL
};
diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c
index 880fffec587..d2239c9ef4d 100644
--- a/builtin/update-server-info.c
+++ b/builtin/update-server-info.c
@@ -4,7 +4,7 @@
#include "parse-options.h"
static const char * const update_server_info_usage[] = {
- "git update-server-info [--force]",
+ "git update-server-info [-f | --force]",
NULL
};
diff --git a/builtin/upload-pack.c b/builtin/upload-pack.c
index 125af53885f..25b69da2bf2 100644
--- a/builtin/upload-pack.c
+++ b/builtin/upload-pack.c
@@ -8,7 +8,8 @@
#include "serve.h"
static const char * const upload_pack_usage[] = {
- N_("git upload-pack [<options>] <dir>"),
+ N_("git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\n"
+ " [--advertise-refs] <directory>"),
NULL
};
diff --git a/builtin/verify-commit.c b/builtin/verify-commit.c
index 40c69a0bedd..3ebad32b0f1 100644
--- a/builtin/verify-commit.c
+++ b/builtin/verify-commit.c
@@ -16,7 +16,7 @@
#include "gpg-interface.h"
static const char * const verify_commit_usage[] = {
- N_("git verify-commit [-v | --verbose] <commit>..."),
+ N_("git verify-commit [-v | --verbose] [--raw] <commit>..."),
NULL
};
diff --git a/builtin/verify-tag.c b/builtin/verify-tag.c
index f45136a06ba..217566952d8 100644
--- a/builtin/verify-tag.c
+++ b/builtin/verify-tag.c
@@ -15,7 +15,7 @@
#include "ref-filter.h"
static const char * const verify_tag_usage[] = {
- N_("git verify-tag [-v | --verbose] [--format=<format>] <tag>..."),
+ N_("git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>..."),
NULL
};
diff --git a/help.c b/help.c
index d04542d8261..f1e090a4428 100644
--- a/help.c
+++ b/help.c
@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
int build_options = 0;
const char * const usage[] = {
- N_("git version [<options>]"),
+ N_("git version [--build-options]"),
NULL
};
struct option options[] = {
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 20/34] doc txt & -h consistency: make "rerere" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (18 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 19/34] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 21/34] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
` (14 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
For "rerere" say "pathspec" consistently, and list the subcommands in
the order that they're discussed in the "COMMANDS" section of the
documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-rerere.txt | 2 +-
builtin/rerere.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 9d0e6f53e7e..992b469270c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]
DESCRIPTION
-----------
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 12570537d37..8b7392d5b44 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]"),
NULL,
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 21/34] doc txt & -h consistency: make "read-tree" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (19 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 20/34] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 22/34] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
` (13 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The C version was right to use "()" in place of "[]" around the option
listing, let's update the *.txt version accordingly, and furthermore
list the *.c options in the same order as the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-read-tree.txt | 2 +-
builtin/read-tree.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index b9bfdc0a319..7567955bad8 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index
SYNOPSIS
--------
[verse]
-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index b3a389e1b1f..f4cbe460b97 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)
static const char * const read_tree_usage[] = {
N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
- " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n"
" (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 22/34] doc txt & -h consistency: make "bundle" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (20 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 21/34] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
` (12 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend the -h output to match that of the *.txt output, the differences
were fairly small. In the case of "[<options>]" we only have a few of
them, so let's exhaustively list them as in the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 1b08700bf9e..544c78a5f3a 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,13 +12,14 @@
*/
#define BUILTIN_BUNDLE_CREATE_USAGE \
- N_("git bundle create [<options>] <file> <git-rev-list args>")
+ N_("git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n" \
+ " [--version=<version>] <file> <git-rev-list-args>")
#define BUILTIN_BUNDLE_VERIFY_USAGE \
- N_("git bundle verify [<options>] <file>")
+ N_("git bundle verify [-q | --quiet] <file>")
#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
N_("git bundle list-heads <file> [<refname>...]")
#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
- N_("git bundle unbundle <file> [<refname>...]")
+ N_("git bundle unbundle [--progress] <file> [<refname>...]")
static char const * const builtin_bundle_usage[] = {
BUILTIN_BUNDLE_CREATE_USAGE,
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (21 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 22/34] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 24/34] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
` (11 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Use the "git cmd" form instead of "git-cmd" for both "git
receive-pack" and "git credential-cache--daemon".
For "git-receive-pack" we do have a binary with that name, even when
installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes
of the SYNOPSIS let's use the "git cmd" form like everywhere else. It
can be invoked like that (and our tests do so), the parts of our
documentation that explain when you need to use the dashed form do so,
and use it.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-receive-pack.txt | 2 +-
builtin/credential-cache--daemon.c | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 5c297db1a4b..65ff518ccff 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <git-dir>
+'git receive-pack' <git-dir>
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index d4eb0097d24..f3c89831d4a 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [--debug] <socket-path>",
+ "git credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
{
const char * const usage[] = {
- "git credential-cache--daemon [options] <action>",
+ "git credential-cache--daemon [--debug] <socket-path>",
"",
"credential-cache--daemon is disabled in this build of Git",
NULL
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 24/34] doc txt & -h consistency: add missing options
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (22 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 25/34] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
` (10 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change those built-in commands that were attempting to exhaustively
list the options in the "-h" output to actually do so, and always
have *.txt documentation know about the exhaustive list of options.
Let's also fix the documentation and -h output for those built-in
commands where the *.txt and -h output was a mismatch of missing
options on both sides.
In the case of "interpret-trailers" fixing the missing options reveals
that the *.txt version was implicitly claiming that the command had
two operating modes, which a look at the -h version (and studying the
documentation) will show is not the case.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-commit-graph.txt | 5 ++++-
Documentation/git-interpret-trailers.txt | 5 +++--
builtin/commit-tree.c | 1 +
builtin/fsck.c | 5 ++++-
builtin/hash-object.c | 4 ++--
builtin/init-db.c | 2 ++
builtin/interpret-trailers.c | 2 +-
builtin/rm.c | 4 +++-
8 files changed, 20 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 36fe56c2c71..c8dbceba014 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -10,7 +10,10 @@ SYNOPSIS
--------
[verse]
'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]
+'git commit-graph write' [--object-dir <dir>] [--append]
+ [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
DESCRIPTION
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 6d6197cd0a4..22ff3a603e0 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages
SYNOPSIS
--------
[verse]
-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
-'git interpret-trailers' [<options>] [--parse] [<file>...]
+'git interpret-trailers' [--in-place] [--trim-empty]
+ [(--trailer <token>[(=|:)<value>])...]
+ [--parse] [<file>...]
DESCRIPTION
-----------
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index e4b85d29d56..cc8d584be2f 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,6 +15,7 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
+ N_("git commit-tree <tree> [(-p <parent>)...]"),
N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
" [(-F <file>)...] <tree>"),
NULL
diff --git a/builtin/fsck.c b/builtin/fsck.c
index 41acbc229e4..7436e1a68ef 100644
--- a/builtin/fsck.c
+++ b/builtin/fsck.c
@@ -820,7 +820,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,
}
static char const * const fsck_usage[] = {
- N_("git fsck [<options>] [<object>...]"),
+ N_("git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n"
+ " [--[no-]full] [--strict] [--verbose] [--lost-found]\n"
+ " [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n"
+ " [--[no-]name-objects] [<object>...]"),
NULL
};
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index f7c16802f0c..b5063815020 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
- " [--stdin] [--] <file>..."),
- "git hash-object --stdin-paths",
+ " [--stdin [--literally]] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]"),
NULL
};
const char *type = blob_type;
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 08ba006d55e..dcaaf102eaf 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
static const char *const init_db_usage[] = {
N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--separate-git-dir <git-dir>] [--object-format=<format>]\n"
+ " [-b <branch-name> | --initial-branch=<branch-name>]\n"
" [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 4cf0cf265dc..e58627c72a9 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -15,7 +15,7 @@
static const char * const git_interpret_trailers_usage[] = {
N_("git interpret-trailers [--in-place] [--trim-empty]\n"
" [(--trailer <token>[(=|:)<value>])...]\n"
- " [<file>...]"),
+ " [--parse] [<file>...]"),
NULL
};
diff --git a/builtin/rm.c b/builtin/rm.c
index b6ba859fe42..f0d025a4e23 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -17,7 +17,9 @@
#include "pathspec.h"
static const char * const builtin_rm_usage[] = {
- N_("git rm [<options>] [--] <file>..."),
+ N_("git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n"
+ " [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 25/34] doc txt & -h consistency: make "stash" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (23 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 24/34] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 26/34] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend both the -h output and *.txt to match one another. In this case
the *.txt didn't list the "save" subcommand, and the "-h" was
similarly missing some commands.
Let's also convert the *.c code to use a macro definition, similar to
that used in preceding commits. This avoids duplication.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 5 ++-
builtin/stash.c | 73 ++++++++++++++++++++++++-------------
2 files changed, 52 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index ea16d2eae7c..f4bb6114d91 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -11,12 +11,15 @@ SYNOPSIS
'git stash' list [<log-options>]
'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
'git stash' drop [-q | --quiet] [<stash>]
-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
+'git stash' pop [--index] [-q | --quiet] [<stash>]
+'git stash' apply [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
[-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [<message>]
'git stash' clear
'git stash' create [<message>]
'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
diff --git a/builtin/stash.c b/builtin/stash.c
index 83c9591ea6d..bb5485b4095 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -21,72 +21,95 @@
#define INCLUDE_ALL_FILES 2
+#define BUILTIN_STASH_LIST_USAGE \
+ N_("git stash list [<log-options>]")
+#define BUILTIN_STASH_SHOW_USAGE \
+ N_("git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]")
+#define BUILTIN_STASH_DROP_USAGE \
+ N_("git stash drop [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_POP_USAGE \
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_APPLY_USAGE \
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_BRANCH_USAGE \
+ N_("git stash branch <branchname> [<stash>]")
+#define BUILTIN_STASH_STORE_USAGE \
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
+#define BUILTIN_STASH_PUSH_USAGE \
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
+ " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
+ " [--] [<pathspec>...]]")
+#define BUILTIN_STASH_SAVE_USAGE \
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [<message>]")
+#define BUILTIN_STASH_CREATE_USAGE \
+ N_("git stash create [<message>]")
+#define BUILTIN_STASH_CLEAR_USAGE \
+ "git stash clear"
+
static const char * const git_stash_usage[] = {
- N_("git stash list [<log-options>]"),
- N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q | --quiet] [<stash>]"),
- N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
- N_("git stash branch <branchname> [<stash>]"),
- "git stash clear",
- N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
- " [--] [<pathspec>...]]"),
- N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_LIST_USAGE,
+ BUILTIN_STASH_SHOW_USAGE,
+ BUILTIN_STASH_DROP_USAGE,
+ BUILTIN_STASH_POP_USAGE,
+ BUILTIN_STASH_APPLY_USAGE,
+ BUILTIN_STASH_BRANCH_USAGE,
+ BUILTIN_STASH_PUSH_USAGE,
+ BUILTIN_STASH_SAVE_USAGE,
+ BUILTIN_STASH_CLEAR_USAGE,
+ BUILTIN_STASH_CREATE_USAGE,
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_list_usage[] = {
- N_("git stash list [<options>]"),
+ BUILTIN_STASH_LIST_USAGE,
NULL
};
static const char * const git_stash_show_usage[] = {
- N_("git stash show [<options>] [<stash>]"),
+ BUILTIN_STASH_SHOW_USAGE,
NULL
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_DROP_USAGE,
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_POP_USAGE,
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_APPLY_USAGE,
NULL
};
static const char * const git_stash_branch_usage[] = {
- N_("git stash branch <branchname> [<stash>]"),
+ BUILTIN_STASH_BRANCH_USAGE,
NULL
};
static const char * const git_stash_clear_usage[] = {
- "git stash clear",
+ BUILTIN_STASH_CLEAR_USAGE,
NULL
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--] [<pathspec>...]]"),
+ BUILTIN_STASH_PUSH_USAGE,
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_SAVE_USAGE,
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 26/34] doc txt & -h consistency: make "annotate" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (24 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 25/34] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The cmd_blame() already detected whether it was processing "blame" or
"annotate", but it didn't adjust its usage output accordingly. Let's
do that.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-annotate.txt | 2 +-
builtin/blame.c | 22 ++++++++++++++++------
2 files changed, 17 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index e44a831339d..5ae8aabe0f8 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
SYNOPSIS
--------
[verse]
-'git annotate' [<options>] <file> [<revision>]
+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>
DESCRIPTION
-----------
diff --git a/builtin/blame.c b/builtin/blame.c
index a9fe8cf7a68..71f925e456c 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -30,6 +30,7 @@
#include "tag.h"
static char blame_usage[] = N_("git blame [<options>] [<rev-opts>] [<rev>] [--] <file>");
+static char annotate_usage[] = N_("git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>");
static const char *blame_opt_usage[] = {
blame_usage,
@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {
NULL
};
+static const char *annotate_opt_usage[] = {
+ annotate_usage,
+ "",
+ N_("<rev-opts> are documented in git-rev-list(1)"),
+ NULL
+};
+
static int longest_file;
static int longest_author;
static int max_orig_digits;
@@ -899,6 +907,8 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
long anchor;
const int hexsz = the_hash_algo->hexsz;
long num_lines = 0;
+ const char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;
+ const char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
setup_default_color_by_age();
git_config(git_blame_config, &output_option);
@@ -914,7 +924,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
parse_options_start(&ctx, argc, argv, prefix, options,
PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);
for (;;) {
- switch (parse_options_step(&ctx, options, blame_opt_usage)) {
+ switch (parse_options_step(&ctx, options, opt_usage)) {
case PARSE_OPT_NON_OPTION:
case PARSE_OPT_UNKNOWN:
break;
@@ -934,7 +944,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
ctx.argv[0] = "--children";
reverse = 1;
}
- parse_revision_opt(&revs, &ctx, options, blame_opt_usage);
+ parse_revision_opt(&revs, &ctx, options, opt_usage);
}
parse_done:
revision_opts_finish(&revs);
@@ -1040,7 +1050,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
switch (argc - dashdash_pos - 1) {
case 2: /* (1b) */
if (argc != 4)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
/* reorder for the new way: <rev> -- <path> */
argv[1] = argv[3];
argv[3] = argv[2];
@@ -1051,11 +1061,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
argv[argc] = NULL;
break;
default:
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
}
} else {
if (argc < 2)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
if (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */
path = add_prefix(prefix, argv[1]);
argv[1] = argv[2];
@@ -1113,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
nth_line_cb, &sb, lno, anchor,
&bottom, &top, sb.path,
the_repository->index))
- usage(blame_usage);
+ usage(str_usage);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more"
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (25 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 26/34] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 28/34] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Correct uses of "<label>..." where we really meant to say
"[<label>...]", i.e. the command in question taken an optional set of
"<label>". As the CodingGuidelines notes "[o]ptional parts [should be]
enclosed in square brackets".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 2 +-
builtin/clean.c | 2 +-
builtin/commit.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 8347c6eed79..160d08b86bb 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/clean.c b/builtin/clean.c
index 6f039f555b2..40ff2c578de 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]"),
NULL
};
diff --git a/builtin/commit.c b/builtin/commit.c
index fcf9c85947e..21ad4ccbf87 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {
};
static const char * const builtin_status_usage[] = {
- N_("git status [<options>] [--] <pathspec>..."),
+ N_("git status [<options>] [--] [<pathspec>...]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 28/34] doc txt & -h consistency: make "diff-tree" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (26 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 29/34] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "diff-tree -h" output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-tree.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 23f58702fa0..85e8c81e594 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)
}
static const char diff_tree_usage[] =
-"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
-"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n"
+" [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\n"
+" [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 29/34] doc txt & -h consistency: make "commit" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (27 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 28/34] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 30/34] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "-h" output of "git commit" consistent with the *.txt version
by exhaustively listing the options that it takes.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/commit.c | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/builtin/commit.c b/builtin/commit.c
index 21ad4ccbf87..64f420bcbf6 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -40,7 +40,14 @@
#include "pretty.h"
static const char * const builtin_commit_usage[] = {
- N_("git commit [<options>] [--] <pathspec>..."),
+ N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\n"
+ " [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\n"
+ " [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\n"
+ " [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\n"
+ " [--date=<date>] [--cleanup=<mode>] [--[no-]status]\n"
+ " [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 30/34] reflog doc: list real subcommands up-front
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (28 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 29/34] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 31/34] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the "git reflog" documentation to exhaustively list the
subcommands it accepts in the SYNOPSIS, as opposed to leaving that for
a "[verse]" in the DESCRIPTION section. This documentation style was
added in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how
other commands which take subcommands are documented.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 0537d4645be..ec64cbff4c6 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -8,14 +8,6 @@ git-reflog - Manage reflog information
SYNOPSIS
--------
-[verse]
-'git reflog' <subcommand> <options>
-
-DESCRIPTION
------------
-The command takes various subcommands, and different options
-depending on the subcommand:
-
[verse]
'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
@@ -25,6 +17,10 @@ depending on the subcommand:
[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
'git reflog exists' <ref>
+DESCRIPTION
+-----------
+This command manages the information recorded in the reflogs.
+
Reference logs, or "reflogs", record when the tips of branches and
other references were updated in the local repository. Reflogs are
useful in various Git commands, to specify the old value of a
@@ -33,7 +29,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point
to one week ago in this local repository", and so on. See
linkgit:gitrevisions[7] for more details.
-This command manages the information recorded in the reflogs.
+The command takes various subcommands, and different options
+depending on the subcommand:
The "show" subcommand (which is also the default, in the absence of
any subcommands) shows the log of the reference provided in the
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 31/34] worktree: define subcommand -h in terms of command -h
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (29 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 30/34] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 32/34] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git worktree" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------
1 file changed, 84 insertions(+), 25 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 5bfc18e5a24..ba6846c3788 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -15,15 +15,72 @@
#include "worktree.h"
#include "quote.h"
-static const char * const worktree_usage[] = {
- N_("git worktree add [<options>] <path> [<commit-ish>]"),
- N_("git worktree list [<options>]"),
- N_("git worktree lock [<options>] <path>"),
- N_("git worktree move <worktree> <new-path>"),
- N_("git worktree prune [<options>]"),
- N_("git worktree remove [<options>] <worktree>"),
- N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <worktree>"),
+#define BUILTIN_WORKTREE_ADD_USAGE \
+ N_("git worktree add [<options>] <path> [<commit-ish>]")
+#define BUILTIN_WORKTREE_LIST_USAGE \
+ N_("git worktree list [<options>]")
+#define BUILTIN_WORKTREE_LOCK_USAGE \
+ N_("git worktree lock [<options>] <path>")
+#define BUILTIN_WORKTREE_MOVE_USAGE \
+ N_("git worktree move <worktree> <new-path>")
+#define BUILTIN_WORKTREE_PRUNE_USAGE \
+ N_("git worktree prune [<options>]")
+#define BUILTIN_WORKTREE_REMOVE_USAGE \
+ N_("git worktree remove [<options>] <worktree>")
+#define BUILTIN_WORKTREE_REPAIR_USAGE \
+ N_("git worktree repair [<path>...]")
+#define BUILTIN_WORKTREE_UNLOCK_USAGE \
+ N_("git worktree unlock <worktree>")
+
+static const char * const git_worktree_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ BUILTIN_WORKTREE_LIST_USAGE,
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_add_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ NULL,
+};
+
+static const char * const git_worktree_list_usage[] = {
+ BUILTIN_WORKTREE_LIST_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_lock_usage[] = {
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_move_usage[] = {
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_prune_usage[] = {
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_remove_usage[] = {
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_repair_usage[] = {
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_unlock_usage[] = {
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
NULL
};
@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,
+ 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_prune_usage, options);
prune_worktrees();
return 0;
}
@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)
memset(&opts, 0, sizeof(opts));
opts.checkout = 1;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);
if (!!opts.detach + !!new_branch + !!new_branch_force > 1)
die(_("options '%s', '%s', and '%s' cannot be used together"), "-b", "-B", "--detach");
if (lock_reason && !keep_locked)
@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)
opts.keep_locked = _("added with --lock");
if (ac < 1 || ac > 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_add_usage, options);
path = prefix_filename(prefix, av[0]);
branch = ac < 2 ? "HEAD" : av[1];
@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_list_usage, options);
else if (verbose && porcelain)
die(_("options '%s' and '%s' cannot be used together"), "--verbose", "--porcelain");
else if (!line_terminator && !porcelain)
@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)
};
struct worktree **worktrees, *wt;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_lock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)
struct worktree **worktrees, *wt;
int ret;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_unlock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
char *path;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_move_usage,
+ 0);
if (ac != 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_move_usage, options);
path = prefix_filename(prefix, av[1]);
strbuf_addstr(&dst, path);
@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
int ret = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_remove_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)
};
int rc = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);
p = ac > 0 ? av : self;
for (; *p; p++)
repair_worktree_at_path(*p, report_repair, &rc);
@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)
if (!prefix)
prefix = "";
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);
return fn(ac, av, prefix);
}
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 32/34] doc txt & -h consistency: make "worktree" consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (30 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 31/34] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "worktree" -h output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index ba6846c3788..4a24d53be15 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -16,17 +16,18 @@
#include "quote.h"
#define BUILTIN_WORKTREE_ADD_USAGE \
- N_("git worktree add [<options>] <path> [<commit-ish>]")
+ N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \
+ " [-b <new-branch>] <path> [<commit-ish>]")
#define BUILTIN_WORKTREE_LIST_USAGE \
- N_("git worktree list [<options>]")
+ N_("git worktree list [-v | --porcelain [-z]]")
#define BUILTIN_WORKTREE_LOCK_USAGE \
- N_("git worktree lock [<options>] <path>")
+ N_("git worktree lock [--reason <string>] <worktree>")
#define BUILTIN_WORKTREE_MOVE_USAGE \
N_("git worktree move <worktree> <new-path>")
#define BUILTIN_WORKTREE_PRUNE_USAGE \
- N_("git worktree prune [<options>]")
+ N_("git worktree prune [-n] [-v] [--expire <expire>]")
#define BUILTIN_WORKTREE_REMOVE_USAGE \
- N_("git worktree remove [<options>] <worktree>")
+ N_("git worktree remove [-f] <worktree>")
#define BUILTIN_WORKTREE_REPAIR_USAGE \
N_("git worktree repair [<path>...]")
#define BUILTIN_WORKTREE_UNLOCK_USAGE \
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (31 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 32/34] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 15:39 ` [PATCH v5 34/34] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
2022-10-13 16:33 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Junio C Hamano
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
There's been a lot of incremental effort to make the SYNOPSIS output
in our documentation consistent with the -h output,
e.g. cbe485298bf (git reflog [expire|delete]: make -h output
consistent with SYNOPSIS, 2022-03-17) is one recent example, but that
effort has been an uphill battle due to the lack of regression
testing.
This adds such regression testing, we can parse out the SYNOPSIS
output with "sed", and it turns out it's relatively easy to normalize
it and the "-h" output to match on another.
We now ensure that we won't have regressions when it comes to the list
of commands in "expect_help_to_match_txt" below, and in subsequent
commits we'll make more of them consistent.
The naïve parser here gets quite a few things wrong, but it doesn't
need to be perfect, just good enough that we can compare /some/ of
this help output. There's no cases where the output would match except
for the parser's stupidity, it's all cases of e.g. comparing the *.txt
to non-parse_options() output.
Since that output is wildly different than the *.txt anyway let's
leave this for now, we can fix the parser some other time, or it won't
become necessary as we'll e.g. convert more things to using
parse_options().
Having a special-case for "merge-tree"'s 1f0c3a29da3 (merge-tree:
implement real merges, 2022-06-18) is a bit ugly, but preferred to
blessing that " (deprecated)" pattern for other commands. We'd
probably want to add some other way of marking deprecated commands in
the SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is
indistinguishable from the command taking an optional literal
"deprecated" string as an argument.
Some of the issues that are left:
* "git show -h", "git whatchanged -h" and "git reflog --oneline -h"
all showing "git log" and "git show" usage output. I.e. the
"builtin_log_usage" in builtin/log.c doesn't take into account what
command we're running.
* Commands which implement subcommands such as like
"multi-pack-index", "notes", "remote" etc. having their subcommands
in a very different order in the *.txt and *.c. Fixing it would
require some verbose diffs, so it's been left alone for now.
* Commands such as "format-patch" have a very long argument list in
the *.txt, but just "[<options>]" in the *.c.
What to do about these has been left out of this series, except to
the extent that preceding commits changed "[<options>]" (or
equivalent) to the list of options in cases where that list of
options was tiny, or we clearly meant to exhaustively list the
options in both *.txt and *.c.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 69 ++++++++++++++++++++++++++++++++++++-
t/t0450/txt-help-mismatches | 58 +++++++++++++++++++++++++++++++
2 files changed, 126 insertions(+), 1 deletion(-)
create mode 100644 t/t0450/txt-help-mismatches
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index efd00cfc51a..8fd20b6dba6 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -1,6 +1,9 @@
#!/bin/sh
-test_description='assert (unbuilt) Documentation/*.txt and -h output'
+test_description='assert (unbuilt) Documentation/*.txt and -h output
+
+Run this with --debug to see a summary of where we still fail to make
+the two versions consistent with one another.'
TEST_PASSES_SANITIZE_LEAK=true
. ./test-lib.sh
@@ -9,6 +12,14 @@ test_expect_success 'setup: list of builtins' '
git --list-cmds=builtins >builtins
'
+test_expect_success 'list of txt and help mismatches is sorted' '
+ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
+ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ BUG "please keep the list of txt and help mismatches sorted"
+ fi
+'
+
help_to_synopsis () {
builtin="$1" &&
out_dir="out/$builtin" &&
@@ -49,6 +60,9 @@ txt_to_synopsis () {
/^$/d;
/^\[verse\]$/d;
+ s/{litdd}/--/g;
+ s/'\''\(git[ a-z-]*\)'\''/\1/g;
+
p;
}' \
<"$b2t" >"$out" &&
@@ -61,6 +75,15 @@ check_dashed_labels () {
HT=" "
+align_after_nl () {
+ builtin="$1" &&
+ len=$(printf "git %s " "$builtin" | wc -c) &&
+ pad=$(printf "%${len}s" "") &&
+
+ sed "s/^[ $HT][ $HT]*/$pad/"
+}
+
+test_debug '>failing'
while read builtin
do
# -h output assertions
@@ -85,6 +108,50 @@ do
test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
check_dashed_labels "$(txt_to_synopsis "$builtin")"
'
+
+ # *.txt output consistency assertions
+ result=
+ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ result=failure
+ else
+ result=success
+ fi &&
+ test_expect_$result "$preq" "$builtin -h output and SYNOPSIS agree" '
+ t2s="$(txt_to_synopsis "$builtin")" &&
+ if test "$builtin" = "merge-tree"
+ then
+ test_when_finished "rm -f t2s.new" &&
+ sed -e '\''s/ (deprecated)$//g'\'' <"$t2s" >t2s.new
+ t2s=t2s.new
+ fi &&
+ h2s="$(help_to_synopsis "$builtin")" &&
+
+ # The *.txt and -h use different spacing for the
+ # alignment of continued usage output, normalize it.
+ align_after_nl "$builtin" <"$t2s" >txt &&
+ align_after_nl "$builtin" <"$h2s" >help &&
+ test_cmp txt help
+ '
+
+ if test_have_prereq "$preq" && test -e txt && test -e help
+ then
+ test_debug '
+ if test_cmp txt help >cmp 2>/dev/null
+ then
+ echo "=== DONE: $builtin ==="
+ else
+ echo "=== TODO: $builtin ===" &&
+ cat cmp
+ fi >>failing
+ '
+
+ # Not in test_expect_success in case --run is being
+ # used with --debug
+ rm -f txt help tmp 2>/dev/null
+ fi
done <builtins
+test_debug 'say "$(cat failing)"'
+
test_done
diff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches
new file mode 100644
index 00000000000..a0777acd667
--- /dev/null
+++ b/t/t0450/txt-help-mismatches
@@ -0,0 +1,58 @@
+add
+am
+apply
+archive
+bisect
+blame
+branch
+check-ref-format
+checkout
+checkout-index
+clone
+column
+config
+credential
+credential-cache
+credential-store
+fast-export
+fast-import
+fetch-pack
+fmt-merge-msg
+for-each-ref
+format-patch
+fsck-objects
+fsmonitor--daemon
+gc
+grep
+index-pack
+init-db
+log
+ls-files
+ls-tree
+mailinfo
+mailsplit
+maintenance
+merge
+merge-file
+merge-index
+merge-one-file
+multi-pack-index
+name-rev
+notes
+pack-objects
+push
+range-diff
+rebase
+remote
+remote-ext
+remote-fd
+repack
+reset
+restore
+rev-parse
+show
+stage
+switch
+update-index
+update-ref
+whatchanged
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v5 34/34] tests: assert consistent whitespace in -h output
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (32 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
@ 2022-10-13 15:39 ` Ævar Arnfjörð Bjarmason
2022-10-13 16:33 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Junio C Hamano
34 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-13 15:39 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test for the *.txt and *.c output assertions which asserts that
for "-h" lines that aren't the "usage: " or " or: " lines they start
with the same amount of whitespace. This ensures that we won't have
buggy output like:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
Which should instead be like this, i.e. the options lines should be
aligned:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
It would be better to be able to use "test_cmp" here, i.e. to
construct the output we expect, and compare it against the actual
output.
For most built-in commands this would be rather straightforward. In
"t0450-txt-doc-vs-help.sh" we already compute the whitespace that a
"git-$builtin" needs, and strip away "usage: " or " or: " from the
start of lines. The problem is:
* For commands that implement subcommands, such as "git bundle", we
don't know whether e.g. "git bundle create" is the subcommand
"create", or the argument "create" to "bundle" for the purposes of
alignment.
We *do* have that information from the *.txt version, since the
part within the ''-quotes should be the command & subcommand, but
that isn't consistent (e.g. see "git bundle" and "git
commit-graph", only the latter is correct), and parsing that out
would be non-trivial.
* If we were to make this stricter we have various
non-parse_options() users (e.g. "git diff-tree") that don't have the
nicely aligned output which we've had since
4631cfc20bd (parse-options: properly align continued usage output,
2021-09-21).
So rather than make perfect the enemy of the good let's assert that
for those lines that are indented they should all use the same
indentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 8fd20b6dba6..cd3969e852b 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -96,6 +96,21 @@ do
check_dashed_labels "$(help_to_synopsis "$builtin")"
'
+ test_expect_success "$builtin -h output has consistent spacing" '
+ h2s="$(help_to_synopsis "$builtin")" &&
+ sed -n \
+ -e "/^ / {
+ s/[^ ].*//;
+ p;
+ }" \
+ <"$h2s" >help &&
+ sort -u help >help.ws &&
+ if test -s help.ws
+ then
+ test_line_count = 1 help.ws
+ fi
+ '
+
txt="$(builtin_to_txt "$builtin")" &&
preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
--
2.38.0.1085.gb7e61c3016c
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v5 00/34] doc/UX: make txt & -h output more consistent
2022-10-13 15:38 ` [PATCH v5 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
` (33 preceding siblings ...)
2022-10-13 15:39 ` [PATCH v5 34/34] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
@ 2022-10-13 16:33 ` Junio C Hamano
34 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-13 16:33 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> We are currently wildly inconsistent in whether the SYNOPSIS in the
> manual page matches the first line of the -h output, and as we add new
> options we routinely forget to add them to one or the other (or both).
>
> Without a more complex approach it's hard to do something about the
> "or both" case. But we can rather easily test whether the -h output
> matches the *.txt version, and report differences.
Nice.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v4 00/34] doc/UX: make txt & -h output more consistent
2022-09-30 18:07 ` [PATCH v3 00/36] " Ævar Arnfjörð Bjarmason
` (36 preceding siblings ...)
2022-10-04 13:20 ` [PATCH v3 00/34] doc/UX: make txt & -h output more consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
` (33 more replies)
37 siblings, 34 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
[I sent the first 3 patches & CL of this v4 as a "v3" in
https://lore.kernel.org/git/cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com/;
sorry. Here's the whole series, correctly labeled as v4]
We are currently wildly inconsistent in whether the SYNOPSIS in the
manual page matches the first line of the -h output, and as we add new
options we routinely forget to add them to one or the other (or both).
Without a more complex approach it's hard to do something about the
"or both" case. But we can rather easily test whether the -h output
matches the *.txt version, and report differences.
As this series shows that allows us to fix a lot of issues we've
effectively already "fixed", we just fixed them in one version, but
not the other.
For the rest of the general overview (the first paragraphs are
copy/pasted) see the v1 at:
https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/ [1];
For v3 see:
http://lore.kernel.org/git/cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com
Changes since v3:
* Added a commit to put a small portion of the the new tests first,
we then add a bit to it as we go along.
* Squashed some changes as requested, now some of the "doc txt & -h
consistency" commits have changes that were previously split up,
but that's noted in the commit message.
* Ejected the "blame" usage_msg_optf() change, instead the relevant
later commit just supports both usage() and usage_with_options().
* Consistently use [<options>], not "[<options...]"
* Various squshes/fix-ups suggested by Eric & Junio, thanks both!
* The new test now runs much faster, since we cache the "sed"
commands that extract the "-h" and "*.txt" output
Ævar Arnfjörð Bjarmason (34):
tests: assert *.txt SYNOPSIS and -h output
CodingGuidelines: update and clarify command-line conventions
builtin/bundle.c: indent with tabs
bundle: define subcommand -h in terms of command -h
doc SYNOPSIS: don't use ' for subcommands
doc SYNOPSIS: consistently use ' for commands
built-ins: consistently add "\n" between "usage" and options
doc txt & -h consistency: word-wrap
doc txt & -h consistency: fix incorrect alternates syntax
doc txt & -h consistency: add "-z" to cat-file "-h"
doc txt & -h consistency: balance unbalanced "[" and "]"
doc txt & -h consistency: correct padding around "[]()"
stash doc SYNOPSIS & -h: correct padding around "[]()"
doc txt & -h consistency: use "<options>", not "<options>..."
doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
doc txt & -h consistency: fix mismatching labels
doc txt & -h consistency: add or fix optional "--" syntax
doc txt & -h consistency: make output order consistent
doc txt & -h consistency: add missing options and labels
doc txt & -h consistency: make "rerere" consistent
doc txt & -h consistency: make "read-tree" consistent
doc txt & -h consistency: make "bundle" consistent
doc txt & -h consistency: use "git foo" form, not "git-foo"
doc txt & -h consistency: add missing options
doc txt & -h consistency: make "stash" consistent
doc txt & -h consistency: make "annotate" consistent
doc txt & -h consistency: use "[<label>...]" for "zero or more"
doc txt & -h consistency: make "diff-tree" consistent
doc txt & -h consistency: make "commit" consistent
reflog doc: list real subcommands up-front
worktree: define subcommand -h in terms of command -h
doc txt & -h consistency: make "worktree" consistent
tests: start asserting that *.txt SYNOPSIS matches -h output
tests: assert consistent whitespace in -h output
Documentation/CodingGuidelines | 14 +-
Documentation/git-annotate.txt | 2 +-
Documentation/git-clean.txt | 8 +-
Documentation/git-commit-graph.txt | 5 +-
.../git-credential-cache--daemon.txt | 4 +-
Documentation/git-diff-files.txt | 2 +-
Documentation/git-fast-export.txt | 2 +-
Documentation/git-hash-object.txt | 3 +-
Documentation/git-interpret-trailers.txt | 5 +-
Documentation/git-merge-base.txt | 4 +-
Documentation/git-mv.txt | 4 +-
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-read-tree.txt | 2 +-
Documentation/git-receive-pack.txt | 4 +-
Documentation/git-reflog.txt | 17 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-rev-list.txt | 2 +-
Documentation/git-send-pack.txt | 5 +-
Documentation/git-show-branch.txt | 4 +-
Documentation/git-show-ref.txt | 4 +-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-stash.txt | 17 +-
Documentation/git-status.txt | 2 +-
Documentation/git-tag.txt | 18 +-
Documentation/git-update-server-info.txt | 8 +-
Documentation/git-upload-archive.txt | 4 +-
Documentation/git-var.txt | 2 +-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
Documentation/git-worktree.txt | 3 +-
builtin/blame.c | 22 ++-
builtin/bugreport.c | 3 +-
builtin/bundle.c | 38 ++--
builtin/cat-file.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 10 +-
builtin/commit-tree.c | 5 +-
builtin/commit.c | 11 +-
builtin/credential-cache--daemon.c | 4 +-
builtin/describe.c | 5 +-
builtin/diagnose.c | 3 +-
builtin/diff-files.c | 1 +
builtin/diff-index.c | 3 +-
builtin/diff-tree.c | 6 +-
builtin/diff.c | 3 +-
builtin/for-each-repo.c | 2 +-
builtin/fsck.c | 5 +-
builtin/hash-object.c | 5 +-
builtin/help.c | 2 +-
builtin/init-db.c | 5 +-
builtin/interpret-trailers.c | 4 +-
builtin/ls-remote.c | 2 +-
builtin/merge-base.c | 2 +-
builtin/pack-objects.c | 4 +-
builtin/pack-redundant.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/read-tree.c | 4 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 3 +-
builtin/revert.c | 9 +-
builtin/rm.c | 4 +-
builtin/send-pack.c | 1 +
builtin/show-branch.c | 3 +-
builtin/show-ref.c | 4 +-
builtin/sparse-checkout.c | 2 +-
builtin/stash.c | 73 +++++---
builtin/symbolic-ref.c | 5 +-
builtin/tag.c | 10 +-
builtin/unpack-file.c | 2 +-
builtin/update-server-info.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/upload-pack.c | 3 +-
builtin/verify-commit.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/verify-tag.c | 2 +-
builtin/worktree.c | 110 ++++++++---
help.c | 2 +-
t/helper/test-proc-receive.c | 2 +-
t/t0450-txt-doc-vs-help.sh | 172 ++++++++++++++++++
t/t0450/txt-help-mismatches | 58 ++++++
82 files changed, 593 insertions(+), 198 deletions(-)
create mode 100755 t/t0450-txt-doc-vs-help.sh
create mode 100644 t/t0450/txt-help-mismatches
Range-diff against v3:
-: ----------- > 1: f76804fe9ae tests: assert *.txt SYNOPSIS and -h output
1: 1611913e321 = 2: c95d3b9ad42 CodingGuidelines: update and clarify command-line conventions
2: b2d76494a34 = 3: b7c98a40393 builtin/bundle.c: indent with tabs
3: 953a72abee1 = 4: 522d7fbb0a3 bundle: define subcommand -h in terms of command -h
4: a8312c50f01 < -: ----------- blame: use a more detailed usage_msg_optf() error on bad -L
5: ec977f7c8fe = 5: ac437d4eee5 doc SYNOPSIS: don't use ' for subcommands
6: b0ae035500c = 6: f20cbb661c6 doc SYNOPSIS: consistently use ' for commands
8: e9924890620 = 7: ecdc14f6dfe built-ins: consistently add "\n" between "usage" and options
10: 1a02f7c76cd ! 8: 1b9b6a91916 doc txt & -h consistency: word-wrap
@@ Commit message
doc txt & -h consistency: word-wrap
Change the documentation and -h output for those built-in commands
- where the *.txt and -h output didn't match as far as word-wrapping was
- concerned.
+ where both the -h output and *.txt were lacking in word-wrapping.
+
+ There are many more built-ins that could use this treatment, this
+ change is narrowed to those where this whitespace change is needed to
+ make the -h and *.txt consistent in the end.
+
+ In the case of "Documentation/git-hash-object.txt" and
+ "builtin/hash-object.c" this is not a "doc txt & -h consistency"
+ change, as we're changing both versions, doing so here makes a
+ subsequent change smaller.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+ ## Documentation/git-hash-object.txt ##
+@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file
+ SYNOPSIS
+ --------
+ [verse]
+-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
++'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
++ [--stdin [--literally]] [--] <file>...
+ 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
+
+ DESCRIPTION
+
## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees
SYNOPSIS
@@ builtin/diagnose.c
};
+ ## builtin/hash-object.c ##
+@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
+ int cmd_hash_object(int argc, const char **argv, const char *prefix)
+ {
+ static const char * const hash_object_usage[] = {
+- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
++ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
++ " [--stdin] [--] <file>..."),
+ "git hash-object --stdin-paths",
+ NULL
+ };
+
## builtin/init-db.c ##
@@ builtin/init-db.c: static int shared_callback(const struct option *opt, const char *arg, int unset)
}
7: 829bdf58499 ! 9: f4598ca1899 doc SYNOPSIS & -h: fix incorrect alternates syntax
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- doc SYNOPSIS & -h: fix incorrect alternates syntax
+ doc txt & -h consistency: fix incorrect alternates syntax
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
- This issue has been with us in both the "-h" and *.txt versions since
- bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
+ This syntax issue for "bugreport" originated in
+ 238b439d698 (bugreport: add tool to generate debugging info,
+ 2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
+ create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
+ "bugreport" documentation and code.
- There are also issues with the alternates syntax for "bugreport" and
- "diagnose", but in those cases only for one of *.c or *.txt, not
- both. Those issues will be fixed in a subsequent "consistency" commit.
+ In the case of "Documentation/git-stash.txt" and "builtin/stash.c"
+ this is not a "doc txt & -h consistency" change, as we're changing
+ both versions, doing so here makes a subsequent change smaller.
+
+ In that case fix the incorrect "[-o | --option <argument>]" syntax,
+ which should be "[(-o | --option) <argument>]", we were previously
+ claiming that only the long option accepted the "<argument>", which
+ isn't what we meant.
+
+ The "stash" issue has been with us in both the "-h" and *.txt versions
+ since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
+
+ We could claim that this isn't a syntax issue if a "vertical bar binds
+ tighter than option and its argument", but such a rule would change
+ e.g. this "cat-file" SYNOPSIS example to mean something we don't:
+
+ ... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
+
+ We have various other examples where the post-image here is already
+ used, e.g. for "format-patch" ("-o"), "grep" ("-m"),
+ "submodule" ("set-branch -b") etc.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-stash.txt: stash index (e.g. the integer `n` is equivalent to
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
+ ## builtin/bugreport.c ##
+@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, int nongit)
+ }
+
+ static const char * const bugreport_usage[] = {
+- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
++ N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
+ " [--diagnose[=<mode>]"),
+ NULL
+ };
+
+ ## builtin/diagnose.c ##
+@@
+ #include "diagnose.h"
+
+ static const char * const diagnose_usage[] = {
+- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
++ N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
+ " [--mode=<mode>]"),
+ NULL
+ };
+
## builtin/stash.c ##
@@ builtin/stash.c: static const char * const git_stash_usage[] = {
N_("git stash branch <branchname> [<stash>]"),
9: 516af07e8a8 < -: ----------- doc SYNOPSIS & -h: word-wrap
11: 7794c3d6ef5 < -: ----------- doc txt & -h consistency: fix incorrect alternates syntax
12: 357a228000c = 10: 0e955f294cd doc txt & -h consistency: add "-z" to cat-file "-h"
13: 57cbaee9826 = 11: aa2f9325839 doc txt & -h consistency: balance unbalanced "[" and "]"
14: a29af2dcc4f = 12: 009a0e586e9 doc txt & -h consistency: correct padding around "[]()"
15: 589705cf6fa = 13: b568189532f stash doc SYNOPSIS & -h: correct padding around "[]()"
16: db850539d2a ! 14: e5cb5c91b82 doc txt & -h consistency: use "<options>", not "<options>..."
@@ Commit message
In the case of "mv" and "sparse-checkout" let's add the missing "[]"
to indicate that these are optional.
+ In the case of "t/helper/test-proc-receive.c" there is no *.txt
+ version, making it the only hunk in this commit that's not a "doc txt
+ & -h consistency" change.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-mv.txt ##
@@ builtin/sparse-checkout.c
NULL
};
+
+ ## t/helper/test-proc-receive.c ##
+@@
+ #include "test-tool.h"
+
+ static const char *proc_receive_usage[] = {
+- "test-tool proc-receive [<options>...]",
++ "test-tool proc-receive [<options>]",
+ NULL
+ };
+
17: 041aa64f3c7 ! 15: 403e7ceb449 t/helper/test-proc-receive.c: use "<options>", not "<options>..."
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- t/helper/test-proc-receive.c: use "<options>", not "<options>..."
+ doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
- As in a preceding commit use "<options>", not "<options>...", in this
- case there is no *.txt version, but let's fix this one too while we're
- at it.
+ Change "builtin/credential-cache--daemon.c" to use "<socket-path>" not
+ "<socket_path>" in a placeholder label, almost all of our
+ documentation uses this form.
+
+ This is now consistent with the "If a placeholder has multiple words,
+ they are separated by dashes" guideline added in
+ 9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's
+ add a now-passing test to assert that that's the case.
+
+ To do this we need to introduce a very sed-powered parser to extract
+ the SYNOPSIS from the *.txt, and handle not all commands with "-h"
+ having a corresponding *.txt (e.g. "bisect--helper"). We'll still want
+ to handle syntax edge cases in the *.txt in subsequent commits for
+ other checks, but let's do that then.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## t/helper/test-proc-receive.c ##
-@@
- #include "test-tool.h"
+ ## builtin/credential-cache--daemon.c ##
+@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
+ const char *socket_path;
+ int ignore_sighup = 0;
+ static const char *usage[] = {
+- "git-credential-cache--daemon [opts] <socket_path>",
++ "git-credential-cache--daemon [opts] <socket-path>",
+ NULL
+ };
+ int debug = 0;
+
+ ## t/t0450-txt-doc-vs-help.sh ##
+@@ t/t0450-txt-doc-vs-help.sh: help_to_synopsis () {
+ echo "$out"
+ }
+
++builtin_to_txt () {
++ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
++}
++
++txt_to_synopsis () {
++ builtin="$1" &&
++ out_dir="out/$builtin" &&
++ out="$out_dir/txt.synopsis" &&
++ if test -f "$out"
++ then
++ echo "$out" &&
++ return 0
++ fi &&
++ b2t="$(builtin_to_txt "$builtin")" &&
++ sed -n \
++ -e '/^\[verse\]$/,/^$/ {
++ /^$/d;
++ /^\[verse\]$/d;
++
++ p;
++ }' \
++ <"$b2t" >"$out" &&
++ echo "$out"
++}
++
++check_dashed_labels () {
++ ! grep -E "<[^>_-]+_" "$1"
++}
++
+ HT=" "
- static const char *proc_receive_usage[] = {
-- "test-tool proc-receive [<options>...]",
-+ "test-tool proc-receive [<options>]",
- NULL
- };
+ while read builtin
+@@ t/t0450-txt-doc-vs-help.sh: do
+ h2s="$(help_to_synopsis "$builtin")" &&
+ ! grep "$HT" "$h2s"
+ '
++
++ test_expect_success "$builtin -h output has dashed labels" '
++ check_dashed_labels "$(help_to_synopsis "$builtin")"
++ '
++
++ txt="$(builtin_to_txt "$builtin")" &&
++ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
++
++ if test -f "$txt"
++ then
++ test_set_prereq "$preq"
++ fi &&
++
++ # *.txt output assertions
++ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
++ check_dashed_labels "$(txt_to_synopsis "$builtin")"
++ '
+ done <builtins
+ test_done
18: 3a439c4401d ! 16: 563ccaab6a9 doc txt & -h consistency: fix mismatching labels
@@ Commit message
corresponding -h output where our translatable labels didn't match
up.
+ In some cases we need to adjust the prose that follows the SYNOPSIS
+ accordingly, as it refers back to the changed label.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-clean.txt ##
@@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
+-are affected.
+If any optional `<pathspec>...` arguments are given, only those paths
- are affected.
++that match the pathspec are affected.
OPTIONS
-------
@@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - T
DESCRIPTION
-----------
+@@ Documentation/git-credential-cache--daemon.txt: DESCRIPTION
+ NOTE: You probably don't want to invoke this command yourself; it is
+ started automatically when you use linkgit:git-credential-cache[1].
+
+-This command listens on the Unix domain socket specified by `<socket>`
++This command listens on the Unix domain socket specified by `<socket-path>`
+ for `git-credential-cache` clients. Clients may store and retrieve
+ credentials. Each credential is held for a timeout specified by the
+ client; once no credentials are held, the daemon exits.
## Documentation/git-mv.txt ##
@@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a symlink
@@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a syml
DESCRIPTION
-----------
+@@ Documentation/git-mv.txt: OPTIONS
+ -------
+ -f::
+ --force::
+- Force renaming or moving of a file even if the target exists
++ Force renaming or moving of a file even if the <destination> exists.
+ -k::
+ Skip move or rename actions which would lead to an error
+ condition. An error happens when a source is neither existing nor
## Documentation/git-receive-pack.txt ##
@@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed into the repository
@@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed in
DESCRIPTION
-----------
+@@ Documentation/git-receive-pack.txt: its behavior, see linkgit:git-config[1].
+
+ OPTIONS
+ -------
+-<directory>::
++<git-dir>::
+ The repository to sync into.
+
+ --http-backend-info-refs::
## Documentation/git-tag.txt ##
@@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object signed with GPG
@@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
+@@ Documentation/git-tag.txt: to delete, list or verify tags.
+
+ Unless `-f` is given, the named tag must not yet exist.
+
+-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
++If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
+ creates a 'tag' object, and requires a tag message. Unless
+ `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
+ in the tag message.
+
+-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
++If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
+ are absent, `-a` is implied.
+
+ Otherwise, a tag reference that points directly at the given object
+ (i.e., a lightweight tag) is created.
+
+ A GnuPG signed tag object will be created when `-s` or `-u
+-<keyid>` is used. When `-u <keyid>` is not used, the
++<key-id>` is used. When `-u <key-id>` is not used, the
+ committer identity for the current user is used to find the
+ GnuPG key for signing. The configuration variable `gpg.program`
+ is used to specify custom GnuPG binary.
+@@ Documentation/git-tag.txt: OPTIONS
+ Override `tag.gpgSign` configuration variable that is
+ set to force each and every tag to be signed.
+
+--u <keyid>::
+---local-user=<keyid>::
++-u <key-id>::
++--local-user=<key-id>::
+ Make a GPG-signed tag, using the given key.
+
+ -f::
+@@ Documentation/git-tag.txt: This option is only applicable when listing tags without annotation lines.
+ Use the given tag message (instead of prompting).
+ If multiple `-m` options are given, their values are
+ concatenated as separate paragraphs.
+- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
++ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ is given.
+
+ -F <file>::
+ --file=<file>::
+ Take the tag message from the given file. Use '-' to
+ read the message from the standard input.
+- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
++ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ is given.
+
+ -e::
+@@ Documentation/git-tag.txt: it in the repository configuration as follows:
+
+ -------------------------------------
+ [user]
+- signingKey = <gpg-keyid>
++ signingKey = <gpg-key_id>
+ -------------------------------------
+
+ `pager.tag` is only respected when listing tags, i.e., when `-l` is
## Documentation/git-upload-archive.txt ##
@@ Documentation/git-upload-archive.txt: git-upload-archive - Send archive back to git-archive
@@ builtin/commit-graph.c
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
- ## builtin/credential-cache--daemon.c ##
-@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
- const char *socket_path;
- int ignore_sighup = 0;
- static const char *usage[] = {
-- "git-credential-cache--daemon [opts] <socket_path>",
-+ "git-credential-cache--daemon [opts] <socket-path>",
- NULL
- };
- int debug = 0;
-
## builtin/for-each-repo.c ##
@@
#include "string-list.h"
19: 3bfdd3fb79e ! 17: e6ef67f1c4f doc txt & -h consistency: add or fix optional "--" syntax
@@ Commit message
inconsistent, or where we incorrectly stated in one but not the other
that the "--" was mandatory.
+ In the case of "rev-list" both sides were wrong, as we we don't
+ require one or more paths if "--" is used, e.g. this is OK:
+
+ git rev-list HEAD --
+
+ That part of this change is not a "doc txt & -h consistency" change,
+ as we're changing both versions, doing so here makes both sides
+ consistent.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+ ## Documentation/git-rev-list.txt ##
+@@ Documentation/git-rev-list.txt: git-rev-list - Lists commit objects in reverse chronological order
+ SYNOPSIS
+ --------
+ [verse]
+-'git rev-list' [<options>] <commit>... [[--] <path>...]
++'git rev-list' [<options>] <commit>... [--] [<path>...]
+
+ DESCRIPTION
+ -----------
+
## builtin/for-each-repo.c ##
@@
#include "string-list.h"
@@ builtin/rev-list.c
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit>... [-- <path>...]\n"
-+"git rev-list [<options>] <commit>... [[--] <path>...]\n"
++"git rev-list [<options>] <commit>... [--] [<path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
20: 98bdd0353cf = 18: 766bafcde05 doc txt & -h consistency: make output order consistent
21: 1713227d497 ! 19: fb95d7a9f86 doc txt & -h consistency: add missing options and labels
@@ Commit message
* We said "opts" or "options", but could instead enumerate
the (small) set of supported options
- * argument labels were missing entirely (ls-remote)
+ * Options that were missing entirely (ls-remote's --sort=<key>)
- * How we referred to an argument was inconsistent between the two,
- e.g. <pack> v.s. <pack>.idx.
+ As we can specify "--sort" multiple times (it's backed by a
+ string-list" it should really be "[(--sort=<key>)...]", which is
+ what "git for-each-ref" lists it as, but let's leave that issue for
+ a subsequent cleanup, and stop at making these consistent. Other
+ "ref-filter.h" users share the same issue, e.g. "git-branch.txt".
+
+ * For "verify-tag" and "verify-commit" we were missing the "--raw"
+ option.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-update-server-info.txt: $GIT_OBJECT_DIRECTORY/info directories
+-------
+-f::
+--force::
-+ Allow adding otherwise ignored files.
++ update the info files from scratch.
+
OUTPUT
------
@@ Documentation/git-verify-commit.txt: git-verify-commit - Check the GPG signature
--------
[verse]
-'git verify-commit' <commit>...
-+'git verify-commit' [-v | --verbose] <commit>...
++'git verify-commit' [-v | --verbose] [--raw] <commit>...
DESCRIPTION
-----------
@@ Documentation/git-verify-tag.txt: git-verify-tag - Check the GPG signature of ta
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
-+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...
++'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
DESCRIPTION
-----------
@@ builtin/upload-pack.c
};
+ ## builtin/verify-commit.c ##
+@@
+ #include "gpg-interface.h"
+
+ static const char * const verify_commit_usage[] = {
+- N_("git verify-commit [-v | --verbose] <commit>..."),
++ N_("git verify-commit [-v | --verbose] [--raw] <commit>..."),
+ NULL
+ };
+
+
+ ## builtin/verify-tag.c ##
+@@
+ #include "ref-filter.h"
+
+ static const char * const verify_tag_usage[] = {
+- N_("git verify-tag [-v | --verbose] [--format=<format>] <tag>..."),
++ N_("git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>..."),
+ NULL
+ };
+
+
## help.c ##
@@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
22: 702eb747c0f = 20: 729029f49c3 doc txt & -h consistency: make "rerere" consistent
23: 01e20b8e452 ! 21: 2d4fdbd1aa1 doc txt & -h consistency: make "read-tree" consistent
@@ Metadata
## Commit message ##
doc txt & -h consistency: make "read-tree" consistent
- The C version was right to use "()" in place of "[]", let's update
- the *.txt version accordingly, and furthermore list the *.c options in
- the same order as the *.txt.
+ The C version was right to use "()" in place of "[]" around the option
+ listing, let's update the *.txt version accordingly, and furthermore
+ list the *.c options in the same order as the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
24: 7f93da79fee = 22: c3d227c17c6 doc txt & -h consistency: make "bundle" consistent
25: ab109f73264 ! 23: 02e450ea39b doc txt & -h consistency: use "git foo" form, not "git-foo"
@@ Commit message
Use the "git cmd" form instead of "git-cmd" for both "git
receive-pack" and "git credential-cache--daemon".
+ For "git-receive-pack" we do have a binary with that name, even when
+ installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes
+ of the SYNOPSIS let's use the "git cmd" form like everywhere else. It
+ can be invoked like that (and our tests do so), the parts of our
+ documentation that explain when you need to use the dashed form do so,
+ and use it.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-receive-pack.txt ##
26: d57635b2707 = 24: 430d40d3083 doc txt & -h consistency: add missing options
27: ac959d0cfc1 = 25: acd6e1f2632 doc txt & -h consistency: make "stash" consistent
28: f617375ea9e ! 26: c02fc626542 doc txt & -h consistency: make "annotate" consistent
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
long anchor;
const int hexsz = the_hash_algo->hexsz;
long num_lines = 0;
-+ const char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
++ const char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;
++ const char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
setup_default_color_by_age();
git_config(git_blame_config, &output_option);
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);
for (;;) {
- switch (parse_options_step(&ctx, options, blame_opt_usage)) {
-+ switch (parse_options_step(&ctx, options, usage)) {
++ switch (parse_options_step(&ctx, options, opt_usage)) {
case PARSE_OPT_NON_OPTION:
case PARSE_OPT_UNKNOWN:
break;
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
reverse = 1;
}
- parse_revision_opt(&revs, &ctx, options, blame_opt_usage);
-+ parse_revision_opt(&revs, &ctx, options, usage);
++ parse_revision_opt(&revs, &ctx, options, opt_usage);
}
parse_done:
revision_opts_finish(&revs);
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
case 2: /* (1b) */
if (argc != 4)
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
/* reorder for the new way: <rev> -- <path> */
argv[1] = argv[3];
argv[3] = argv[2];
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
break;
default:
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
}
} else {
if (argc < 2)
- usage_with_options(blame_opt_usage, options);
-+ usage_with_options(usage, options);
++ usage_with_options(opt_usage, options);
if (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */
path = add_prefix(prefix, argv[1]);
argv[1] = argv[2];
@@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)
+ nth_line_cb, &sb, lno, anchor,
&bottom, &top, sb.path,
the_repository->index))
- usage_msg_optf(_("failed to parse -L argument '%s'"),
-- blame_opt_usage, options, arg);
-+ usage, options, arg);
+- usage(blame_usage);
++ usage(str_usage);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
29: c96c3fc6d8d = 27: d991b9ef611 doc txt & -h consistency: use "[<label>...]" for "zero or more"
30: 34b778dd176 = 28: dd7d2f0b167 doc txt & -h consistency: make "diff-tree" consistent
31: 336fc749f1c = 29: 3c8154151f3 doc txt & -h consistency: make "commit" consistent
32: 81024d1c3cd = 30: 2452157548b reflog doc: list real subcommands up-front
33: 76e6b7d296a = 31: dbcabff3421 worktree: define subcommand -h in terms of command -h
34: efd0c2c634d = 32: ea82721b057 doc txt & -h consistency: make "worktree" consistent
35: 22da68abce3 ! 33: a2abf7a1161 tests: start asserting that *.txt SYNOPSIS matches -h output
@@ Commit message
testing.
This adds such regression testing, we can parse out the SYNOPSIS
- output with "sed", and is turns out it's relatively easy to normalize
+ output with "sed", and it turns out it's relatively easy to normalize
it and the "-h" output to match on another.
We now ensure that we won't have regressions when it comes to the list
@@ Commit message
"builtin_log_usage" in builtin/log.c doesn't take into account what
command we're running.
- * Likewise "git stage -h" shows "git add" usage, but should be aware
- of what command it's running. The same for "annotate" and "blame".
-
* Commands which implement subcommands such as like
"multi-pack-index", "notes", "remote" etc. having their subcommands
in a very different order in the *.txt and *.c. Fixing it would
- require some verbose diffs, so it's been left alone for onw.
+ require some verbose diffs, so it's been left alone for now.
* Commands such as "format-patch" have a very long argument list in
the *.txt, but just "[<options>]" in the *.c.
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- ## t/t0450-txt-doc-vs-help.sh (new) ##
+ ## t/t0450-txt-doc-vs-help.sh ##
@@
-+#!/bin/sh
-+
-+test_description='compare (unbuilt) Documentation/*.txt to -h output
+ #!/bin/sh
+
+-test_description='assert (unbuilt) Documentation/*.txt and -h output'
++test_description='assert (unbuilt) Documentation/*.txt and -h output
+
+Run this with --debug to see a summary of where we still fail to make
+the two versions consistent with one another.'
-+
-+. ./test-lib.sh
-+
-+test_expect_success 'setup: list of builtins' '
-+ git --list-cmds=builtins >builtins
-+'
-+
+
+ TEST_PASSES_SANITIZE_LEAK=true
+ . ./test-lib.sh
+@@ t/t0450-txt-doc-vs-help.sh: test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+ '
+
+test_expect_success 'list of txt and help mismatches is sorted' '
+ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
+ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
@@ t/t0450-txt-doc-vs-help.sh (new)
+ fi
+'
+
-+builtin_to_synopsis () {
-+ builtin="$1" &&
-+ test_when_finished "rm -f out" &&
-+ test_expect_code 129 git $builtin -h >out 2>&1 &&
-+ sed -n \
-+ -e '1,/^$/ {
-+ /^$/d;
-+ s/^usage: //;
-+ s/^ *or: //;
-+ p;
-+ }' <out
-+}
-+
-+builtin_to_txt () {
-+ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
-+}
-+
-+txt_synopsis () {
-+ sed -n \
-+ -e '/^\[verse\]$/,/^$/ {
-+ /^$/d;
-+ /^\[verse\]$/d;
+ help_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+@@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {
+ /^$/d;
+ /^\[verse\]$/d;
+
+ s/{litdd}/--/g;
-+
+ s/'\''\(git[ a-z-]*\)'\''/\1/g;
-+ p;
-+ }' \
-+ <"$1"
-+}
+
-+HT=" "
+ p;
+ }' \
+ <"$b2t" >"$out" &&
+@@ t/t0450-txt-doc-vs-help.sh: check_dashed_labels () {
+
+ HT=" "
+
+align_after_nl () {
+ builtin="$1" &&
+ len=$(printf "git %s " "$builtin" | wc -c) &&
@@ t/t0450-txt-doc-vs-help.sh (new)
+}
+
+test_debug '>failing'
-+while read builtin
-+do
-+ test_expect_success "$builtin -h output has no \t" '
-+ builtin_to_synopsis "$builtin" >help.raw &&
-+ ! grep "$HT" help.raw
-+ '
-+
-+ txt="$(builtin_to_txt "$builtin")" &&
-+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
-+
-+ if test -f "$txt"
-+ then
-+ test_set_prereq "$preq"
-+ fi &&
-+
+ while read builtin
+ do
+ # -h output assertions
+@@ t/t0450-txt-doc-vs-help.sh: do
+ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
+ check_dashed_labels "$(txt_to_synopsis "$builtin")"
+ '
++
++ # *.txt output consistency assertions
+ result=
+ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
@@ t/t0450-txt-doc-vs-help.sh (new)
+ else
+ result=success
+ fi &&
-+
+ test_expect_$result "$preq" "$builtin -h output and SYNOPSIS agree" '
-+ txt_synopsis "$txt" >txt.raw &&
++ t2s="$(txt_to_synopsis "$builtin")" &&
+ if test "$builtin" = "merge-tree"
+ then
-+ sed -e '\''s/ (deprecated)$//g'\'' <txt.raw >txt.raw.new &&
-+ mv txt.raw.new txt.raw
++ test_when_finished "rm -f t2s.new" &&
++ sed -e '\''s/ (deprecated)$//g'\'' <"$t2s" >t2s.new
++ t2s=t2s.new
+ fi &&
-+ builtin_to_synopsis "$builtin" >help.raw &&
++ h2s="$(help_to_synopsis "$builtin")" &&
+
+ # The *.txt and -h use different spacing for the
+ # alignment of continued usage output, normalize it.
-+ align_after_nl "$builtin" <txt.raw >txt &&
-+ align_after_nl "$builtin" <help.raw >help &&
++ align_after_nl "$builtin" <"$t2s" >txt &&
++ align_after_nl "$builtin" <"$h2s" >help &&
+ test_cmp txt help
+ '
+
@@ t/t0450-txt-doc-vs-help.sh (new)
+ # used with --debug
+ rm -f txt help tmp 2>/dev/null
+ fi
-+done <builtins
-+
+ done <builtins
+
+test_debug 'say "$(cat failing)"'
+
-+test_done
+ test_done
## t/t0450/txt-help-mismatches (new) ##
@@
36: b56113dd620 ! 34: 3443ae7ee6b tests: assert consistent whitespace in -h output
@@ Commit message
[...]
[--create-reflog] [...]
- Which should instead be like this instead, i.e. the options lines
- should be aligned:
+ Which should instead be like this, i.e. the options lines should be
+ aligned:
[...]
or: git tag [-n[<num>]]
@@ Commit message
## t/t0450-txt-doc-vs-help.sh ##
@@ t/t0450-txt-doc-vs-help.sh: do
- ! grep "$HT" help.raw
+ check_dashed_labels "$(help_to_synopsis "$builtin")"
'
+ test_expect_success "$builtin -h output has consistent spacing" '
-+ builtin_to_synopsis "$builtin" >help.raw &&
++ h2s="$(help_to_synopsis "$builtin")" &&
+ sed -n \
+ -e "/^ / {
+ s/[^ ].*//;
+ p;
+ }" \
-+ <help.raw >help &&
++ <"$h2s" >help &&
+ sort -u help >help.ws &&
+ if test -s help.ws
+ then
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply [flat|nested] 230+ messages in thread* [PATCH v4 01/34] tests: assert *.txt SYNOPSIS and -h output
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
` (32 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test to assert basic compliance with the CodingGuidelines in the
SYNOPSIS and builtin -h output. For now we only assert that the "-h"
output doesn't have "\t" characters, as a very basic syntax check.
Subsequent commits will expand on the checks here as various issues
are fixed, but let's first add the test scaffolding.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
create mode 100755 t/t0450-txt-doc-vs-help.sh
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
new file mode 100755
index 00000000000..c8820bdd38f
--- /dev/null
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+
+test_description='assert (unbuilt) Documentation/*.txt and -h output'
+
+TEST_PASSES_SANITIZE_LEAK=true
+. ./test-lib.sh
+
+test_expect_success 'setup: list of builtins' '
+ git --list-cmds=builtins >builtins
+'
+
+help_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+ out="$out_dir/help.synopsis" &&
+ if test -f "$out"
+ then
+ echo "$out" &&
+ return 0
+ fi &&
+ mkdir -p "$out_dir" &&
+ test_expect_code 129 git $builtin -h >"$out.raw" 2>&1 &&
+ sed -n \
+ -e '1,/^$/ {
+ /^$/d;
+ s/^usage: //;
+ s/^ *or: //;
+ p;
+ }' <"$out.raw" >"$out" &&
+ echo "$out"
+}
+
+HT=" "
+
+while read builtin
+do
+ # -h output assertions
+ test_expect_success "$builtin -h output has no \t" '
+ h2s="$(help_to_synopsis "$builtin")" &&
+ ! grep "$HT" "$h2s"
+ '
+done <builtins
+
+test_done
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 02/34] CodingGuidelines: update and clarify command-line conventions
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
` (31 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Edit the section which explains how to create a good SYNOPSIS section
for clarity and accuracy, it was mostly introduced in
c455bd8950e (CodingGuidelines: Add a section on writing documentation,
2010-11-04):
* Change "extra" example to "file", which now naturally follows from
previous "<file>..." example (one or more) to "[<file>...]" (zero or
more).
* Explain how we prefer spacing around "[]()" tokens and "|"
alternatives, this is not a new policy, but just codifies what's
already the pattern in the most wide use in the documentation.
Having a space around " | " for flags, but not for flag values is
inconsistent, but this style guide codifies existing
patterns. Grepping shows that we don't have any instance matching the
second "Don't" example:
git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/CodingGuidelines | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 9fca21cc5f9..3d3bdeba9e4 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -650,8 +650,8 @@ Writing Documentation:
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [<extra>]
- (Zero or one <extra>.)
+ [<file>...]
+ (Zero or more of <file>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
@@ -665,6 +665,16 @@ Writing Documentation:
[-q | --quiet]
[--utf8 | --no-utf8]
+ Use spacing around "|" token(s), but not immediately after opening or
+ before closing a [] or () pair:
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
+
+ Don't use spacing around "|" tokens when they're used to seperate the
+ alternate arguments of an option:
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
+
Parentheses are used for grouping:
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 03/34] builtin/bundle.c: indent with tabs
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 01/34] tests: assert *.txt SYNOPSIS and -h output Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 02/34] CodingGuidelines: update and clarify command-line conventions Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 04/34] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (30 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix indentation issues introduced with 73c3253d75e (bundle: framework
for options before bundle file, 2019-11-10), and carried forward in
some subsequent commits.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index e80efce3a42..5c78894afd5 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,31 +12,31 @@
*/
static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ N_("git bundle verify [<options>] <file>"),
+ N_("git bundle list-heads <file> [<refname>...]"),
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- NULL
+ N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
- NULL
+ N_("git bundle verify [<options>] <file>"),
+ NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
- NULL
+ N_("git bundle list-heads <file> [<refname>...]"),
+ NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+ N_("git bundle unbundle <file> [<refname>...]"),
+ NULL
};
static int parse_options_cmd_bundle(int argc,
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 04/34] bundle: define subcommand -h in terms of command -h
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 03/34] builtin/bundle.c: indent with tabs Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 05/34] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
` (29 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git bundle" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 29 +++++++++++++++++++----------
1 file changed, 19 insertions(+), 10 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 5c78894afd5..1b08700bf9e 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -11,31 +11,40 @@
* bundle supporting "fetch", "pull", and "ls-remote".
*/
-static const char * const builtin_bundle_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
- N_("git bundle verify [<options>] <file>"),
- N_("git bundle list-heads <file> [<refname>...]"),
- N_("git bundle unbundle <file> [<refname>...]"),
- NULL
+#define BUILTIN_BUNDLE_CREATE_USAGE \
+ N_("git bundle create [<options>] <file> <git-rev-list args>")
+#define BUILTIN_BUNDLE_VERIFY_USAGE \
+ N_("git bundle verify [<options>] <file>")
+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
+ N_("git bundle list-heads <file> [<refname>...]")
+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
+ N_("git bundle unbundle <file> [<refname>...]")
+
+static char const * const builtin_bundle_usage[] = {
+ BUILTIN_BUNDLE_CREATE_USAGE,
+ BUILTIN_BUNDLE_VERIFY_USAGE,
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
+ NULL,
};
static const char * const builtin_bundle_create_usage[] = {
- N_("git bundle create [<options>] <file> <git-rev-list args>"),
+ BUILTIN_BUNDLE_CREATE_USAGE,
NULL
};
static const char * const builtin_bundle_verify_usage[] = {
- N_("git bundle verify [<options>] <file>"),
+ BUILTIN_BUNDLE_VERIFY_USAGE,
NULL
};
static const char * const builtin_bundle_list_heads_usage[] = {
- N_("git bundle list-heads <file> [<refname>...]"),
+ BUILTIN_BUNDLE_LIST_HEADS_USAGE,
NULL
};
static const char * const builtin_bundle_unbundle_usage[] = {
- N_("git bundle unbundle <file> [<refname>...]"),
+ BUILTIN_BUNDLE_UNBUNDLE_USAGE,
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 05/34] doc SYNOPSIS: don't use ' for subcommands
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 04/34] bundle: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 06/34] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
` (28 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Almost all of our documentation doesn't use "'" syntax for
subcommands, but these did, let's make them consistent with the
rest.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index db9d46edfa9..0537d4645be 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -17,7 +17,7 @@ The command takes various subcommands, and different options
depending on the subcommand:
[verse]
-'git reflog' ['show'] [<log-options>] [<ref>]
+'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
[--rewrite] [--updateref] [--stale-fix]
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4cfc8833780..4b613d4140c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
DESCRIPTION
-----------
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 06/34] doc SYNOPSIS: consistently use ' for commands
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 05/34] doc SYNOPSIS: don't use ' for subcommands Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 07/34] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
` (27 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Most of our commands use ''-quotation only for the name of the command
itself, and not its (optional) arguments. Let's do the same for these.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-fast-export.txt | 2 +-
Documentation/git-sparse-checkout.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 1978dbdc6ad..4643ddbe68f 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -9,7 +9,7 @@ git-fast-export - Git data exporter
SYNOPSIS
--------
[verse]
-'git fast-export [<options>]' | 'git fast-import'
+'git fast-export' [<options>] | 'git fast-import'
DESCRIPTION
-----------
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 3776705bf53..872436d7426 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [<options>]'
+'git sparse-checkout' <subcommand> [<options>]
DESCRIPTION
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 07/34] built-ins: consistently add "\n" between "usage" and options
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 06/34] doc SYNOPSIS: consistently use ' for commands Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 08/34] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
` (26 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change commands in the "diff" family and "rev-list" to separate the
usage information and option listing with an empty line.
In the case of "git diff -h" we did this already (but let's use a
consistent "\n" pattern there), for the rest these are now consistent
with how the parse_options() API would emit usage.
As we'll see in a subsequent commit this also helps to make the "git
<cmd> -h" output more easily machine-readable, as we can assume that
the usage information is separated from the options by an empty line.
Note that "COMMON_DIFF_OPTIONS_HELP" starts with a "\n", so the
seeming omission of a "\n" here is correct, the second one is provided
by the macro.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-files.c | 1 +
builtin/diff-index.c | 1 +
builtin/diff-tree.c | 1 +
builtin/diff.c | 3 ++-
builtin/rev-list.c | 1 +
5 files changed, 6 insertions(+), 1 deletion(-)
diff --git a/builtin/diff-files.c b/builtin/diff-files.c
index 92cf6e1e922..096ea2fedbc 100644
--- a/builtin/diff-files.c
+++ b/builtin/diff-files.c
@@ -15,6 +15,7 @@
static const char diff_files_usage[] =
"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_files(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index 7d158af6b6d..e667cf52e7d 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -11,6 +11,7 @@
static const char diff_cache_usage[] =
"git diff-index [-m] [--cached] "
"[<common-diff-options>] <tree-ish> [<path>...]"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
int cmd_diff_index(int argc, const char **argv, const char *prefix)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 116097a404a..23f58702fa0 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)
static const char diff_tree_usage[] =
"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
" --cc show combined diff for merge commits removing uninteresting hunks\n"
diff --git a/builtin/diff.c b/builtin/diff.c
index 54bb3de964c..67760b67552 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =
" or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
" or: git diff [<options>] <commit>...<commit> [--] [<path>...]\n"
" or: git diff [<options>] <blob> <blob>\n"
-" or: git diff [<options>] --no-index [--] <path> <path>\n"
+" or: git diff [<options>] --no-index [--] <path> <path>"
+"\n"
COMMON_DIFF_OPTIONS_HELP;
static const char *blob_path(struct object_array_entry *entry)
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index fba6f5d51f3..f67e2b33555 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -21,6 +21,7 @@
static const char rev_list_usage[] =
"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"\n"
" limiting output:\n"
" --max-count=<n>\n"
" --max-age=<epoch>\n"
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 08/34] doc txt & -h consistency: word-wrap
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 07/34] built-ins: consistently add "\n" between "usage" and options Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 09/34] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
` (25 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the documentation and -h output for those built-in commands
where both the -h output and *.txt were lacking in word-wrapping.
There are many more built-ins that could use this treatment, this
change is narrowed to those where this whitespace change is needed to
make the -h and *.txt consistent in the end.
In the case of "Documentation/git-hash-object.txt" and
"builtin/hash-object.c" this is not a "doc txt & -h consistency"
change, as we're changing both versions, doing so here makes a
subsequent change smaller.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-hash-object.txt | 3 ++-
Documentation/git-worktree.txt | 3 ++-
builtin/bugreport.c | 3 ++-
builtin/commit-graph.c | 8 ++++----
builtin/commit-tree.c | 4 ++--
builtin/diagnose.c | 3 ++-
builtin/hash-object.c | 3 ++-
builtin/init-db.c | 3 ++-
builtin/interpret-trailers.c | 4 +++-
builtin/read-tree.c | 4 +++-
builtin/show-branch.c | 3 ++-
builtin/show-ref.c | 4 +++-
12 files changed, 29 insertions(+), 16 deletions(-)
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index df9e2c58bdb..58670ef12f7 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...
+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+ [--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
DESCRIPTION
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index ada30c86a7c..063d6eeb99d 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees
SYNOPSIS
--------
[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+ [-b <new-branch>] <path> [<commit-ish>]
'git worktree list' [-v | --porcelain [-z]]
'git worktree lock' [--reason <string>] <worktree>
'git worktree move' <worktree> <new-path>
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 530895be55f..faa268f3cfb 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]"),
+ N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ " [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 51557fe786e..cd346f95f08 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -13,10 +13,10 @@
N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append] " \
- "[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] " \
- "[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] " \
- "<split options>")
+ N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
+ " <split options>")
static const char * builtin_commit_graph_verify_usage[] = {
BUILTIN_COMMIT_GRAPH_VERIFY_USAGE,
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 63ea3229333..e4b85d29d56 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,8 +15,8 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
- N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] "
- "[(-F <file>)...] <tree>"),
+ N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
+ " [(-F <file>)...] <tree>"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 576e0e8e385..28c394a62a5 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,8 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]"),
+ N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ " [--mode=<mode>]"),
NULL
};
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index fbae878c2b9..f7c16802f0c 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,
int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
- N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
+ " [--stdin] [--] <file>..."),
"git hash-object --stdin-paths",
NULL
};
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 546f9c595e7..08ba006d55e 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
}
static const char *const init_db_usage[] = {
- N_("git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]"),
+ N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 84748eafc01..4cf0cf265dc 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -13,7 +13,9 @@
#include "config.h"
static const char * const git_interpret_trailers_usage[] = {
- N_("git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]"),
+ N_("git interpret-trailers [--in-place] [--trim-empty]\n"
+ " [(--trailer <token>[(=|:)<value>])...]\n"
+ " [<file>...]"),
NULL
};
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index 9f1f33e9546..b3a389e1b1f 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)
}
static const char * const read_tree_usage[] = {
- N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) [-u | -i]] [--no-sparse-checkout] [--index-output=<file>] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
+ N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
+ " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
diff --git a/builtin/show-branch.c b/builtin/show-branch.c
index d3f5715e3e3..c013abaf942 100644
--- a/builtin/show-branch.c
+++ b/builtin/show-branch.c
@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {
N_("git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n"
" [--current] [--color[=<when>] | --no-color] [--sparse]\n"
" [--more=<n> | --list | --independent | --merge-base]\n"
- " [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]"),
+ " [--no-name | --sha1-name] [--topics]\n"
+ " [(<rev> | <glob>)...]"),
N_("git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]"),
NULL
};
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 48569061087..3af6a53ee97 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -9,7 +9,9 @@
#include "parse-options.h"
static const char * const show_ref_usage[] = {
- N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]"),
+ N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\n"
+ " [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n"
+ " [--heads] [--] [<pattern>...]"),
N_("git show-ref --exclude-existing[=<pattern>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 09/34] doc txt & -h consistency: fix incorrect alternates syntax
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 08/34] doc txt & -h consistency: word-wrap Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 10/34] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
` (24 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix the incorrect "[-o | --option <argument>]" syntax, which should be
"[(-o | --option) <argument>]", we were previously claiming that only
the long option accepted the "<argument>", which isn't what we meant.
This syntax issue for "bugreport" originated in
238b439d698 (bugreport: add tool to generate debugging info,
2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
"bugreport" documentation and code.
In the case of "Documentation/git-stash.txt" and "builtin/stash.c"
this is not a "doc txt & -h consistency" change, as we're changing
both versions, doing so here makes a subsequent change smaller.
In that case fix the incorrect "[-o | --option <argument>]" syntax,
which should be "[(-o | --option) <argument>]", we were previously
claiming that only the long option accepted the "<argument>", which
isn't what we meant.
The "stash" issue has been with us in both the "-h" and *.txt versions
since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).
We could claim that this isn't a syntax issue if a "vertical bar binds
tighter than option and its argument", but such a rule would change
e.g. this "cat-file" SYNOPSIS example to mean something we don't:
... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
We have various other examples where the post-image here is already
used, e.g. for "format-patch" ("-o"), "grep" ("-m"),
"submodule" ("set-branch -b") etc.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 6 +++---
builtin/bugreport.c | 2 +-
builtin/diagnose.c | 2 +-
builtin/stash.c | 6 +++---
4 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index c5d70918283..4856f452511 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -14,12 +14,12 @@ SYNOPSIS
'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [-m|--message <message>]
+ [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
DESCRIPTION
-----------
@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
COMMANDS
--------
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
Save your local modifications to a new 'stash entry' and roll them
back to HEAD (in the working tree and in the index).
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index faa268f3cfb..23170113cc8 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
+ N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
" [--diagnose[=<mode>]"),
NULL
};
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 28c394a62a5..474de9ec647 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
+ N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
diff --git a/builtin/stash.c b/builtin/stash.c
index 2274aae2556..51d40efaac7 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [-m|--message <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n"
+ " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 10/34] doc txt & -h consistency: add "-z" to cat-file "-h"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 09/34] doc txt & -h consistency: fix incorrect alternates syntax Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 11/34] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
` (23 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited
input with `-z`, 2022-07-22), before that change the SYNOPSIS and "-h"
output were the same, but not afterwards.
That change followed a similar earlier divergence in
473fa2df08d (Documentation: add --batch-command to cat-file synopsis,
2022-04-07). Subsequent commits will fix this sort of thing more
systematically, but let's fix this one as a one-off.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/cat-file.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/cat-file.c b/builtin/cat-file.c
index 989eee0bb4c..fa7bd891692 100644
--- a/builtin/cat-file.c
+++ b/builtin/cat-file.c
@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)
N_("git cat-file (-t | -s) [--allow-unknown-type] <object>"),
N_("git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\n"
" [--buffer] [--follow-symlinks] [--unordered]\n"
- " [--textconv | --filters]"),
+ " [--textconv | --filters] [-z]"),
N_("git cat-file (--textconv | --filters)\n"
" [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]"),
NULL
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 11/34] doc txt & -h consistency: balance unbalanced "[" and "]"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 10/34] doc txt & -h consistency: add "-z" to cat-file "-h" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 12/34] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
` (22 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix a "-h" output syntax issue introduced when "--diagnose" was added
in aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,
2022-08-12): We need to close the "[" we opened. The
corresponding *.txt change did not have the same issue.
The "help -h" output then had one "]" too many, which is an issue
introduced in b40845293b5 (help: correct the usage string in -h and
documentation, 2021-09-10).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bugreport.c | 2 +-
builtin/help.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 23170113cc8..bb138161943 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
static const char * const bugreport_usage[] = {
N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
- " [--diagnose[=<mode>]"),
+ " [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/help.c b/builtin/help.c
index 6f2796f211e..53f2812dfb1 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {
};
static const char * const builtin_help_usage[] = {
- "git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
+ "git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]",
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
"git help [-g|--guides]",
"git help [-c|--config]",
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 12/34] doc txt & -h consistency: correct padding around "[]()"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (10 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 11/34] doc txt & -h consistency: balance unbalanced "[" and "]" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 13/34] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
` (21 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-diff-files.txt | 2 +-
Documentation/git-hash-object.txt | 2 +-
Documentation/git-merge-base.txt | 4 ++--
Documentation/git-pack-redundant.txt | 2 +-
Documentation/git-prune-packed.txt | 2 +-
Documentation/git-rerere.txt | 2 +-
Documentation/git-send-pack.txt | 2 +-
Documentation/git-show-branch.txt | 4 ++--
Documentation/git-show-ref.txt | 4 ++--
Documentation/git-var.txt | 2 +-
Documentation/git-verify-pack.txt | 2 +-
builtin/bugreport.c | 2 +-
builtin/commit-graph.c | 2 +-
builtin/diagnose.c | 2 +-
builtin/sparse-checkout.c | 2 +-
15 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index bf1febb9ae7..591e3801b7b 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index
SYNOPSIS
--------
[verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 58670ef12f7..472b5bb995b 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
[verse]
-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]
+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]
[--stdin [--literally]] [--] <file>...
'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 2d944e0851f..b01ba3d3565 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
--------
[verse]
-'git merge-base' [-a|--all] <commit> <commit>...
-'git merge-base' [-a|--all] --octopus <commit>...
+'git merge-base' [-a | --all] <commit> <commit>...
+'git merge-base' [-a | --all] --octopus <commit>...
'git merge-base' --is-ancestor <commit> <commit>
'git merge-base' --independent <commit>...
'git merge-base' --fork-point <ref> [<commit>]
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt
index ee7034b5e52..dda80a740c8 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.txt
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
SYNOPSIS
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)
DESCRIPTION
-----------
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 9fed59a3172..844d6f808a0 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files
SYNOPSIS
--------
[verse]
-'git prune-packed' [-n|--dry-run] [-q|--quiet]
+'git prune-packed' [-n | --dry-run] [-q | --quiet]
DESCRIPTION
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 4b613d4140c..9d0e6f53e7e 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]
+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
DESCRIPTION
-----------
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index be41f119740..e0c71623432 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
- [--[no-]signed|--signed=(true|false|if-asked)]
+ [--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
DESCRIPTION
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index e5ec6b467f9..71f608b1ff1 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits
SYNOPSIS
--------
[verse]
-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]
+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
[(<rev> | <glob>)...]
-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]
DESCRIPTION
-----------
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ab4d271925d..d1d56f68b43 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository
SYNOPSIS
--------
[verse]
-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]
- [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]
+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
[--heads] [--] [<pattern>...]
'git show-ref' --exclude-existing[=<pattern>]
diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 387cc1b9142..6aa521fab23 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -9,7 +9,7 @@ git-var - Show a Git logical variable
SYNOPSIS
--------
[verse]
-'git var' ( -l | <variable> )
+'git var' (-l | <variable>)
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 61ca6d04c20..b8720dce8ab 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files
SYNOPSIS
--------
[verse]
-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...
+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
DESCRIPTION
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index bb138161943..61d93383f51 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index cd346f95f08..13cbb75ca28 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -14,7 +14,7 @@
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
- " [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n" \
+ " [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/diagnose.c b/builtin/diagnose.c
index 474de9ec647..d52015c67a4 100644
--- a/builtin/diagnose.c
+++ b/builtin/diagnose.c
@@ -3,7 +3,7 @@
#include "diagnose.h"
static const char * const diagnose_usage[] = {
- N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
+ N_("git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--mode=<mode>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 287716db68e..aac0f708e42 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init|list|set|add|reapply|disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 13/34] stash doc SYNOPSIS & -h: correct padding around "[]()"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (11 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 12/34] doc txt & -h consistency: correct padding around "[]()" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 14/34] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
` (20 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The whitespace padding of alternatives should be of the form "[-f |
--force]" not "[-f|--force]". Likewise we should not have padding
before the first option, so "(--all | <pack-filename>...)" is correct,
not "( --all | <pack-filename>... )".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 12 ++++++------
builtin/stash.c | 28 ++++++++++++++--------------
2 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 4856f452511..ea16d2eae7c 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -9,17 +9,17 @@ SYNOPSIS
--------
[verse]
'git stash' list [<log-options>]
-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q|--quiet] [<stash>]
-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+'git stash' drop [-q | --quiet] [<stash>]
+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]
- [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
'git stash' clear
'git stash' create [<message>]
-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>
+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
DESCRIPTION
-----------
diff --git a/builtin/stash.c b/builtin/stash.c
index 51d40efaac7..d91cf5fd3e1 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -24,16 +24,16 @@
static const char * const git_stash_usage[] = {
N_("git stash list [<options>]"),
N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q|--quiet] [<stash>]"),
- N_("git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
+ N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
N_("git stash branch <branchname> [<stash>]"),
"git stash clear",
- N_("git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
" [--] [<pathspec>...]]"),
- N_("git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q|--quiet] [<stash>]"),
+ N_("git stash drop [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q|--quiet] [<stash>]"),
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
NULL
};
@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m|--message) <message>] [-q|--quiet] <commit>"),
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n"
+ N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
" [--] [<pathspec>...]]"),
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\n"
- " [-u|--include-untracked] [-a|--all] [<message>]"),
+ N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
+ " [-u | --include-untracked] [-a | --all] [<message>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 14/34] doc txt & -h consistency: use "<options>", not "<options>..."
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (12 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 13/34] stash doc SYNOPSIS & -h: " Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" Ævar Arnfjörð Bjarmason
` (19 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
It's arguably more correct to say "[<option>...]" than either of these
forms, but the vast majority of our documentation uses the
"[<options>]" form to indicate an arbitrary number of options, let's
do the same in these cases, which were the odd ones out.
In the case of "mv" and "sparse-checkout" let's add the missing "[]"
to indicate that these are optional.
In the case of "t/helper/test-proc-receive.c" there is no *.txt
version, making it the only hunk in this commit that's not a "doc txt
& -h consistency" change.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-mv.txt | 2 +-
Documentation/git-status.txt | 2 +-
builtin/pack-objects.c | 4 ++--
builtin/sparse-checkout.c | 2 +-
t/helper/test-proc-receive.c | 2 +-
5 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 79449bf98fe..972a055fbd8 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' <options>... <args>...
+'git mv' [<options>] <args>...
DESCRIPTION
-----------
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 54a4b29b473..5e438a7fdc1 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -9,7 +9,7 @@ git-status - Show the working tree status
SYNOPSIS
--------
[verse]
-'git status' [<options>...] [--] [<pathspec>...]
+'git status' [<options>] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 3658c05cafc..573d0b20b76 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,
#define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)
static const char *pack_usage[] = {
- N_("git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]"),
- N_("git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]"),
+ N_("git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]"),
NULL
};
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index aac0f708e42..58a22503f04 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -20,7 +20,7 @@
static const char *empty_base = "";
static char const * const builtin_sparse_checkout_usage[] = {
- N_("git sparse-checkout (init | list | set | add | reapply | disable) <options>"),
+ N_("git sparse-checkout (init | list | set | add | reapply | disable) [<options>]"),
NULL
};
diff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c
index cc08506cf0b..a4b305f4947 100644
--- a/t/helper/test-proc-receive.c
+++ b/t/helper/test-proc-receive.c
@@ -6,7 +6,7 @@
#include "test-tool.h"
static const char *proc_receive_usage[] = {
- "test-tool proc-receive [<options>...]",
+ "test-tool proc-receive [<options>]",
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (13 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 14/34] doc txt & -h consistency: use "<options>", not "<options>..." Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
` (18 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change "builtin/credential-cache--daemon.c" to use "<socket-path>" not
"<socket_path>" in a placeholder label, almost all of our
documentation uses this form.
This is now consistent with the "If a placeholder has multiple words,
they are separated by dashes" guideline added in
9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's
add a now-passing test to assert that that's the case.
To do this we need to introduce a very sed-powered parser to extract
the SYNOPSIS from the *.txt, and handle not all commands with "-h"
having a corresponding *.txt (e.g. "bisect--helper"). We'll still want
to handle syntax edge cases in the *.txt in subsequent commits for
other checks, but let's do that then.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/credential-cache--daemon.c | 2 +-
t/t0450-txt-doc-vs-help.sh | 46 ++++++++++++++++++++++++++++++
2 files changed, 47 insertions(+), 1 deletion(-)
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index 4c6c89ab0de..ca672a6a619 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket_path>",
+ "git-credential-cache--daemon [opts] <socket-path>",
NULL
};
int debug = 0;
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index c8820bdd38f..efd00cfc51a 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -30,6 +30,35 @@ help_to_synopsis () {
echo "$out"
}
+builtin_to_txt () {
+ echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
+}
+
+txt_to_synopsis () {
+ builtin="$1" &&
+ out_dir="out/$builtin" &&
+ out="$out_dir/txt.synopsis" &&
+ if test -f "$out"
+ then
+ echo "$out" &&
+ return 0
+ fi &&
+ b2t="$(builtin_to_txt "$builtin")" &&
+ sed -n \
+ -e '/^\[verse\]$/,/^$/ {
+ /^$/d;
+ /^\[verse\]$/d;
+
+ p;
+ }' \
+ <"$b2t" >"$out" &&
+ echo "$out"
+}
+
+check_dashed_labels () {
+ ! grep -E "<[^>_-]+_" "$1"
+}
+
HT=" "
while read builtin
@@ -39,6 +68,23 @@ do
h2s="$(help_to_synopsis "$builtin")" &&
! grep "$HT" "$h2s"
'
+
+ test_expect_success "$builtin -h output has dashed labels" '
+ check_dashed_labels "$(help_to_synopsis "$builtin")"
+ '
+
+ txt="$(builtin_to_txt "$builtin")" &&
+ preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
+
+ if test -f "$txt"
+ then
+ test_set_prereq "$preq"
+ fi &&
+
+ # *.txt output assertions
+ test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
+ check_dashed_labels "$(txt_to_synopsis "$builtin")"
+ '
done <builtins
test_done
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (14 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 15/34] doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 16:27 ` Junio C Hamano
2022-10-04 13:23 ` [PATCH v4 17/34] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
` (17 subsequent siblings)
33 siblings, 1 reply; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various inconsistencies between command SYNOPSIS and the
corresponding -h output where our translatable labels didn't match
up.
In some cases we need to adjust the prose that follows the SYNOPSIS
accordingly, as it refers back to the changed label.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 8 ++++----
Documentation/git-credential-cache--daemon.txt | 4 ++--
Documentation/git-mv.txt | 4 ++--
Documentation/git-receive-pack.txt | 4 ++--
Documentation/git-tag.txt | 18 +++++++++---------
Documentation/git-upload-archive.txt | 4 ++--
builtin/bugreport.c | 2 +-
builtin/clean.c | 2 +-
builtin/commit-graph.c | 4 ++--
builtin/for-each-repo.c | 2 +-
builtin/pack-redundant.c | 2 +-
builtin/rerere.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/stash.c | 2 +-
builtin/unpack-file.c | 2 +-
builtin/upload-archive.c | 2 +-
builtin/verify-pack.c | 2 +-
builtin/worktree.c | 2 +-
18 files changed, 34 insertions(+), 34 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 91742633fa8..61b6d8667a4 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
DESCRIPTION
-----------
@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`
option is specified, ignored files are also removed. This can, for
example, be useful to remove all build products.
-If any optional `<path>...` arguments are given, only those paths
-are affected.
+If any optional `<pathspec>...` arguments are given, only those paths
+that match the pathspec are affected.
OPTIONS
-------
-d::
- Normally, when no <path> is specified, git clean will not
+ Normally, when no <pathspec> is specified, git clean will not
recurse into untracked directories to avoid removing too much.
Specify -d to have it recurse into such directories as well.
If any paths are specified, -d is irrelevant; all untracked
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index 01e1c214dd8..650a15a7edf 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
SYNOPSIS
--------
[verse]
-'git credential-cache{litdd}daemon' [--debug] <socket>
+'git credential-cache{litdd}daemon' [--debug] <socket-path>
DESCRIPTION
-----------
@@ -16,7 +16,7 @@ DESCRIPTION
NOTE: You probably don't want to invoke this command yourself; it is
started automatically when you use linkgit:git-credential-cache[1].
-This command listens on the Unix domain socket specified by `<socket>`
+This command listens on the Unix domain socket specified by `<socket-path>`
for `git-credential-cache` clients. Clients may store and retrieve
credentials. Each credential is held for a timeout specified by the
client; once no credentials are held, the daemon exits.
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index 972a055fbd8..fb0220fd18d 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink
SYNOPSIS
--------
[verse]
-'git mv' [<options>] <args>...
+'git mv' [<options>] <source>... <destination>
DESCRIPTION
-----------
@@ -30,7 +30,7 @@ OPTIONS
-------
-f::
--force::
- Force renaming or moving of a file even if the target exists
+ Force renaming or moving of a file even if the <destination> exists.
-k::
Skip move or rename actions which would lead to an error
condition. An error happens when a source is neither existing nor
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 014a78409b9..5c297db1a4b 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <directory>
+'git-receive-pack' <git-dir>
DESCRIPTION
-----------
@@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1].
OPTIONS
-------
-<directory>::
+<git-dir>::
The repository to sync into.
--http-backend-info-refs::
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 31a97a1b6c5..fdc72b5875a 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
SYNOPSIS
--------
[verse]
-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
@@ -26,19 +26,19 @@ to delete, list or verify tags.
Unless `-f` is given, the named tag must not yet exist.
-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
+If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
creates a 'tag' object, and requires a tag message. Unless
`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
in the tag message.
-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
are absent, `-a` is implied.
Otherwise, a tag reference that points directly at the given object
(i.e., a lightweight tag) is created.
A GnuPG signed tag object will be created when `-s` or `-u
-<keyid>` is used. When `-u <keyid>` is not used, the
+<key-id>` is used. When `-u <key-id>` is not used, the
committer identity for the current user is used to find the
GnuPG key for signing. The configuration variable `gpg.program`
is used to specify custom GnuPG binary.
@@ -72,8 +72,8 @@ OPTIONS
Override `tag.gpgSign` configuration variable that is
set to force each and every tag to be signed.
--u <keyid>::
---local-user=<keyid>::
+-u <key-id>::
+--local-user=<key-id>::
Make a GPG-signed tag, using the given key.
-f::
@@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines.
Use the given tag message (instead of prompting).
If multiple `-m` options are given, their values are
concatenated as separate paragraphs.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-F <file>::
--file=<file>::
Take the tag message from the given file. Use '-' to
read the message from the standard input.
- Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
-e::
@@ -220,7 +220,7 @@ it in the repository configuration as follows:
-------------------------------------
[user]
- signingKey = <gpg-keyid>
+ signingKey = <gpg-key_id>
-------------------------------------
`pager.tag` is only respected when listing tags, i.e., when `-l` is
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index fba0f1c1b27..e8eb10baad7 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive
SYNOPSIS
--------
[verse]
-'git upload-archive' <directory>
+'git upload-archive' <repository>
DESCRIPTION
-----------
@@ -54,7 +54,7 @@ access via non-smart-http.
OPTIONS
-------
-<directory>::
+<repository>::
The repository to get a tar archive from.
GIT
diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 61d93383f51..96052541cbf 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
}
static const char * const bugreport_usage[] = {
- N_("git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\n"
+ N_("git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\n"
" [--diagnose[=<mode>]]"),
NULL
};
diff --git a/builtin/clean.c b/builtin/clean.c
index 5466636e666..6f039f555b2 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
NULL
};
diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c
index 13cbb75ca28..e8f77f535f3 100644
--- a/builtin/commit-graph.c
+++ b/builtin/commit-graph.c
@@ -10,10 +10,10 @@
#include "tag.h"
#define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \
- N_("git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]")
+ N_("git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]")
#define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \
- N_("git commit-graph write [--object-dir <objdir>] [--append]\n" \
+ N_("git commit-graph write [--object-dir <dir>] [--append]\n" \
" [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n" \
" [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n" \
" <split options>")
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index fd86e5a8619..c6379b783c8 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <command-args>"),
+ N_("git for-each-repo --config=<config> <arguments>"),
NULL
};
diff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c
index ed9b9013a5f..ecd49ca268f 100644
--- a/builtin/pack-redundant.c
+++ b/builtin/pack-redundant.c
@@ -14,7 +14,7 @@
#define BLKSIZE 512
static const char pack_redundant_usage[] =
-"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)";
+"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)";
static int load_all_packs, verbose, alt_odb;
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 83d7a778e37..12570537d37 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <path>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
NULL,
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index f67e2b33555..ada68a4af5e 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit-id>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [-- <path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/stash.c b/builtin/stash.c
index d91cf5fd3e1..83c9591ea6d 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -22,7 +22,7 @@
#define INCLUDE_ALL_FILES 2
static const char * const git_stash_usage[] = {
- N_("git stash list [<options>]"),
+ N_("git stash list [<log-options>]"),
N_("git stash show [<options>] [<stash>]"),
N_("git stash drop [-q | --quiet] [<stash>]"),
N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
diff --git a/builtin/unpack-file.c b/builtin/unpack-file.c
index 58652229f27..9e8119dd354 100644
--- a/builtin/unpack-file.c
+++ b/builtin/unpack-file.c
@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)
struct object_id oid;
if (argc != 2 || !strcmp(argv[1], "-h"))
- usage("git unpack-file <sha1>");
+ usage("git unpack-file <blob>");
if (get_oid(argv[1], &oid))
die("Not a valid object name %s", argv[1]);
diff --git a/builtin/upload-archive.c b/builtin/upload-archive.c
index 98d028dae67..945ee2b4126 100644
--- a/builtin/upload-archive.c
+++ b/builtin/upload-archive.c
@@ -10,7 +10,7 @@
#include "strvec.h"
static const char upload_archive_usage[] =
- "git upload-archive <repo>";
+ "git upload-archive <repository>";
static const char deadchild[] =
"git upload-archive: archiver died with error";
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index 05c52135946..db9ac5c4606 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
NULL
};
diff --git a/builtin/worktree.c b/builtin/worktree.c
index c6710b25520..5bfc18e5a24 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {
N_("git worktree prune [<options>]"),
N_("git worktree remove [<options>] <worktree>"),
N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <path>"),
+ N_("git worktree unlock <worktree>"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* Re: [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels
2022-10-04 13:23 ` [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
@ 2022-10-04 16:27 ` Junio C Hamano
0 siblings, 0 replies; 230+ messages in thread
From: Junio C Hamano @ 2022-10-04 16:27 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Victoria Dye, Taylor Blau, Emily Shaffer, Jonathan Nieder,
John Cai, Eric Sunshine
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
> index 91742633fa8..61b6d8667a4 100644
> --- a/Documentation/git-clean.txt
> +++ b/Documentation/git-clean.txt
> @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
> SYNOPSIS
> --------
> [verse]
> -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...
> +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
>
> DESCRIPTION
> -----------
> @@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`
> option is specified, ignored files are also removed. This can, for
> example, be useful to remove all build products.
>
> -If any optional `<path>...` arguments are given, only those paths
> -are affected.
> +If any optional `<pathspec>...` arguments are given, only those paths
> +that match the pathspec are affected.
OK. But ...
> OPTIONS
> -------
> -d::
> - Normally, when no <path> is specified, git clean will not
> + Normally, when no <pathspec> is specified, git clean will not
> recurse into untracked directories to avoid removing too much.
> Specify -d to have it recurse into such directories as well.
> If any paths are specified, -d is irrelevant; all untracked
... this "any paths are" needs the same treatment. I didn't point
out every instances of the same error in my previous review, but was
hoping that a reroll was done a bit more care than just fixing exact
locations pointed out.
There may be other such instances in this round, but this somehow
stood out in my quick scan. I am offline today, and will not
reading the other patches until tomorrow.
Thanks for working on the topic.
^ permalink raw reply [flat|nested] 230+ messages in thread
* [PATCH v4 17/34] doc txt & -h consistency: add or fix optional "--" syntax
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (15 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 18/34] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
` (16 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add the "[--]" for those cases where the *.txt and -h were
inconsistent, or where we incorrectly stated in one but not the other
that the "--" was mandatory.
In the case of "rev-list" both sides were wrong, as we we don't
require one or more paths if "--" is used, e.g. this is OK:
git rev-list HEAD --
That part of this change is not a "doc txt & -h consistency" change,
as we're changing both versions, doing so here makes both sides
consistent.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-rev-list.txt | 2 +-
builtin/for-each-repo.c | 2 +-
builtin/rev-list.c | 2 +-
builtin/verify-pack.c | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 20bb8e82176..51029a22715 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order
SYNOPSIS
--------
[verse]
-'git rev-list' [<options>] <commit>... [[--] <path>...]
+'git rev-list' [<options>] <commit>... [--] [<path>...]
DESCRIPTION
-----------
diff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c
index c6379b783c8..d45d873f579 100644
--- a/builtin/for-each-repo.c
+++ b/builtin/for-each-repo.c
@@ -6,7 +6,7 @@
#include "string-list.h"
static const char * const for_each_repo_usage[] = {
- N_("git for-each-repo --config=<config> <arguments>"),
+ N_("git for-each-repo --config=<config> [--] <arguments>"),
NULL
};
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index ada68a4af5e..3acd93f71e1 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -20,7 +20,7 @@
#include "packfile.h"
static const char rev_list_usage[] =
-"git rev-list [<options>] <commit>... [-- <path>...]\n"
+"git rev-list [<options>] <commit>... [--] [<path>...]\n"
"\n"
" limiting output:\n"
" --max-count=<n>\n"
diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c
index db9ac5c4606..27d6f75fd8a 100644
--- a/builtin/verify-pack.c
+++ b/builtin/verify-pack.c
@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has
}
static const char * const verify_pack_usage[] = {
- N_("git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx..."),
+ N_("git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx..."),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 18/34] doc txt & -h consistency: make output order consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (16 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 17/34] doc txt & -h consistency: add or fix optional "--" syntax Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 19/34] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
` (15 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix cases where the SYNOPSIS and -h output was presented in a
different order.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/merge-base.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/builtin/merge-base.c b/builtin/merge-base.c
index a11f8c6e4bb..6f3941f2a49 100644
--- a/builtin/merge-base.c
+++ b/builtin/merge-base.c
@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)
static const char * const merge_base_usage[] = {
N_("git merge-base [-a | --all] <commit> <commit>..."),
N_("git merge-base [-a | --all] --octopus <commit>..."),
- N_("git merge-base --independent <commit>..."),
N_("git merge-base --is-ancestor <commit> <commit>"),
+ N_("git merge-base --independent <commit>..."),
N_("git merge-base --fork-point <ref> [<commit>]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 19/34] doc txt & -h consistency: add missing options and labels
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (17 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 18/34] doc txt & -h consistency: make output order consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 20/34] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
` (14 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Fix various issues of SYNOPSIS and -h output syntax where:
* Options such as --force were missing entirely
* ...or the short option, such as -f
* We said "opts" or "options", but could instead enumerate
the (small) set of supported options
* Options that were missing entirely (ls-remote's --sort=<key>)
As we can specify "--sort" multiple times (it's backed by a
string-list" it should really be "[(--sort=<key>)...]", which is
what "git for-each-ref" lists it as, but let's leave that issue for
a subsequent cleanup, and stop at making these consistent. Other
"ref-filter.h" users share the same issue, e.g. "git-branch.txt".
* For "verify-tag" and "verify-commit" we were missing the "--raw"
option.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-send-pack.txt | 3 ++-
Documentation/git-sparse-checkout.txt | 2 +-
Documentation/git-update-server-info.txt | 8 +++++++-
Documentation/git-verify-commit.txt | 2 +-
Documentation/git-verify-tag.txt | 2 +-
builtin/credential-cache--daemon.c | 2 +-
builtin/describe.c | 5 +++--
builtin/diff-index.c | 2 +-
builtin/ls-remote.c | 2 +-
builtin/pack-refs.c | 2 +-
builtin/revert.c | 9 +++++----
builtin/send-pack.c | 1 +
builtin/symbolic-ref.c | 5 +++--
builtin/tag.c | 10 ++++++----
builtin/update-server-info.c | 2 +-
builtin/upload-pack.c | 3 ++-
builtin/verify-commit.c | 2 +-
builtin/verify-tag.c | 2 +-
help.c | 2 +-
19 files changed, 40 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index e0c71623432..595b002152f 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository
SYNOPSIS
--------
[verse]
-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+'git send-pack' [--mirror] [--dry-run] [--force]
+ [--receive-pack=<git-receive-pack>]
[--verbose] [--thin] [--atomic]
[--[no-]signed | --signed=(true|false|if-asked)]
[<host>:]<directory> (--all | <ref>...)
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 872436d7426..68392d2a56e 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
SYNOPSIS
--------
[verse]
-'git sparse-checkout' <subcommand> [<options>]
+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]
DESCRIPTION
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt
index 969bb2e15f1..17e429dbd09 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.txt
@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers
SYNOPSIS
--------
[verse]
-'git update-server-info'
+'git update-server-info' [-f | --force]
DESCRIPTION
-----------
@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover
what references and packs the server has. This command
generates such auxiliary files.
+OPTIONS
+-------
+-f::
+--force::
+ update the info files from scratch.
+
OUTPUT
------
diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt
index 92097f6673d..aee4c40eac4 100644
--- a/Documentation/git-verify-commit.txt
+++ b/Documentation/git-verify-commit.txt
@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits
SYNOPSIS
--------
[verse]
-'git verify-commit' <commit>...
+'git verify-commit' [-v | --verbose] [--raw] <commit>...
DESCRIPTION
-----------
diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
index 0b8075dad96..81d50ecc4c6 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.txt
@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags
SYNOPSIS
--------
[verse]
-'git verify-tag' [--format=<format>] <tag>...
+'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index ca672a6a619..d4eb0097d24 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [opts] <socket-path>",
+ "git-credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
diff --git a/builtin/describe.c b/builtin/describe.c
index e17c4b4c69b..23e3f05fb10 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -23,8 +23,9 @@
define_commit_slab(commit_names, struct commit_name *);
static const char * const describe_usage[] = {
- N_("git describe [<options>] [<commit-ish>...]"),
- N_("git describe [<options>] --dirty"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]"),
+ N_("git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]"),
+ N_("git describe <blob>"),
NULL
};
diff --git a/builtin/diff-index.c b/builtin/diff-index.c
index e667cf52e7d..aea139b9d8f 100644
--- a/builtin/diff-index.c
+++ b/builtin/diff-index.c
@@ -9,7 +9,7 @@
#include "submodule.h"
static const char diff_cache_usage[] =
-"git diff-index [-m] [--cached] "
+"git diff-index [-m] [--cached] [--merge-base] "
"[<common-diff-options>] <tree-ish> [<path>...]"
"\n"
COMMON_DIFF_OPTIONS_HELP;
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index df44e5cc0d1..5d5ac038716 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -7,7 +7,7 @@
static const char * const ls_remote_usage[] = {
N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
- " [-q | --quiet] [--exit-code] [--get-url]\n"
+ " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
" [--symref] [<repository> [<refs>...]]"),
NULL
};
diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c
index cfbd5c36c76..27c2ca06acb 100644
--- a/builtin/pack-refs.c
+++ b/builtin/pack-refs.c
@@ -5,7 +5,7 @@
#include "repository.h"
static char const * const pack_refs_usage[] = {
- N_("git pack-refs [<options>]"),
+ N_("git pack-refs [--all] [--no-prune]"),
NULL
};
diff --git a/builtin/revert.c b/builtin/revert.c
index ee2a0807f01..ee32c714a76 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -21,14 +21,15 @@
*/
static const char * const revert_usage[] = {
- N_("git revert [<options>] <commit-ish>..."),
- N_("git revert <subcommand>"),
+ N_("git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>..."),
+ N_("git revert (--continue | --skip | --abort | --quit)"),
NULL
};
static const char * const cherry_pick_usage[] = {
- N_("git cherry-pick [<options>] <commit-ish>..."),
- N_("git cherry-pick <subcommand>"),
+ N_("git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n"
+ " [-S[<keyid>]] <commit>..."),
+ N_("git cherry-pick (--continue | --skip | --abort | --quit)"),
NULL
};
diff --git a/builtin/send-pack.c b/builtin/send-pack.c
index 64962be0168..4c5d125fa0a 100644
--- a/builtin/send-pack.c
+++ b/builtin/send-pack.c
@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {
N_("git send-pack [--mirror] [--dry-run] [--force]\n"
" [--receive-pack=<git-receive-pack>]\n"
" [--verbose] [--thin] [--atomic]\n"
+ " [--[no-]signed | --signed=(true|false|if-asked)]\n"
" [<host>:]<directory> (--all | <ref>...)"),
NULL,
};
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index 1b0f10225f0..50b6df78df0 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -5,8 +5,9 @@
#include "parse-options.h"
static const char * const git_symbolic_ref_usage[] = {
- N_("git symbolic-ref [<options>] <name> [<ref>]"),
- N_("git symbolic-ref -d [-q] <name>"),
+ N_("git symbolic-ref [-m <reason>] <name> <ref>"),
+ N_("git symbolic-ref [-q] [--short] <name>"),
+ N_("git symbolic-ref --delete [-q] <name>"),
NULL
};
diff --git a/builtin/tag.c b/builtin/tag.c
index 75dece0e4f1..d428c45dc8d 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -23,11 +23,13 @@
#include "date.h"
static const char * const git_tag_usage[] = {
- N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\n"
- " <tagname> [<head>]"),
+ N_("git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n"
+ " <tagname> [<commit> | <object>]"),
N_("git tag -d <tagname>..."),
- N_("git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\n"
- " [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
+ N_("git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n"
+ " [--points-at <object>] [--column[=<options>] | --no-column]\n"
+ " [--create-reflog] [--sort=<key>] [--format=<format>]\n"
+ " [--merged <commit>] [--no-merged <commit>] [<pattern>...]"),
N_("git tag -v [--format=<format>] <tagname>..."),
NULL
};
diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c
index 880fffec587..d2239c9ef4d 100644
--- a/builtin/update-server-info.c
+++ b/builtin/update-server-info.c
@@ -4,7 +4,7 @@
#include "parse-options.h"
static const char * const update_server_info_usage[] = {
- "git update-server-info [--force]",
+ "git update-server-info [-f | --force]",
NULL
};
diff --git a/builtin/upload-pack.c b/builtin/upload-pack.c
index 125af53885f..25b69da2bf2 100644
--- a/builtin/upload-pack.c
+++ b/builtin/upload-pack.c
@@ -8,7 +8,8 @@
#include "serve.h"
static const char * const upload_pack_usage[] = {
- N_("git upload-pack [<options>] <dir>"),
+ N_("git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\n"
+ " [--advertise-refs] <directory>"),
NULL
};
diff --git a/builtin/verify-commit.c b/builtin/verify-commit.c
index 40c69a0bedd..3ebad32b0f1 100644
--- a/builtin/verify-commit.c
+++ b/builtin/verify-commit.c
@@ -16,7 +16,7 @@
#include "gpg-interface.h"
static const char * const verify_commit_usage[] = {
- N_("git verify-commit [-v | --verbose] <commit>..."),
+ N_("git verify-commit [-v | --verbose] [--raw] <commit>..."),
NULL
};
diff --git a/builtin/verify-tag.c b/builtin/verify-tag.c
index f45136a06ba..217566952d8 100644
--- a/builtin/verify-tag.c
+++ b/builtin/verify-tag.c
@@ -15,7 +15,7 @@
#include "ref-filter.h"
static const char * const verify_tag_usage[] = {
- N_("git verify-tag [-v | --verbose] [--format=<format>] <tag>..."),
+ N_("git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>..."),
NULL
};
diff --git a/help.c b/help.c
index d04542d8261..f1e090a4428 100644
--- a/help.c
+++ b/help.c
@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)
struct strbuf buf = STRBUF_INIT;
int build_options = 0;
const char * const usage[] = {
- N_("git version [<options>]"),
+ N_("git version [--build-options]"),
NULL
};
struct option options[] = {
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 20/34] doc txt & -h consistency: make "rerere" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (18 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 19/34] doc txt & -h consistency: add missing options and labels Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 21/34] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
` (13 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
For "rerere" say "pathspec" consistently, and list the subcommands in
the order that they're discussed in the "COMMANDS" section of the
documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-rerere.txt | 2 +-
builtin/rerere.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index 9d0e6f53e7e..992b469270c 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
SYNOPSIS
--------
[verse]
-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]
+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]
DESCRIPTION
-----------
diff --git a/builtin/rerere.c b/builtin/rerere.c
index 12570537d37..8b7392d5b44 100644
--- a/builtin/rerere.c
+++ b/builtin/rerere.c
@@ -10,7 +10,7 @@
#include "pathspec.h"
static const char * const rerere_usage[] = {
- N_("git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]"),
+ N_("git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]"),
NULL,
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 21/34] doc txt & -h consistency: make "read-tree" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (19 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 20/34] doc txt & -h consistency: make "rerere" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 22/34] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
` (12 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The C version was right to use "()" in place of "[]" around the option
listing, let's update the *.txt version accordingly, and furthermore
list the *.c options in the same order as the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-read-tree.txt | 2 +-
builtin/read-tree.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index b9bfdc0a319..7567955bad8 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index
SYNOPSIS
--------
[verse]
-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)
[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index b3a389e1b1f..f4cbe460b97 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)
static const char * const read_tree_usage[] = {
N_("git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n"
- " [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\n"
+ " [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n"
" (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 22/34] doc txt & -h consistency: make "bundle" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (20 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 21/34] doc txt & -h consistency: make "read-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
` (11 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend the -h output to match that of the *.txt output, the differences
were fairly small. In the case of "[<options>]" we only have a few of
them, so let's exhaustively list them as in the *.txt.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/bundle.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 1b08700bf9e..544c78a5f3a 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,13 +12,14 @@
*/
#define BUILTIN_BUNDLE_CREATE_USAGE \
- N_("git bundle create [<options>] <file> <git-rev-list args>")
+ N_("git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\n" \
+ " [--version=<version>] <file> <git-rev-list-args>")
#define BUILTIN_BUNDLE_VERIFY_USAGE \
- N_("git bundle verify [<options>] <file>")
+ N_("git bundle verify [-q | --quiet] <file>")
#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \
N_("git bundle list-heads <file> [<refname>...]")
#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \
- N_("git bundle unbundle <file> [<refname>...]")
+ N_("git bundle unbundle [--progress] <file> [<refname>...]")
static char const * const builtin_bundle_usage[] = {
BUILTIN_BUNDLE_CREATE_USAGE,
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (21 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 22/34] doc txt & -h consistency: make "bundle" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 24/34] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
` (10 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Use the "git cmd" form instead of "git-cmd" for both "git
receive-pack" and "git credential-cache--daemon".
For "git-receive-pack" we do have a binary with that name, even when
installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes
of the SYNOPSIS let's use the "git cmd" form like everywhere else. It
can be invoked like that (and our tests do so), the parts of our
documentation that explain when you need to use the dashed form do so,
and use it.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-receive-pack.txt | 2 +-
builtin/credential-cache--daemon.c | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 5c297db1a4b..65ff518ccff 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
[verse]
-'git-receive-pack' <git-dir>
+'git receive-pack' <git-dir>
DESCRIPTION
-----------
diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index d4eb0097d24..f3c89831d4a 100644
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
const char *socket_path;
int ignore_sighup = 0;
static const char *usage[] = {
- "git-credential-cache--daemon [--debug] <socket-path>",
+ "git credential-cache--daemon [--debug] <socket-path>",
NULL
};
int debug = 0;
@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
{
const char * const usage[] = {
- "git credential-cache--daemon [options] <action>",
+ "git credential-cache--daemon [--debug] <socket-path>",
"",
"credential-cache--daemon is disabled in this build of Git",
NULL
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 24/34] doc txt & -h consistency: add missing options
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (22 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 23/34] doc txt & -h consistency: use "git foo" form, not "git-foo" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 25/34] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change those built-in commands that were attempting to exhaustively
list the options in the "-h" output to actually do so, and always
have *.txt documentation know about the exhaustive list of options.
Let's also fix the documentation and -h output for those built-in
commands where the *.txt and -h output was a mismatch of missing
options on both sides.
In the case of "interpret-trailers" fixing the missing options reveals
that the *.txt version was implicitly claiming that the command had
two operating modes, which a look at the -h version (and studying the
documentation) will show is not the case.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-commit-graph.txt | 5 ++++-
Documentation/git-interpret-trailers.txt | 5 +++--
builtin/commit-tree.c | 1 +
builtin/fsck.c | 5 ++++-
builtin/hash-object.c | 4 ++--
builtin/init-db.c | 2 ++
builtin/interpret-trailers.c | 2 +-
builtin/rm.c | 4 +++-
8 files changed, 20 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 36fe56c2c71..c8dbceba014 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -10,7 +10,10 @@ SYNOPSIS
--------
[verse]
'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]
+'git commit-graph write' [--object-dir <dir>] [--append]
+ [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+ [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+ <split options>
DESCRIPTION
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 6d6197cd0a4..22ff3a603e0 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages
SYNOPSIS
--------
[verse]
-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
-'git interpret-trailers' [<options>] [--parse] [<file>...]
+'git interpret-trailers' [--in-place] [--trim-empty]
+ [(--trailer <token>[(=|:)<value>])...]
+ [--parse] [<file>...]
DESCRIPTION
-----------
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index e4b85d29d56..cc8d584be2f 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -15,6 +15,7 @@
#include "parse-options.h"
static const char * const commit_tree_usage[] = {
+ N_("git commit-tree <tree> [(-p <parent>)...]"),
N_("git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\n"
" [(-F <file>)...] <tree>"),
NULL
diff --git a/builtin/fsck.c b/builtin/fsck.c
index f7916f06ed5..ef273321d0b 100644
--- a/builtin/fsck.c
+++ b/builtin/fsck.c
@@ -821,7 +821,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,
}
static char const * const fsck_usage[] = {
- N_("git fsck [<options>] [<object>...]"),
+ N_("git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n"
+ " [--[no-]full] [--strict] [--verbose] [--lost-found]\n"
+ " [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n"
+ " [--[no-]name-objects] [<object>...]"),
NULL
};
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
index f7c16802f0c..b5063815020 100644
--- a/builtin/hash-object.c
+++ b/builtin/hash-object.c
@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)
{
static const char * const hash_object_usage[] = {
N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\n"
- " [--stdin] [--] <file>..."),
- "git hash-object --stdin-paths",
+ " [--stdin [--literally]] [--] <file>..."),
+ N_("git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]"),
NULL
};
const char *type = blob_type;
diff --git a/builtin/init-db.c b/builtin/init-db.c
index 08ba006d55e..dcaaf102eaf 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)
static const char *const init_db_usage[] = {
N_("git init [-q | --quiet] [--bare] [--template=<template-directory>]\n"
+ " [--separate-git-dir <git-dir>] [--object-format=<format>]\n"
+ " [-b <branch-name> | --initial-branch=<branch-name>]\n"
" [--shared[=<permissions>]] [<directory>]"),
NULL
};
diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c
index 4cf0cf265dc..e58627c72a9 100644
--- a/builtin/interpret-trailers.c
+++ b/builtin/interpret-trailers.c
@@ -15,7 +15,7 @@
static const char * const git_interpret_trailers_usage[] = {
N_("git interpret-trailers [--in-place] [--trim-empty]\n"
" [(--trailer <token>[(=|:)<value>])...]\n"
- " [<file>...]"),
+ " [--parse] [<file>...]"),
NULL
};
diff --git a/builtin/rm.c b/builtin/rm.c
index b6ba859fe42..f0d025a4e23 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -17,7 +17,9 @@
#include "pathspec.h"
static const char * const builtin_rm_usage[] = {
- N_("git rm [<options>] [--] <file>..."),
+ N_("git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n"
+ " [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 25/34] doc txt & -h consistency: make "stash" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (23 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 24/34] doc txt & -h consistency: add missing options Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 26/34] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Amend both the -h output and *.txt to match one another. In this case
the *.txt didn't list the "save" subcommand, and the "-h" was
similarly missing some commands.
Let's also convert the *.c code to use a macro definition, similar to
that used in preceding commits. This avoids duplication.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-stash.txt | 5 ++-
builtin/stash.c | 73 ++++++++++++++++++++++++-------------
2 files changed, 52 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index ea16d2eae7c..f4bb6114d91 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -11,12 +11,15 @@ SYNOPSIS
'git stash' list [<log-options>]
'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
'git stash' drop [-q | --quiet] [<stash>]
-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]
+'git stash' pop [--index] [-q | --quiet] [<stash>]
+'git stash' apply [--index] [-q | --quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
[-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
[--pathspec-from-file=<file> [--pathspec-file-nul]]
[--] [<pathspec>...]]
+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+ [-u | --include-untracked] [-a | --all] [<message>]
'git stash' clear
'git stash' create [<message>]
'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
diff --git a/builtin/stash.c b/builtin/stash.c
index 83c9591ea6d..bb5485b4095 100644
--- a/builtin/stash.c
+++ b/builtin/stash.c
@@ -21,72 +21,95 @@
#define INCLUDE_ALL_FILES 2
+#define BUILTIN_STASH_LIST_USAGE \
+ N_("git stash list [<log-options>]")
+#define BUILTIN_STASH_SHOW_USAGE \
+ N_("git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]")
+#define BUILTIN_STASH_DROP_USAGE \
+ N_("git stash drop [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_POP_USAGE \
+ N_("git stash pop [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_APPLY_USAGE \
+ N_("git stash apply [--index] [-q | --quiet] [<stash>]")
+#define BUILTIN_STASH_BRANCH_USAGE \
+ N_("git stash branch <branchname> [<stash>]")
+#define BUILTIN_STASH_STORE_USAGE \
+ N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>")
+#define BUILTIN_STASH_PUSH_USAGE \
+ N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n" \
+ " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n" \
+ " [--] [<pathspec>...]]")
+#define BUILTIN_STASH_SAVE_USAGE \
+ N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n" \
+ " [-u | --include-untracked] [-a | --all] [<message>]")
+#define BUILTIN_STASH_CREATE_USAGE \
+ N_("git stash create [<message>]")
+#define BUILTIN_STASH_CLEAR_USAGE \
+ "git stash clear"
+
static const char * const git_stash_usage[] = {
- N_("git stash list [<log-options>]"),
- N_("git stash show [<options>] [<stash>]"),
- N_("git stash drop [-q | --quiet] [<stash>]"),
- N_("git stash (pop | apply) [--index] [-q | --quiet] [<stash>]"),
- N_("git stash branch <branchname> [<stash>]"),
- "git stash clear",
- N_("git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
- " [--] [<pathspec>...]]"),
- N_("git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_LIST_USAGE,
+ BUILTIN_STASH_SHOW_USAGE,
+ BUILTIN_STASH_DROP_USAGE,
+ BUILTIN_STASH_POP_USAGE,
+ BUILTIN_STASH_APPLY_USAGE,
+ BUILTIN_STASH_BRANCH_USAGE,
+ BUILTIN_STASH_PUSH_USAGE,
+ BUILTIN_STASH_SAVE_USAGE,
+ BUILTIN_STASH_CLEAR_USAGE,
+ BUILTIN_STASH_CREATE_USAGE,
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_list_usage[] = {
- N_("git stash list [<options>]"),
+ BUILTIN_STASH_LIST_USAGE,
NULL
};
static const char * const git_stash_show_usage[] = {
- N_("git stash show [<options>] [<stash>]"),
+ BUILTIN_STASH_SHOW_USAGE,
NULL
};
static const char * const git_stash_drop_usage[] = {
- N_("git stash drop [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_DROP_USAGE,
NULL
};
static const char * const git_stash_pop_usage[] = {
- N_("git stash pop [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_POP_USAGE,
NULL
};
static const char * const git_stash_apply_usage[] = {
- N_("git stash apply [--index] [-q | --quiet] [<stash>]"),
+ BUILTIN_STASH_APPLY_USAGE,
NULL
};
static const char * const git_stash_branch_usage[] = {
- N_("git stash branch <branchname> [<stash>]"),
+ BUILTIN_STASH_BRANCH_USAGE,
NULL
};
static const char * const git_stash_clear_usage[] = {
- "git stash clear",
+ BUILTIN_STASH_CLEAR_USAGE,
NULL
};
static const char * const git_stash_store_usage[] = {
- N_("git stash store [(-m | --message) <message>] [-q | --quiet] <commit>"),
+ BUILTIN_STASH_STORE_USAGE,
NULL
};
static const char * const git_stash_push_usage[] = {
- N_("git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n"
- " [--] [<pathspec>...]]"),
+ BUILTIN_STASH_PUSH_USAGE,
NULL
};
static const char * const git_stash_save_usage[] = {
- N_("git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\n"
- " [-u | --include-untracked] [-a | --all] [<message>]"),
+ BUILTIN_STASH_SAVE_USAGE,
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 26/34] doc txt & -h consistency: make "annotate" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (24 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 25/34] doc txt & -h consistency: make "stash" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
The cmd_blame() already detected whether it was processing "blame" or
"annotate", but it didn't adjust its usage output accordingly. Let's
do that.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-annotate.txt | 2 +-
builtin/blame.c | 22 ++++++++++++++++------
2 files changed, 17 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt
index e44a831339d..5ae8aabe0f8 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.txt
@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information
SYNOPSIS
--------
[verse]
-'git annotate' [<options>] <file> [<revision>]
+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>
DESCRIPTION
-----------
diff --git a/builtin/blame.c b/builtin/blame.c
index a9fe8cf7a68..71f925e456c 100644
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -30,6 +30,7 @@
#include "tag.h"
static char blame_usage[] = N_("git blame [<options>] [<rev-opts>] [<rev>] [--] <file>");
+static char annotate_usage[] = N_("git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>");
static const char *blame_opt_usage[] = {
blame_usage,
@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {
NULL
};
+static const char *annotate_opt_usage[] = {
+ annotate_usage,
+ "",
+ N_("<rev-opts> are documented in git-rev-list(1)"),
+ NULL
+};
+
static int longest_file;
static int longest_author;
static int max_orig_digits;
@@ -899,6 +907,8 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
long anchor;
const int hexsz = the_hash_algo->hexsz;
long num_lines = 0;
+ const char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;
+ const char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;
setup_default_color_by_age();
git_config(git_blame_config, &output_option);
@@ -914,7 +924,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
parse_options_start(&ctx, argc, argv, prefix, options,
PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);
for (;;) {
- switch (parse_options_step(&ctx, options, blame_opt_usage)) {
+ switch (parse_options_step(&ctx, options, opt_usage)) {
case PARSE_OPT_NON_OPTION:
case PARSE_OPT_UNKNOWN:
break;
@@ -934,7 +944,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
ctx.argv[0] = "--children";
reverse = 1;
}
- parse_revision_opt(&revs, &ctx, options, blame_opt_usage);
+ parse_revision_opt(&revs, &ctx, options, opt_usage);
}
parse_done:
revision_opts_finish(&revs);
@@ -1040,7 +1050,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
switch (argc - dashdash_pos - 1) {
case 2: /* (1b) */
if (argc != 4)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
/* reorder for the new way: <rev> -- <path> */
argv[1] = argv[3];
argv[3] = argv[2];
@@ -1051,11 +1061,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
argv[argc] = NULL;
break;
default:
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
}
} else {
if (argc < 2)
- usage_with_options(blame_opt_usage, options);
+ usage_with_options(opt_usage, options);
if (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */
path = add_prefix(prefix, argv[1]);
argv[1] = argv[2];
@@ -1113,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
nth_line_cb, &sb, lno, anchor,
&bottom, &top, sb.path,
the_repository->index))
- usage(blame_usage);
+ usage(str_usage);
if ((!lno && (top || bottom)) || lno < bottom)
die(Q_("file %s has only %lu line",
"file %s has only %lu lines",
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more"
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (25 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 26/34] doc txt & -h consistency: make "annotate" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 28/34] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Correct uses of "<label>..." where we really meant to say
"[<label>...]", i.e. the command in question taken an optional set of
"<label>". As the CodingGuidelines notes "[o]ptional parts [should be]
enclosed in square brackets".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-clean.txt | 2 +-
builtin/clean.c | 2 +-
builtin/commit.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 61b6d8667a4..62b5715ba1f 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree
SYNOPSIS
--------
[verse]
-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...
+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]
DESCRIPTION
-----------
diff --git a/builtin/clean.c b/builtin/clean.c
index 6f039f555b2..40ff2c578de 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;
static unsigned int colopts;
static const char *const builtin_clean_usage[] = {
- N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>..."),
+ N_("git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]"),
NULL
};
diff --git a/builtin/commit.c b/builtin/commit.c
index fcf9c85947e..21ad4ccbf87 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {
};
static const char * const builtin_status_usage[] = {
- N_("git status [<options>] [--] <pathspec>..."),
+ N_("git status [<options>] [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 28/34] doc txt & -h consistency: make "diff-tree" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (26 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 27/34] doc txt & -h consistency: use "[<label>...]" for "zero or more" Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 29/34] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "diff-tree -h" output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/diff-tree.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/builtin/diff-tree.c b/builtin/diff-tree.c
index 23f58702fa0..85e8c81e594 100644
--- a/builtin/diff-tree.c
+++ b/builtin/diff-tree.c
@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)
}
static const char diff_tree_usage[] =
-"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] "
-"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
+"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n"
+" [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\n"
+" [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n"
"\n"
" -r diff recursively\n"
" -c show combined diff for merge commits\n"
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 29/34] doc txt & -h consistency: make "commit" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (27 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 28/34] doc txt & -h consistency: make "diff-tree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 30/34] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "-h" output of "git commit" consistent with the *.txt version
by exhaustively listing the options that it takes.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/commit.c | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/builtin/commit.c b/builtin/commit.c
index 21ad4ccbf87..64f420bcbf6 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -40,7 +40,14 @@
#include "pretty.h"
static const char * const builtin_commit_usage[] = {
- N_("git commit [<options>] [--] <pathspec>..."),
+ N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\n"
+ " [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\n"
+ " [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\n"
+ " [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\n"
+ " [--date=<date>] [--cleanup=<mode>] [--[no-]status]\n"
+ " [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\n"
+ " [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\n"
+ " [--] [<pathspec>...]"),
NULL
};
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 30/34] reflog doc: list real subcommands up-front
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (28 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 29/34] doc txt & -h consistency: make "commit" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 31/34] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Change the "git reflog" documentation to exhaustively list the
subcommands it accepts in the SYNOPSIS, as opposed to leaving that for
a "[verse]" in the DESCRIPTION section. This documentation style was
added in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how
other commands which take subcommands are documented.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-reflog.txt | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 0537d4645be..ec64cbff4c6 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -8,14 +8,6 @@ git-reflog - Manage reflog information
SYNOPSIS
--------
-[verse]
-'git reflog' <subcommand> <options>
-
-DESCRIPTION
------------
-The command takes various subcommands, and different options
-depending on the subcommand:
-
[verse]
'git reflog' [show] [<log-options>] [<ref>]
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
@@ -25,6 +17,10 @@ depending on the subcommand:
[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
'git reflog exists' <ref>
+DESCRIPTION
+-----------
+This command manages the information recorded in the reflogs.
+
Reference logs, or "reflogs", record when the tips of branches and
other references were updated in the local repository. Reflogs are
useful in various Git commands, to specify the old value of a
@@ -33,7 +29,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point
to one week ago in this local repository", and so on. See
linkgit:gitrevisions[7] for more details.
-This command manages the information recorded in the reflogs.
+The command takes various subcommands, and different options
+depending on the subcommand:
The "show" subcommand (which is also the default, in the absence of
any subcommands) shows the log of the reference provided in the
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 31/34] worktree: define subcommand -h in terms of command -h
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (29 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 30/34] reflog doc: list real subcommands up-front Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 32/34] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Avoid repeating the "-h" output for the "git worktree" command, and
instead define the usage of each subcommand with macros, so that the
"-h" output for the command itself can re-use those definitions. See
[1], [2] and [3] for prior art using the same pattern.
1. b25b727494f (builtin/multi-pack-index.c: define common usage with a
macro, 2021-03-30)
2. 8757b35d443 (commit-graph: define common usage with a macro,
2021-08-23)
3. 1e91d3faf6c (reflog: move "usage" variables and use macros,
2022-03-17)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------
1 file changed, 84 insertions(+), 25 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 5bfc18e5a24..ba6846c3788 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -15,15 +15,72 @@
#include "worktree.h"
#include "quote.h"
-static const char * const worktree_usage[] = {
- N_("git worktree add [<options>] <path> [<commit-ish>]"),
- N_("git worktree list [<options>]"),
- N_("git worktree lock [<options>] <path>"),
- N_("git worktree move <worktree> <new-path>"),
- N_("git worktree prune [<options>]"),
- N_("git worktree remove [<options>] <worktree>"),
- N_("git worktree repair [<path>...]"),
- N_("git worktree unlock <worktree>"),
+#define BUILTIN_WORKTREE_ADD_USAGE \
+ N_("git worktree add [<options>] <path> [<commit-ish>]")
+#define BUILTIN_WORKTREE_LIST_USAGE \
+ N_("git worktree list [<options>]")
+#define BUILTIN_WORKTREE_LOCK_USAGE \
+ N_("git worktree lock [<options>] <path>")
+#define BUILTIN_WORKTREE_MOVE_USAGE \
+ N_("git worktree move <worktree> <new-path>")
+#define BUILTIN_WORKTREE_PRUNE_USAGE \
+ N_("git worktree prune [<options>]")
+#define BUILTIN_WORKTREE_REMOVE_USAGE \
+ N_("git worktree remove [<options>] <worktree>")
+#define BUILTIN_WORKTREE_REPAIR_USAGE \
+ N_("git worktree repair [<path>...]")
+#define BUILTIN_WORKTREE_UNLOCK_USAGE \
+ N_("git worktree unlock <worktree>")
+
+static const char * const git_worktree_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ BUILTIN_WORKTREE_LIST_USAGE,
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_add_usage[] = {
+ BUILTIN_WORKTREE_ADD_USAGE,
+ NULL,
+};
+
+static const char * const git_worktree_list_usage[] = {
+ BUILTIN_WORKTREE_LIST_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_lock_usage[] = {
+ BUILTIN_WORKTREE_LOCK_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_move_usage[] = {
+ BUILTIN_WORKTREE_MOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_prune_usage[] = {
+ BUILTIN_WORKTREE_PRUNE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_remove_usage[] = {
+ BUILTIN_WORKTREE_REMOVE_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_repair_usage[] = {
+ BUILTIN_WORKTREE_REPAIR_USAGE,
+ NULL
+};
+
+static const char * const git_worktree_unlock_usage[] = {
+ BUILTIN_WORKTREE_UNLOCK_USAGE,
NULL
};
@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,
+ 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_prune_usage, options);
prune_worktrees();
return 0;
}
@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)
memset(&opts, 0, sizeof(opts));
opts.checkout = 1;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);
if (!!opts.detach + !!new_branch + !!new_branch_force > 1)
die(_("options '%s', '%s', and '%s' cannot be used together"), "-b", "-B", "--detach");
if (lock_reason && !keep_locked)
@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)
opts.keep_locked = _("added with --lock");
if (ac < 1 || ac > 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_add_usage, options);
path = prefix_filename(prefix, av[0]);
branch = ac < 2 ? "HEAD" : av[1];
@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)
};
expire = TIME_MAX;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);
if (ac)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_list_usage, options);
else if (verbose && porcelain)
die(_("options '%s' and '%s' cannot be used together"), "--verbose", "--porcelain");
else if (!line_terminator && !porcelain)
@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)
};
struct worktree **worktrees, *wt;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_lock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)
struct worktree **worktrees, *wt;
int ret;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_unlock_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
char *path;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_move_usage,
+ 0);
if (ac != 2)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_move_usage, options);
path = prefix_filename(prefix, av[1]);
strbuf_addstr(&dst, path);
@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)
const char *reason = NULL;
int ret = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);
if (ac != 1)
- usage_with_options(worktree_usage, options);
+ usage_with_options(git_worktree_remove_usage, options);
worktrees = get_worktrees();
wt = find_worktree(worktrees, prefix, av[0]);
@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)
};
int rc = 0;
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);
p = ac > 0 ? av : self;
for (; *p; p++)
repair_worktree_at_path(*p, report_repair, &rc);
@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)
if (!prefix)
prefix = "";
- ac = parse_options(ac, av, prefix, options, worktree_usage, 0);
+ ac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);
return fn(ac, av, prefix);
}
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 32/34] doc txt & -h consistency: make "worktree" consistent
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (30 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 31/34] worktree: define subcommand -h in terms of command -h Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 34/34] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Make the "worktree" -h output consistent with the *.txt version.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/worktree.c | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/builtin/worktree.c b/builtin/worktree.c
index ba6846c3788..4a24d53be15 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -16,17 +16,18 @@
#include "quote.h"
#define BUILTIN_WORKTREE_ADD_USAGE \
- N_("git worktree add [<options>] <path> [<commit-ish>]")
+ N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \
+ " [-b <new-branch>] <path> [<commit-ish>]")
#define BUILTIN_WORKTREE_LIST_USAGE \
- N_("git worktree list [<options>]")
+ N_("git worktree list [-v | --porcelain [-z]]")
#define BUILTIN_WORKTREE_LOCK_USAGE \
- N_("git worktree lock [<options>] <path>")
+ N_("git worktree lock [--reason <string>] <worktree>")
#define BUILTIN_WORKTREE_MOVE_USAGE \
N_("git worktree move <worktree> <new-path>")
#define BUILTIN_WORKTREE_PRUNE_USAGE \
- N_("git worktree prune [<options>]")
+ N_("git worktree prune [-n] [-v] [--expire <expire>]")
#define BUILTIN_WORKTREE_REMOVE_USAGE \
- N_("git worktree remove [<options>] <worktree>")
+ N_("git worktree remove [-f] <worktree>")
#define BUILTIN_WORKTREE_REPAIR_USAGE \
N_("git worktree repair [<path>...]")
#define BUILTIN_WORKTREE_UNLOCK_USAGE \
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (31 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 32/34] doc txt & -h consistency: make "worktree" consistent Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
2022-10-04 13:23 ` [PATCH v4 34/34] tests: assert consistent whitespace in " Ævar Arnfjörð Bjarmason
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
There's been a lot of incremental effort to make the SYNOPSIS output
in our documentation consistent with the -h output,
e.g. cbe485298bf (git reflog [expire|delete]: make -h output
consistent with SYNOPSIS, 2022-03-17) is one recent example, but that
effort has been an uphill battle due to the lack of regression
testing.
This adds such regression testing, we can parse out the SYNOPSIS
output with "sed", and it turns out it's relatively easy to normalize
it and the "-h" output to match on another.
We now ensure that we won't have regressions when it comes to the list
of commands in "expect_help_to_match_txt" below, and in subsequent
commits we'll make more of them consistent.
The naïve parser here gets quite a few things wrong, but it doesn't
need to be perfect, just good enough that we can compare /some/ of
this help output. There's no cases where the output would match except
for the parser's stupidity, it's all cases of e.g. comparing the *.txt
to non-parse_options() output.
Since that output is wildly different than the *.txt anyway let's
leave this for now, we can fix the parser some other time, or it won't
become necessary as we'll e.g. convert more things to using
parse_options().
Having a special-case for "merge-tree"'s 1f0c3a29da3 (merge-tree:
implement real merges, 2022-06-18) is a bit ugly, but preferred to
blessing that " (deprecated)" pattern for other commands. We'd
probably want to add some other way of marking deprecated commands in
the SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is
indistinguishable from the command taking an optional literal
"deprecated" string as an argument.
Some of the issues that are left:
* "git show -h", "git whatchanged -h" and "git reflog --oneline -h"
all showing "git log" and "git show" usage output. I.e. the
"builtin_log_usage" in builtin/log.c doesn't take into account what
command we're running.
* Commands which implement subcommands such as like
"multi-pack-index", "notes", "remote" etc. having their subcommands
in a very different order in the *.txt and *.c. Fixing it would
require some verbose diffs, so it's been left alone for now.
* Commands such as "format-patch" have a very long argument list in
the *.txt, but just "[<options>]" in the *.c.
What to do about these has been left out of this series, except to
the extent that preceding commits changed "[<options>]" (or
equivalent) to the list of options in cases where that list of
options was tiny, or we clearly meant to exhaustively list the
options in both *.txt and *.c.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 69 ++++++++++++++++++++++++++++++++++++-
t/t0450/txt-help-mismatches | 58 +++++++++++++++++++++++++++++++
2 files changed, 126 insertions(+), 1 deletion(-)
create mode 100644 t/t0450/txt-help-mismatches
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index efd00cfc51a..8fd20b6dba6 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -1,6 +1,9 @@
#!/bin/sh
-test_description='assert (unbuilt) Documentation/*.txt and -h output'
+test_description='assert (unbuilt) Documentation/*.txt and -h output
+
+Run this with --debug to see a summary of where we still fail to make
+the two versions consistent with one another.'
TEST_PASSES_SANITIZE_LEAK=true
. ./test-lib.sh
@@ -9,6 +12,14 @@ test_expect_success 'setup: list of builtins' '
git --list-cmds=builtins >builtins
'
+test_expect_success 'list of txt and help mismatches is sorted' '
+ sort -u "$TEST_DIRECTORY"/t0450/txt-help-mismatches >expect &&
+ if ! test_cmp expect "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ BUG "please keep the list of txt and help mismatches sorted"
+ fi
+'
+
help_to_synopsis () {
builtin="$1" &&
out_dir="out/$builtin" &&
@@ -49,6 +60,9 @@ txt_to_synopsis () {
/^$/d;
/^\[verse\]$/d;
+ s/{litdd}/--/g;
+ s/'\''\(git[ a-z-]*\)'\''/\1/g;
+
p;
}' \
<"$b2t" >"$out" &&
@@ -61,6 +75,15 @@ check_dashed_labels () {
HT=" "
+align_after_nl () {
+ builtin="$1" &&
+ len=$(printf "git %s " "$builtin" | wc -c) &&
+ pad=$(printf "%${len}s" "") &&
+
+ sed "s/^[ $HT][ $HT]*/$pad/"
+}
+
+test_debug '>failing'
while read builtin
do
# -h output assertions
@@ -85,6 +108,50 @@ do
test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
check_dashed_labels "$(txt_to_synopsis "$builtin")"
'
+
+ # *.txt output consistency assertions
+ result=
+ if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/txt-help-mismatches
+ then
+ result=failure
+ else
+ result=success
+ fi &&
+ test_expect_$result "$preq" "$builtin -h output and SYNOPSIS agree" '
+ t2s="$(txt_to_synopsis "$builtin")" &&
+ if test "$builtin" = "merge-tree"
+ then
+ test_when_finished "rm -f t2s.new" &&
+ sed -e '\''s/ (deprecated)$//g'\'' <"$t2s" >t2s.new
+ t2s=t2s.new
+ fi &&
+ h2s="$(help_to_synopsis "$builtin")" &&
+
+ # The *.txt and -h use different spacing for the
+ # alignment of continued usage output, normalize it.
+ align_after_nl "$builtin" <"$t2s" >txt &&
+ align_after_nl "$builtin" <"$h2s" >help &&
+ test_cmp txt help
+ '
+
+ if test_have_prereq "$preq" && test -e txt && test -e help
+ then
+ test_debug '
+ if test_cmp txt help >cmp 2>/dev/null
+ then
+ echo "=== DONE: $builtin ==="
+ else
+ echo "=== TODO: $builtin ===" &&
+ cat cmp
+ fi >>failing
+ '
+
+ # Not in test_expect_success in case --run is being
+ # used with --debug
+ rm -f txt help tmp 2>/dev/null
+ fi
done <builtins
+test_debug 'say "$(cat failing)"'
+
test_done
diff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches
new file mode 100644
index 00000000000..a0777acd667
--- /dev/null
+++ b/t/t0450/txt-help-mismatches
@@ -0,0 +1,58 @@
+add
+am
+apply
+archive
+bisect
+blame
+branch
+check-ref-format
+checkout
+checkout-index
+clone
+column
+config
+credential
+credential-cache
+credential-store
+fast-export
+fast-import
+fetch-pack
+fmt-merge-msg
+for-each-ref
+format-patch
+fsck-objects
+fsmonitor--daemon
+gc
+grep
+index-pack
+init-db
+log
+ls-files
+ls-tree
+mailinfo
+mailsplit
+maintenance
+merge
+merge-file
+merge-index
+merge-one-file
+multi-pack-index
+name-rev
+notes
+pack-objects
+push
+range-diff
+rebase
+remote
+remote-ext
+remote-fd
+repack
+reset
+restore
+rev-parse
+show
+stage
+switch
+update-index
+update-ref
+whatchanged
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread* [PATCH v4 34/34] tests: assert consistent whitespace in -h output
2022-10-04 13:23 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (32 preceding siblings ...)
2022-10-04 13:23 ` [PATCH v4 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output Ævar Arnfjörð Bjarmason
@ 2022-10-04 13:23 ` Ævar Arnfjörð Bjarmason
33 siblings, 0 replies; 230+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-10-04 13:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Victoria Dye, Taylor Blau, Emily Shaffer,
Jonathan Nieder, John Cai, Eric Sunshine,
Ævar Arnfjörð Bjarmason
Add a test for the *.txt and *.c output assertions which asserts that
for "-h" lines that aren't the "usage: " or " or: " lines they start
with the same amount of whitespace. This ensures that we won't have
buggy output like:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
Which should instead be like this, i.e. the options lines should be
aligned:
[...]
or: git tag [-n[<num>]]
[...]
[--create-reflog] [...]
It would be better to be able to use "test_cmp" here, i.e. to
construct the output we expect, and compare it against the actual
output.
For most built-in commands this would be rather straightforward. In
"t0450-txt-doc-vs-help.sh" we already compute the whitespace that a
"git-$builtin" needs, and strip away "usage: " or " or: " from the
start of lines. The problem is:
* For commands that implement subcommands, such as "git bundle", we
don't know whether e.g. "git bundle create" is the subcommand
"create", or the argument "create" to "bundle" for the purposes of
alignment.
We *do* have that information from the *.txt version, since the
part within the ''-quotes should be the command & subcommand, but
that isn't consistent (e.g. see "git bundle" and "git
commit-graph", only the latter is correct), and parsing that out
would be non-trivial.
* If we were to make this stricter we have various
non-parse_options() users (e.g. "git diff-tree") that don't have the
nicely aligned output which we've had since
4631cfc20bd (parse-options: properly align continued usage output,
2021-09-21).
So rather than make perfect the enemy of the good let's assert that
for those lines that are indented they should all use the same
indentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 8fd20b6dba6..cd3969e852b 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -96,6 +96,21 @@ do
check_dashed_labels "$(help_to_synopsis "$builtin")"
'
+ test_expect_success "$builtin -h output has consistent spacing" '
+ h2s="$(help_to_synopsis "$builtin")" &&
+ sed -n \
+ -e "/^ / {
+ s/[^ ].*//;
+ p;
+ }" \
+ <"$h2s" >help &&
+ sort -u help >help.ws &&
+ if test -s help.ws
+ then
+ test_line_count = 1 help.ws
+ fi
+ '
+
txt="$(builtin_to_txt "$builtin")" &&
preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
--
2.38.0.rc2.935.g6b421ae1592
^ permalink raw reply related [flat|nested] 230+ messages in thread