{"thread":{"id":"58397","subject":"[PATCH 00/34] doc/UX: make txt & -h output more consistent","startedAt":"2022-09-05T08:27:03Z","lastAt":"2022-10-13T16:33:53Z","messageCount":230,"participants":["Ævar Arnfjörð Bjarmason","Junio C Hamano","Victoria Dye","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":34},"messages":[{"id":"462586","messageId":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":null,"subject":"[PATCH 00/34] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:11Z","receivedAt":"2022-09-05T08:27:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"We are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nWe now have a test that checks that these are the same for all\nbuilt-ins. Out of 141 built-in commands we still have 58 cases that\ndiffer at the end of this series, but that's a lot better than before.\n\nThis series is 34 patches, but it's been structured in a way that\nreviewers should be able to mostly trust the \"doc txt & -h\nconsistency\" commits already. In all of those cases we already have\nthe post-image in-tree, it's just in either the *.txt or -h version,\nnot both. All of the \"doc txt & -h consistency\" commits merely make\nthose consistent together.\n\nAll of the commands and documentation altered by the \"doc txt & -h\nconsistency\" commits are then tested in 34/34, i.e. there are no\n\"loose ends\" where we partially \"fix\" something, but fail to fully\ntest it at the end (unless I missed something).\n\nJunio: This series merges cleanly with \"seen\", and I've intentionally\nleft out any changes that might conflict. If we get newlry queued\npatches that make things inconsistent the new test will fail. Perhaps\nwe should make them all \"TODO\" and flip the switch later, but we are\ngoing to have to test this for real at some point if we're going to\nstem the tide of these routinely drifting apart.\n\nÆvar Arnfjörð Bjarmason (34):\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n  bundle: define subcommand -h in terms of command -h\n  blame: use a more detailed usage_msg_optf() error on bad -L\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  doc SYNOPSIS & -h: fix incorrect alternates syntax\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n\n Documentation/CodingGuidelines                |  17 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |   6 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   2 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   2 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   2 +-\n Documentation/git-reflog.txt                  |  17 +-\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-send-pack.txt               |   3 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 +-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |   2 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  26 ++-\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 ++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 ++++---\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/worktree.c                            | 110 ++++++++---\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 179 ++++++++++++++++++\n 78 files changed, 530 insertions(+), 185 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462587","messageId":"patch-03.34-b49268615c3-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 03/34] bundle: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:14Z","receivedAt":"2022-09-05T08:27:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git bundle\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 29 +++++++++++++++++++----------\n 1 file changed, 19 insertions(+), 10 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 5c78894afd5..1b08700bf9e 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -11,31 +11,40 @@\n  * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n  */\n \n-static const char * const builtin_bundle_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-\tN_(\"git bundle verify [<options>] <file>\"),\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n-\tNULL\n+#define BUILTIN_BUNDLE_CREATE_USAGE \\\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n+\tN_(\"git bundle verify [<options>] <file>\")\n+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n+\tN_(\"git bundle list-heads <file> [<refname>...]\")\n+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n+\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\n+static char const * const builtin_bundle_usage[] = {\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n+\tNULL,\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-\tN_(\"git bundle verify [<options>] <file>\"),\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462588","messageId":"patch-02.34-66286fa3af7-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 02/34] builtin/bundle.c: use \\t, not fix indentation 2-SP indentation","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:13Z","receivedAt":"2022-09-05T08:27:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462589","messageId":"patch-04.34-22c3d1a73dc-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 04/34] blame: use a more detailed usage_msg_optf() error on bad -L","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:15Z","receivedAt":"2022-09-05T08:27:10Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Improve the error message emitted when there's a bad -L argument, and\ndo so using the parse-options.c flavor of \"usage()\", instead of using\nthe non-parse-options.c usage() function. This was the last user of\nusage() in this file.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/blame.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex a9fe8cf7a68..8ec59fa2096 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tanchor = 1;\n \trange_set_init(&ranges, range_list.nr);\n \tfor (range_i = 0; range_i < range_list.nr; ++range_i) {\n+\t\tconst char *arg = range_list.items[range_i].string;\n \t\tlong bottom, top;\n-\t\tif (parse_range_arg(range_list.items[range_i].string,\n-\t\t\t\t    nth_line_cb, &sb, lno, anchor,\n+\t\tif (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n-\t\t\tusage(blame_usage);\n+\t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n+\t\t\t\t       blame_opt_usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462590","messageId":"patch-01.34-b8cbd443987-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 01/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:12Z","receivedAt":"2022-09-05T08:27:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 4c756be517a..0d959f8c96b 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -650,8 +650,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -665,6 +665,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not on the inside of \"[]()\"\n+ tokens:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462591","messageId":"patch-05.34-dc66db38a62-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 05/34] doc SYNOPSIS: don't use ' for subcommands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:16Z","receivedAt":"2022-09-05T08:27:14Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Almost all of our documentation doesn't use \"'\" syntax for\nsubcommands, but these did, let's make them consistent with the\nrest.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex db9d46edfa9..0537d4645be 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [<log-options>] [<ref>]\n+'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4cfc8833780..4b613d4140c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n \n DESCRIPTION\n -----------\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462592","messageId":"patch-06.34-0b946d60fcc-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 06/34] doc SYNOPSIS: consistently use ' for commands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:17Z","receivedAt":"2022-09-05T08:27:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Most of our commands use ''-quotation only for the name of the command\nitself, and not its (optional) arguments. Let's do the same for these.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-export.txt     | 2 +-\n Documentation/git-sparse-checkout.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 1978dbdc6ad..4643ddbe68f 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [<options>]' | 'git fast-import'\n+'git fast-export' [<options>] | 'git fast-import'\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 3776705bf53..872436d7426 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [<options>]'\n+'git sparse-checkout' <subcommand> [<options>]\n \n \n DESCRIPTION\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462593","messageId":"patch-07.34-a070c97f29b-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 07/34] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:18Z","receivedAt":"2022-09-05T08:27:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nUnlike a preceding commit where this was fixed for commands which had\ninconsistent \"-h\" and *.txt, for \"stash\" it's been with us in both the\n\"-h\" and *.txt since bd514cada4b (stash: introduce 'git stash store',\n2013-06-15).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 6 +++---\n builtin/stash.c             | 6 +++---\n 2 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 6e15f475257..0df21321e50 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -14,12 +14,12 @@ SYNOPSIS\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n+\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n \n DESCRIPTION\n -----------\n@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n COMMANDS\n --------\n \n-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>...]::\n+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>...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 1ba24c11737..0fc359e9d39 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n \tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [-m|--message <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n \tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462594","messageId":"patch-08.34-75c39a2ff83-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 08/34] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:19Z","receivedAt":"2022-09-05T08:27:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change commands in the \"diff\" family and \"rev-list\" to separate the\nusage information and option listing with an empty line.\n\nIn the case of \"git diff -h\" we did this already (but let's use a\nconsistent \"\\n\" pattern there), for the rest these are now consistent\nwith how the parse_options() API would emit usage.\n\nAs we'll see in a subsequent commit this also helps to make the \"git\n<cmd> -h\" output more easily machine-readable, as we can assume that\nthe usage usage information is separated from the options by an empty\nline.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-files.c | 1 +\n builtin/diff-index.c | 1 +\n builtin/diff-tree.c  | 1 +\n builtin/diff.c       | 3 ++-\n builtin/rev-list.c   | 1 +\n 5 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/diff-files.c b/builtin/diff-files.c\nindex 92cf6e1e922..096ea2fedbc 100644\n--- a/builtin/diff-files.c\n+++ b/builtin/diff-files.c\n@@ -15,6 +15,7 @@\n \n static const char diff_files_usage[] =\n \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_files(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 7d158af6b6d..e667cf52e7d 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -11,6 +11,7 @@\n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 116097a404a..23f58702fa0 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)\n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n \"  --cc          show combined diff for merge commits removing uninteresting hunks\\n\"\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 54bb3de964c..67760b67552 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =\n \"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>\\n\"\n-\"   or: git diff [<options>] --no-index [--] <path> <path>\\n\"\n+\"   or: git diff [<options>] --no-index [--] <path> <path>\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n static const char *blob_path(struct object_array_entry *entry)\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex fba6f5d51f3..f67e2b33555 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -21,6 +21,7 @@\n \n static const char rev_list_usage[] =\n \"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n \"    --max-age=<epoch>\\n\"\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462595","messageId":"patch-10.34-965f6b3b3cb-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 10/34] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:21Z","receivedAt":"2022-09-05T08:27:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis syntax issue for \"bugreport\" originated in\n238b439d698 (bugreport: add tool to generate debugging info,\n2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\ncreate 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n\"bugreport\" documentation and code.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/diagnose.c  | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex faa268f3cfb..23170113cc8 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex c7672fa99e2..54491f2c51c 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462596","messageId":"patch-09.34-f79a6ead8b0-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 09/34] doc txt & -h consistency: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:20Z","receivedAt":"2022-09-05T08:27:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere the *.txt and -h output didn't match as far as word-wrapping was\nconcerned.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-hash-object.txt | 3 ++-\n Documentation/git-worktree.txt    | 3 ++-\n builtin/bugreport.c               | 3 ++-\n builtin/commit-graph.c            | 8 ++++----\n builtin/commit-tree.c             | 4 ++--\n builtin/diagnose.c                | 3 ++-\n builtin/init-db.c                 | 3 ++-\n builtin/interpret-trailers.c      | 4 +++-\n builtin/read-tree.c               | 4 +++-\n builtin/show-branch.c             | 3 ++-\n builtin/show-ref.c                | 4 +++-\n 11 files changed, 27 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex df9e2c58bdb..58670ef12f7 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+\t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \n DESCRIPTION\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex ada30c86a7c..063d6eeb99d 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees\n SYNOPSIS\n --------\n [verse]\n-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n+\t\t   [-b <new-branch>] <path> [<commit-ish>]\n 'git worktree list' [-v | --porcelain [-z]]\n 'git worktree lock' [--reason <string>] <worktree>\n 'git worktree move' <worktree> <new-path>\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 530895be55f..faa268f3cfb 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]\"),\n+\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex dc3cc353947..50b1a171566 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -13,10 +13,10 @@\n \tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append] \" \\\n-\t   \"[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] \" \\\n-\t   \"[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] \" \\\n-\t   \"<split options>\")\n+\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n+\t   \"                       <split options>\")\n \n static const char * builtin_commit_graph_verify_usage[] = {\n \tBUILTIN_COMMIT_GRAPH_VERIFY_USAGE,\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 63ea3229333..e4b85d29d56 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,8 +15,8 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n-\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] \"\n-\t\t\"[(-F <file>)...] <tree>\"),\n+\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n+\t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex cd260c20155..c7672fa99e2 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,8 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]\"),\n+\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 546f9c595e7..08ba006d55e 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n }\n \n static const char *const init_db_usage[] = {\n-\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]\"),\n+\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 84748eafc01..4cf0cf265dc 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -13,7 +13,9 @@\n #include \"config.h\"\n \n static const char * const git_interpret_trailers_usage[] = {\n-\tN_(\"git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]\"),\n+\tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n+\t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n+\t   \"                       [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 9f1f33e9546..b3a389e1b1f 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)\n }\n \n static const char * const read_tree_usage[] = {\n-\tN_(\"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+\tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n+\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n \ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex 64c649c6a23..6db13de8910 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {\n     N_(\"git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\\n\"\n        \"                [--current] [--color[=<when>] | --no-color] [--sparse]\\n\"\n        \"                [--more=<n> | --list | --independent | --merge-base]\\n\"\n-       \"                [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\"),\n+       \"                [--no-name | --sha1-name] [--topics]\\n\"\n+       \"                [(<rev> | <glob>)...]\"),\n     N_(\"git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\"),\n     NULL\n };\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 5fa207a044e..d807ef5c28b 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -9,7 +9,9 @@\n #include \"parse-options.h\"\n \n static const char * const show_ref_usage[] = {\n-\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]\"),\n+\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\\n\"\n+\t   \"             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\\n\"\n+\t   \"             [--heads] [--] [<pattern>...]\"),\n \tN_(\"git show-ref --exclude-existing[=<pattern>]\"),\n \tNULL\n };\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462597","messageId":"patch-11.34-698d8d3d53a-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 11/34] doc txt & -h consistency: add \"-z\" to cat-file \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:22Z","receivedAt":"2022-09-05T08:27:35Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited\ninput with `-z`, 2022-07-22), before that change the SYNOPSIS and \"-h\"\noutput were the same, but not afterwards.\n\nThat change followed a similar earlier divergence in\n473fa2df08d (Documentation: add --batch-command to cat-file synopsis,\n2022-04-07). Subsequent commits will fix this sort of thing more\nsystematically, but let's fix this one as a one-off.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/cat-file.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 989eee0bb4c..fa7bd891692 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] <object>\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t   \"             [--buffer] [--follow-symlinks] [--unordered]\\n\"\n-\t\t   \"             [--textconv | --filters]\"),\n+\t\t   \"             [--textconv | --filters] [-z]\"),\n \t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n \t\t   \"             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\"),\n \t\tNULL\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462598","messageId":"patch-12.34-55ce0f8632f-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 12/34] doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:23Z","receivedAt":"2022-09-05T08:27:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\nin aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n2022-08-12): We need to close the \"[\" we opened. The\ncorresponding *.txt change did not have the same issue.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 23170113cc8..bb138161943 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n \n static const char * const bugreport_usage[] = {\n \tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n-\t   \"              [--diagnose[=<mode>]\"),\n+\t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462599","messageId":"patch-13.34-d88690fa849-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 13/34] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:24Z","receivedAt":"2022-09-05T08:27:39Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-diff-files.txt     | 2 +-\n Documentation/git-merge-base.txt     | 4 ++--\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-prune-packed.txt   | 2 +-\n Documentation/git-rerere.txt         | 2 +-\n Documentation/git-show-branch.txt    | 4 ++--\n Documentation/git-show-ref.txt       | 4 ++--\n Documentation/git-var.txt            | 2 +-\n Documentation/git-verify-pack.txt    | 2 +-\n builtin/bugreport.c                  | 2 +-\n builtin/diagnose.c                   | 2 +-\n builtin/sparse-checkout.c            | 2 +-\n 12 files changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex bf1febb9ae7..591e3801b7b 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b01ba3d3565 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n+'git merge-base' [-a | --all] <commit> <commit>...\n+'git merge-base' [-a | --all] --octopus <commit>...\n 'git merge-base' --is-ancestor <commit> <commit>\n 'git merge-base' --independent <commit>...\n 'git merge-base' --fork-point <ref> [<commit>]\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e52..dda80a740c8 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 9fed59a3172..844d6f808a0 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n SYNOPSIS\n --------\n [verse]\n-'git prune-packed' [-n|--dry-run] [-q|--quiet]\n+'git prune-packed' [-n | --dry-run] [-q | --quiet]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4b613d4140c..9d0e6f53e7e 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 5cc2fcefbab..e0d71a208c4 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits\n SYNOPSIS\n --------\n [verse]\n-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n \t\t[(<rev> | <glob>)...]\n-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ab4d271925d..d1d56f68b43 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository\n SYNOPSIS\n --------\n [verse]\n-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]\n-\t     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]\n+\t     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n \t     [--heads] [--] [<pattern>...]\n 'git show-ref' --exclude-existing[=<pattern>]\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex 387cc1b9142..6aa521fab23 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -9,7 +9,7 @@ git-var - Show a Git logical variable\n SYNOPSIS\n --------\n [verse]\n-'git var' ( -l | <variable> )\n+'git var' (-l | <variable>)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c20..b8720dce8ab 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files\n SYNOPSIS\n --------\n [verse]\n-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n \n \n DESCRIPTION\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex bb138161943..61d93383f51 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 54491f2c51c..64a65e2842b 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 287716db68e..aac0f708e42 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init|list|set|add|reapply|disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462600","messageId":"patch-14.34-12ec2627504-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 14/34] stash doc SYNOPSIS & -h: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:25Z","receivedAt":"2022-09-05T08:27:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 12 ++++++------\n builtin/stash.c             | 28 ++++++++++++++--------------\n 2 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 0df21321e50..379bea645db 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,17 +9,17 @@ SYNOPSIS\n --------\n [verse]\n 'git stash' list [<log-options>]\n-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n-'git stash' drop [-q|--quiet] [<stash>]\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n+'git stash' drop [-q | --quiet] [<stash>]\n+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 0fc359e9d39..7d82ead6760 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -24,16 +24,16 @@\n static const char * const git_stash_usage[] = {\n \tN_(\"git stash list [<options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n-\tN_(\"git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n-\tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"               [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462601","messageId":"patch-16.34-1adbe9b7d12-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 16/34] t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:27Z","receivedAt":"2022-09-05T08:27:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"As in a preceding commit use \"<options>\", not \"<options>...\", in this\ncase there is no *.txt version, but let's fix this one too while we're\nat it.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/helper/test-proc-receive.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\nindex cc08506cf0b..a4b305f4947 100644\n--- a/t/helper/test-proc-receive.c\n+++ b/t/helper/test-proc-receive.c\n@@ -6,7 +6,7 @@\n #include \"test-tool.h\"\n \n static const char *proc_receive_usage[] = {\n-\t\"test-tool proc-receive [<options>...]\",\n+\t\"test-tool proc-receive [<options>]\",\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462602","messageId":"patch-15.34-33d47a8a827-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 15/34] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:26Z","receivedAt":"2022-09-05T08:27:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"It's arguably more correct to say \"[<option>...]\" than either of these\nforms, but the vast majority of our documentation uses the\n\"[<options>]\" form to indicate an arbitrary number of options, let's\ndo the same in these cases, which were the odd ones out.\n\nIn the case of \"mv\" let's add the missing \"[]\" to indicate that these\nare optional.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-mv.txt     | 2 +-\n Documentation/git-status.txt | 2 +-\n builtin/pack-objects.c       | 4 ++--\n 3 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 79449bf98fe..972a055fbd8 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' <options>... <args>...\n+'git mv' [<options>] <args>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 54a4b29b473..5e438a7fdc1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -9,7 +9,7 @@ git-status - Show the working tree status\n SYNOPSIS\n --------\n [verse]\n-'git status' [<options>...] [--] [<pathspec>...]\n+'git status' [<options>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 39e28cfcafc..f3ffeb4cd0f 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,\n #define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)\n \n static const char *pack_usage[] = {\n-\tN_(\"git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]\"),\n-\tN_(\"git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462603","messageId":"patch-17.34-517f9f9a53f-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 17/34] doc txt & -h consistency: fix mismatching labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:28Z","receivedAt":"2022-09-05T08:27:47Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various inconsistencies between command SYNOPSIS and the\ncorresponding -h output where our translatable labels didn't match\nup.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt                    | 6 +++---\n Documentation/git-credential-cache--daemon.txt | 2 +-\n Documentation/git-mv.txt                       | 2 +-\n Documentation/git-receive-pack.txt             | 2 +-\n Documentation/git-tag.txt                      | 2 +-\n Documentation/git-upload-archive.txt           | 4 ++--\n builtin/bugreport.c                            | 2 +-\n builtin/clean.c                                | 2 +-\n builtin/commit-graph.c                         | 4 ++--\n builtin/credential-cache--daemon.c             | 2 +-\n builtin/for-each-repo.c                        | 2 +-\n builtin/pack-redundant.c                       | 2 +-\n builtin/rerere.c                               | 2 +-\n builtin/rev-list.c                             | 2 +-\n builtin/stash.c                                | 2 +-\n builtin/unpack-file.c                          | 2 +-\n builtin/upload-archive.c                       | 2 +-\n builtin/worktree.c                             | 2 +-\n 18 files changed, 22 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex a7f309dff5a..13e3a0844f8 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\n-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n \n DESCRIPTION\n -----------\n@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n \n-If any optional `<path>...` arguments are given, only those paths\n+If any optional `<pathspec>...` arguments are given, only those paths\n are affected.\n \n OPTIONS\n -------\n -d::\n-\tNormally, when no <path> is specified, git clean will not\n+\tNormally, when no <pathspec> is specified, git clean will not\n \trecurse into untracked directories to avoid removing too much.\n \tSpecify -d to have it recurse into such directories as well.\n \tIf any paths are specified, -d is irrelevant; all untracked\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 01e1c214dd8..74832d06806 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 972a055fbd8..c612a5fd5b9 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [<options>] <args>...\n+'git mv' [<options>] <source>... <destination>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 014a78409b9..eec1268b10f 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31a97a1b6c5..c15ec895720 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n \t<tagname> [<commit> | <object>]\n 'git tag' -d <tagname>...\n 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex fba0f1c1b27..e8eb10baad7 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n SYNOPSIS\n --------\n [verse]\n-'git upload-archive' <directory>\n+'git upload-archive' <repository>\n \n DESCRIPTION\n -----------\n@@ -54,7 +54,7 @@ access via non-smart-http.\n \n OPTIONS\n -------\n-<directory>::\n+<repository>::\n \tThe repository to get a tar archive from.\n \n GIT\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 61d93383f51..96052541cbf 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 5466636e666..6f039f555b2 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 50b1a171566..0d906c4aa42 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -10,10 +10,10 @@\n #include \"tag.h\"\n \n #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n-\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n+\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n \t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex 4c6c89ab0de..ca672a6a619 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex fd86e5a8619..c6379b783c8 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <command-args>\"),\n+\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c\nindex ed9b9013a5f..ecd49ca268f 100644\n--- a/builtin/pack-redundant.c\n+++ b/builtin/pack-redundant.c\n@@ -14,7 +14,7 @@\n #define BLKSIZE 512\n \n static const char pack_redundant_usage[] =\n-\"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)\";\n+\"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\";\n \n static int load_all_packs, verbose, alt_odb;\n \ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 83d7a778e37..12570537d37 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <path>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n \tNULL,\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex f67e2b33555..ada68a4af5e 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 7d82ead6760..614bb0dd4a2 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -22,7 +22,7 @@\n #define INCLUDE_ALL_FILES 2\n \n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tN_(\"git stash list [<log-options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n \tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\ndiff --git a/builtin/unpack-file.c b/builtin/unpack-file.c\nindex 58652229f27..9e8119dd354 100644\n--- a/builtin/unpack-file.c\n+++ b/builtin/unpack-file.c\n@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)\n \tstruct object_id oid;\n \n \tif (argc != 2 || !strcmp(argv[1], \"-h\"))\n-\t\tusage(\"git unpack-file <sha1>\");\n+\t\tusage(\"git unpack-file <blob>\");\n \tif (get_oid(argv[1], &oid))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n \ndiff --git a/builtin/upload-archive.c b/builtin/upload-archive.c\nindex 98d028dae67..945ee2b4126 100644\n--- a/builtin/upload-archive.c\n+++ b/builtin/upload-archive.c\n@@ -10,7 +10,7 @@\n #include \"strvec.h\"\n \n static const char upload_archive_usage[] =\n-\t\"git upload-archive <repo>\";\n+\t\"git upload-archive <repository>\";\n \n static const char deadchild[] =\n \"git upload-archive: archiver died with error\";\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex c6710b25520..5bfc18e5a24 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {\n \tN_(\"git worktree prune [<options>]\"),\n \tN_(\"git worktree remove [<options>] <worktree>\"),\n \tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <path>\"),\n+\tN_(\"git worktree unlock <worktree>\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462604","messageId":"patch-18.34-df312ad3ceb-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 18/34] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:29Z","receivedAt":"2022-09-05T08:27:49Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add the \"[--]\" for those cases where the *.txt and -h were\ninconsistent, or where we incorrectly stated in one but not the other\nthat the \"--\" was mandatory.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/for-each-repo.c | 2 +-\n builtin/rev-list.c      | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex c6379b783c8..d45d873f579 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n+\tN_(\"git for-each-repo --config=<config> [--] <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex ada68a4af5e..3cc8aad52ed 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462605","messageId":"patch-21.34-50e1a8c2b1e-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 21/34] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:32Z","receivedAt":"2022-09-05T08:28:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\nthe order that they're discussed in the \"COMMANDS\" section of the\ndocumentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rerere.txt | 2 +-\n builtin/rerere.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 9d0e6f53e7e..992b469270c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 12570537d37..8b7392d5b44 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n \tNULL,\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462606","messageId":"patch-19.34-77cf58aa9c7-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 19/34] doc txt & -h consistency: make output order consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:30Z","receivedAt":"2022-09-05T08:28:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix cases where the SYNOPSIS and -h output was presented in a\ndifferent order.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/merge-base.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex a11f8c6e4bb..6f3941f2a49 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n static const char * const merge_base_usage[] = {\n \tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n \tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n+\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n \tNULL\n };\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462607","messageId":"patch-20.34-f6ecf6a38af-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 20/34] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:31Z","receivedAt":"2022-09-05T08:28:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various issues of SYNOPSIS and -h output syntax where:\n\n * Options such as --force were missing entirely\n * ...or the short option, such as -f\n\n * We said \"opts\" or \"options\", but could instead enumerate\n   the (small) set of supported options\n\n * argument labels were missing entirely (ls-remote)\n\n * How we referred to an argument was inconsistent between the two,\n   e.g. <pack> v.s. <pack>.idx.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-send-pack.txt          |  3 ++-\n Documentation/git-sparse-checkout.txt    |  2 +-\n Documentation/git-update-server-info.txt |  8 +++++++-\n Documentation/git-verify-commit.txt      |  2 +-\n Documentation/git-verify-tag.txt         |  2 +-\n builtin/credential-cache--daemon.c       |  2 +-\n builtin/describe.c                       |  5 +++--\n builtin/diff-index.c                     |  2 +-\n builtin/help.c                           |  2 +-\n builtin/ls-remote.c                      |  2 +-\n builtin/pack-refs.c                      |  2 +-\n builtin/revert.c                         |  9 +++++----\n builtin/send-pack.c                      |  1 +\n builtin/sparse-checkout.c                |  2 +-\n builtin/symbolic-ref.c                   |  5 +++--\n builtin/tag.c                            | 10 ++++++----\n builtin/update-server-info.c             |  2 +-\n builtin/upload-pack.c                    |  3 ++-\n builtin/verify-pack.c                    |  2 +-\n help.c                                   |  2 +-\n 20 files changed, 41 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex be41f119740..047713e3a81 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n+'git send-pack' [--mirror] [--dry-run] [--force]\n+\t\t[--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n \t\t[--[no-]signed|--signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 872436d7426..68392d2a56e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout' <subcommand> [<options>]\n+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\nindex 969bb2e15f1..4e6bf44427f 100644\n--- a/Documentation/git-update-server-info.txt\n+++ b/Documentation/git-update-server-info.txt\n@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n SYNOPSIS\n --------\n [verse]\n-'git update-server-info'\n+'git update-server-info' [-f | --force]\n \n DESCRIPTION\n -----------\n@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n what references and packs the server has.  This command\n generates such auxiliary files.\n \n+OPTIONS\n+-------\n+-f::\n+--force::\n+\tAllow adding otherwise ignored files.\n+\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\nindex 92097f6673d..96d10cfdffe 100644\n--- a/Documentation/git-verify-commit.txt\n+++ b/Documentation/git-verify-commit.txt\n@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n SYNOPSIS\n --------\n [verse]\n-'git verify-commit' <commit>...\n+'git verify-commit' [-v | --verbose] <commit>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\nindex 0b8075dad96..a454df2711e 100644\n--- a/Documentation/git-verify-tag.txt\n+++ b/Documentation/git-verify-tag.txt\n@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n SYNOPSIS\n --------\n [verse]\n-'git verify-tag' [--format=<format>] <tag>...\n+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex ca672a6a619..d4eb0097d24 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n+\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex a76f1a1a7a7..98fb8afc3fa 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -23,8 +23,9 @@\n define_commit_slab(commit_names, struct commit_name *);\n \n static const char * const describe_usage[] = {\n-\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n-\tN_(\"git describe [<options>] --dirty\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n+\tN_(\"git describe <blob>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex e667cf52e7d..aea139b9d8f 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -9,7 +9,7 @@\n #include \"submodule.h\"\n \n static const char diff_cache_usage[] =\n-\"git diff-index [-m] [--cached] \"\n+\"git diff-index [-m] [--cached] [--merge-base] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n \"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 09ac4289f13..36e3f4116e9 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex df44e5cc0d1..5d5ac038716 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -7,7 +7,7 @@\n \n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n-\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n+\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n \t   \"              [--symref] [<repository> [<refs>...]]\"),\n \tNULL\n };\ndiff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\nindex cfbd5c36c76..27c2ca06acb 100644\n--- a/builtin/pack-refs.c\n+++ b/builtin/pack-refs.c\n@@ -5,7 +5,7 @@\n #include \"repository.h\"\n \n static char const * const pack_refs_usage[] = {\n-\tN_(\"git pack-refs [<options>]\"),\n+\tN_(\"git pack-refs [--all] [--no-prune]\"),\n \tNULL\n };\n \ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex ee2a0807f01..ee32c714a76 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -21,14 +21,15 @@\n  */\n \n static const char * const revert_usage[] = {\n-\tN_(\"git revert [<options>] <commit-ish>...\"),\n-\tN_(\"git revert <subcommand>\"),\n+\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n-\tN_(\"git cherry-pick <subcommand>\"),\n+\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n+\t   \"                [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \ndiff --git a/builtin/send-pack.c b/builtin/send-pack.c\nindex 64962be0168..dd9d2c4acc4 100644\n--- a/builtin/send-pack.c\n+++ b/builtin/send-pack.c\n@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n+\t   \"              [--[no-]signed|--signed=(true|false|if-asked)]\\n\"\n \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n \tNULL,\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex aac0f708e42..58a22503f04 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\nindex 1b0f10225f0..50b6df78df0 100644\n--- a/builtin/symbolic-ref.c\n+++ b/builtin/symbolic-ref.c\n@@ -5,8 +5,9 @@\n #include \"parse-options.h\"\n \n static const char * const git_symbolic_ref_usage[] = {\n-\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n-\tN_(\"git symbolic-ref -d [-q] <name>\"),\n+\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n+\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n+\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n \tNULL\n };\n \ndiff --git a/builtin/tag.c b/builtin/tag.c\nindex 75dece0e4f1..f665b90692a 100644\n--- a/builtin/tag.c\n+++ b/builtin/tag.c\n@@ -23,11 +23,13 @@\n #include \"date.h\"\n \n static const char * const git_tag_usage[] = {\n-\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n-\t   \"        <tagname> [<head>]\"),\n+\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n+\t   \"        <tagname> [<commit> | <object>]\"),\n \tN_(\"git tag -d <tagname>...\"),\n-\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n-\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n+\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n+\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n+\t   \"[--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n+\t   \"[--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n \tNULL\n };\ndiff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\nindex 880fffec587..d2239c9ef4d 100644\n--- a/builtin/update-server-info.c\n+++ b/builtin/update-server-info.c\n@@ -4,7 +4,7 @@\n #include \"parse-options.h\"\n \n static const char * const update_server_info_usage[] = {\n-\t\"git update-server-info [--force]\",\n+\t\"git update-server-info [-f | --force]\",\n \tNULL\n };\n \ndiff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\nindex 125af53885f..25b69da2bf2 100644\n--- a/builtin/upload-pack.c\n+++ b/builtin/upload-pack.c\n@@ -8,7 +8,8 @@\n #include \"serve.h\"\n \n static const char * const upload_pack_usage[] = {\n-\tN_(\"git upload-pack [<options>] <dir>\"),\n+\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n+\t   \"                [--advertise-refs] <directory>\"),\n \tNULL\n };\n \ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex 05c52135946..27d6f75fd8a 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n \tNULL\n };\n \ndiff --git a/help.c b/help.c\nindex 991e33f8a6e..0dd5b980220 100644\n--- a/help.c\n+++ b/help.c\n@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \tstruct strbuf buf = STRBUF_INIT;\n \tint build_options = 0;\n \tconst char * const usage[] = {\n-\t\tN_(\"git version [<options>]\"),\n+\t\tN_(\"git version [--build-options]\"),\n \t\tNULL\n \t};\n \tstruct option options[] = {\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462608","messageId":"patch-22.34-92c178d5303-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 22/34] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:33Z","receivedAt":"2022-09-05T08:28:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The C version was right to use \"()\" in place of \"[]\", let's update\nthe *.txt version accordingly, and furthermore list the *.c options in\nthe same order as the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-read-tree.txt | 2 +-\n builtin/read-tree.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex b9bfdc0a319..7567955bad8 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n SYNOPSIS\n --------\n [verse]\n-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex b3a389e1b1f..f4cbe460b97 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n \n static const char * const read_tree_usage[] = {\n \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n-\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462609","messageId":"patch-23.34-dee17f861b2-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 23/34] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:34Z","receivedAt":"2022-09-05T08:28:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend the -h output to match that of the *.txt output, the differences\nwere fairly small. In the case of \"[<options>]\" we only have a few of\nthem, so let's exhaustively list them as in the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 1b08700bf9e..544c78a5f3a 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,13 +12,14 @@\n  */\n \n #define BUILTIN_BUNDLE_CREATE_USAGE \\\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n+\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n-\tN_(\"git bundle verify [<options>] <file>\")\n+\tN_(\"git bundle verify [-q | --quiet] <file>\")\n #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n \tN_(\"git bundle list-heads <file> [<refname>...]\")\n #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n-\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n \n static char const * const builtin_bundle_usage[] = {\n \tBUILTIN_BUNDLE_CREATE_USAGE,\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462610","messageId":"patch-25.34-3b0295e3467-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 25/34] doc txt & -h consistency: add missing options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:36Z","receivedAt":"2022-09-05T08:28:51Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change those built-in commands that were attempting to exhaustively\nthe options in the \"-h\" output to actually do so, and always\nhave *.txt documentation know about the exhaustive list of options.\n\nLet's also fix the documentation and -h output for those built-in\ncommands where the *.txt and -h output was a mismatch of missing\noptions on both sides.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-commit-graph.txt       | 5 ++++-\n Documentation/git-interpret-trailers.txt | 5 +++--\n builtin/commit-tree.c                    | 1 +\n builtin/fsck.c                           | 5 ++++-\n builtin/hash-object.c                    | 5 +++--\n builtin/init-db.c                        | 2 ++\n builtin/interpret-trailers.c             | 2 +-\n builtin/rm.c                             | 4 +++-\n 8 files changed, 21 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 047decdb65b..f158ada90ea 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -10,7 +10,10 @@ SYNOPSIS\n --------\n [verse]\n 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n+'git commit-graph write' [--object-dir <dir>] [--append]\n+\t\t\t[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n+\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n+\t\t\t<split options>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 956a01d184f..057744e6d73 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [<options>] [--parse] [<file>...]\n+'git interpret-trailers' [--in-place] [--trim-empty]\n+\t\t\t[(--trailer <token>[(=|:)<value>])...]\n+\t\t\t[--parse] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex e4b85d29d56..cc8d584be2f 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,6 +15,7 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n+\tN_(\"git commit-tree <tree> [(-p <parent>)...]\"),\n \tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n \t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\ndiff --git a/builtin/fsck.c b/builtin/fsck.c\nindex 6c73092f10d..d9d163eabe4 100644\n--- a/builtin/fsck.c\n+++ b/builtin/fsck.c\n@@ -819,7 +819,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,\n }\n \n static char const * const fsck_usage[] = {\n-\tN_(\"git fsck [<options>] [<object>...]\"),\n+\tN_(\"git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\\n\"\n+\t   \"         [--[no-]full] [--strict] [--verbose] [--lost-found]\\n\"\n+\t   \"         [--[no-]dangling] [--[no-]progress] [--connectivity-only]\\n\"\n+\t   \"         [--[no-]name-objects] [<object>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex fbae878c2b9..11c3dfe0441 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -80,8 +80,9 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n-\t\t\"git hash-object  --stdin-paths\",\n+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\\n\"\n+\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n \t\tNULL\n \t};\n \tconst char *type = blob_type;\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 08ba006d55e..dcaaf102eaf 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n \n static const char *const init_db_usage[] = {\n \tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--separate-git-dir <git-dir>] [--object-format=<format>]\\n\"\n+\t   \"         [-b <branch-name> | --initial-branch=<branch-name>]\\n\"\n \t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 4cf0cf265dc..e58627c72a9 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -15,7 +15,7 @@\n static const char * const git_interpret_trailers_usage[] = {\n \tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n \t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n-\t   \"                       [<file>...]\"),\n+\t   \"                       [--parse] [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex b6ba859fe42..f0d025a4e23 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -17,7 +17,9 @@\n #include \"pathspec.h\"\n \n static const char * const builtin_rm_usage[] = {\n-\tN_(\"git rm [<options>] [--] <file>...\"),\n+\tN_(\"git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\\n\"\n+\t   \"       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"       [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462612","messageId":"patch-24.34-8cc52c68b67-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 24/34] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:35Z","receivedAt":"2022-09-05T08:28:52Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\nreceive-pack\" and \"git credential-cache--daemon\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-receive-pack.txt | 2 +-\n builtin/credential-cache--daemon.c | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex eec1268b10f..92452334ac4 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <git-dir>\n+'git receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex d4eb0097d24..f3c89831d4a 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\n@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n {\n \tconst char * const usage[] = {\n-\t\t\"git credential-cache--daemon [options] <action>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\t\"\",\n \t\t\"credential-cache--daemon is disabled in this build of Git\",\n \t\tNULL\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462611","messageId":"patch-26.34-3907f349948-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 26/34] doc txt & -h consistency: make \"stash\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:37Z","receivedAt":"2022-09-05T08:28:54Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend both the the -h output and *.txt to match one another. In this\ncase the *.txt didn't list the \"save\" subcommand, and the \"-h\" was\nsimilarly missing some commands.\n\nLet's also convert the *.c code to use a macro definition, similar to\nthat used in preceding commits. This avoids duplication.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt |  5 ++-\n builtin/stash.c             | 73 ++++++++++++++++++++++++-------------\n 2 files changed, 52 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 379bea645db..c350a3b8dac 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,12 +11,15 @@ SYNOPSIS\n 'git stash' list [<log-options>]\n 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n 'git stash' drop [-q | --quiet] [<stash>]\n-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n+'git stash' pop [--index] [-q | --quiet] [<stash>]\n+'git stash' apply [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [<message>]\n 'git stash' clear\n 'git stash' create [<message>]\n 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 614bb0dd4a2..5408832efb4 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -21,72 +21,95 @@\n \n #define INCLUDE_ALL_FILES 2\n \n+#define BUILTIN_STASH_LIST_USAGE \\\n+\tN_(\"git stash list [<log-options>]\")\n+#define BUILTIN_STASH_SHOW_USAGE \\\n+\tN_(\"git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\")\n+#define BUILTIN_STASH_DROP_USAGE \\\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_POP_USAGE \\\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_APPLY_USAGE \\\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_BRANCH_USAGE \\\n+\tN_(\"git stash branch <branchname> [<stash>]\")\n+#define BUILTIN_STASH_STORE_USAGE \\\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\")\n+#define BUILTIN_STASH_PUSH_USAGE \\\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\" \\\n+\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\" \\\n+\t   \"          [--] [<pathspec>...]]\")\n+#define BUILTIN_STASH_SAVE_USAGE \\\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\")\n+#define BUILTIN_STASH_CREATE_USAGE \\\n+\tN_(\"git stash create [<message>]\")\n+#define BUILTIN_STASH_CLEAR_USAGE \\\n+\t\"git stash clear\"\n+\n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<log-options>]\"),\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n-\t\"git stash clear\",\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n+\tBUILTIN_STASH_SHOW_USAGE,\n+\tBUILTIN_STASH_DROP_USAGE,\n+\tBUILTIN_STASH_POP_USAGE,\n+\tBUILTIN_STASH_APPLY_USAGE,\n+\tBUILTIN_STASH_BRANCH_USAGE,\n+\tBUILTIN_STASH_PUSH_USAGE,\n+\tBUILTIN_STASH_SAVE_USAGE,\n+\tBUILTIN_STASH_CLEAR_USAGE,\n+\tBUILTIN_STASH_CREATE_USAGE,\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_list_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_show_usage[] = {\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n+\tBUILTIN_STASH_SHOW_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_DROP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_POP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_APPLY_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_branch_usage[] = {\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_clear_usage[] = {\n-\t\"git stash clear\",\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n+\tBUILTIN_STASH_PUSH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_SAVE_USAGE,\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462613","messageId":"patch-28.34-6607ed3e343-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 28/34] doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:39Z","receivedAt":"2022-09-05T08:28:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Correct uses of \"<label>...\" where we really meant to say\n\"[<label>...]\", i.e. the command in question taken an optional set of\n\"<label>\". As the CodingGuidelines notes \"[o]ptional parts [should be]\nenclosed in square brackets\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt | 2 +-\n builtin/clean.c             | 2 +-\n builtin/commit.c            | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 13e3a0844f8..6d55cd1f5e8 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\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>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 6f039f555b2..40ff2c578de 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex fcf9c85947e..21ad4ccbf87 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {\n };\n \n static const char * const builtin_status_usage[] = {\n-\tN_(\"git status [<options>] [--] <pathspec>...\"),\n+\tN_(\"git status [<options>] [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462614","messageId":"patch-27.34-f6c9fb63a08-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 27/34] doc txt & -h consistency: make \"annotate\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:38Z","receivedAt":"2022-09-05T08:29:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cmd_blame() already detected whether it was processing \"blame\" or\n\"annotate\", but it didn't adjust its usage output accordingly. Let's\ndo that.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-annotate.txt |  2 +-\n builtin/blame.c                | 21 +++++++++++++++------\n 2 files changed, 16 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex e44a831339d..5ae8aabe0f8 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [<options>] <file> [<revision>]\n+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex 8ec59fa2096..be9e091a86b 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -30,6 +30,7 @@\n #include \"tag.h\"\n \n static char blame_usage[] = N_(\"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n+static char annotate_usage[] = N_(\"git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n \n static const char *blame_opt_usage[] = {\n \tblame_usage,\n@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {\n \tNULL\n };\n \n+static const char *annotate_opt_usage[] = {\n+\tannotate_usage,\n+\t\"\",\n+\tN_(\"<rev-opts> are documented in git-rev-list(1)\"),\n+\tNULL\n+};\n+\n static int longest_file;\n static int longest_author;\n static int max_orig_digits;\n@@ -899,6 +907,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tlong anchor;\n \tconst int hexsz = the_hash_algo->hexsz;\n \tlong num_lines = 0;\n+\tconst char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n \n \tsetup_default_color_by_age();\n \tgit_config(git_blame_config, &output_option);\n@@ -914,7 +923,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tparse_options_start(&ctx, argc, argv, prefix, options,\n \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n \tfor (;;) {\n-\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n+\t\tswitch (parse_options_step(&ctx, options, usage)) {\n \t\tcase PARSE_OPT_NON_OPTION:\n \t\tcase PARSE_OPT_UNKNOWN:\n \t\t\tbreak;\n@@ -934,7 +943,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\tctx.argv[0] = \"--children\";\n \t\t\treverse = 1;\n \t\t}\n-\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n+\t\tparse_revision_opt(&revs, &ctx, options, usage);\n \t}\n parse_done:\n \trevision_opts_finish(&revs);\n@@ -1040,7 +1049,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\tswitch (argc - dashdash_pos - 1) {\n \t\tcase 2: /* (1b) */\n \t\t\tif (argc != 4)\n-\t\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\t\tusage_with_options(usage, options);\n \t\t\t/* reorder for the new way: <rev> -- <path> */\n \t\t\targv[1] = argv[3];\n \t\t\targv[3] = argv[2];\n@@ -1051,11 +1060,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\targv[argc] = NULL;\n \t\t\tbreak;\n \t\tdefault:\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\t}\n \t} else {\n \t\tif (argc < 2)\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n \t\t\tpath = add_prefix(prefix, argv[1]);\n \t\t\targv[1] = argv[2];\n@@ -1114,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n \t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n-\t\t\t\t       blame_opt_usage, options, arg);\n+\t\t\t\t       usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462615","messageId":"patch-32.34-5fa403db45a-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 32/34] worktree: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:43Z","receivedAt":"2022-09-05T08:29:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git worktree\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------\n 1 file changed, 84 insertions(+), 25 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 5bfc18e5a24..ba6846c3788 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -15,15 +15,72 @@\n #include \"worktree.h\"\n #include \"quote.h\"\n \n-static const char * const worktree_usage[] = {\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\"),\n-\tN_(\"git worktree list [<options>]\"),\n-\tN_(\"git worktree lock [<options>] <path>\"),\n-\tN_(\"git worktree move <worktree> <new-path>\"),\n-\tN_(\"git worktree prune [<options>]\"),\n-\tN_(\"git worktree remove [<options>] <worktree>\"),\n-\tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <worktree>\"),\n+#define BUILTIN_WORKTREE_ADD_USAGE \\\n+\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+#define BUILTIN_WORKTREE_LIST_USAGE \\\n+\tN_(\"git worktree list [<options>]\")\n+#define BUILTIN_WORKTREE_LOCK_USAGE \\\n+\tN_(\"git worktree lock [<options>] <path>\")\n+#define BUILTIN_WORKTREE_MOVE_USAGE \\\n+\tN_(\"git worktree move <worktree> <new-path>\")\n+#define BUILTIN_WORKTREE_PRUNE_USAGE \\\n+\tN_(\"git worktree prune [<options>]\")\n+#define BUILTIN_WORKTREE_REMOVE_USAGE \\\n+\tN_(\"git worktree remove [<options>] <worktree>\")\n+#define BUILTIN_WORKTREE_REPAIR_USAGE \\\n+\tN_(\"git worktree repair [<path>...]\")\n+#define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n+\tN_(\"git worktree unlock <worktree>\")\n+\n+static const char * const git_worktree_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_add_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tNULL,\n+};\n+\n+static const char * const git_worktree_list_usage[] = {\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_lock_usage[] = {\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_move_usage[] = {\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_prune_usage[] = {\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_remove_usage[] = {\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_repair_usage[] = {\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_unlock_usage[] = {\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n \tNULL\n };\n \n@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,\n+\t\t\t   0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_prune_usage, options);\n \tprune_worktrees();\n \treturn 0;\n }\n@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)\n \n \tmemset(&opts, 0, sizeof(opts));\n \topts.checkout = 1;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);\n \tif (!!opts.detach + !!new_branch + !!new_branch_force > 1)\n \t\tdie(_(\"options '%s', '%s', and '%s' cannot be used together\"), \"-b\", \"-B\", \"--detach\");\n \tif (lock_reason && !keep_locked)\n@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\topts.keep_locked = _(\"added with --lock\");\n \n \tif (ac < 1 || ac > 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_add_usage, options);\n \n \tpath = prefix_filename(prefix, av[0]);\n \tbranch = ac < 2 ? \"HEAD\" : av[1];\n@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_list_usage, options);\n \telse if (verbose && porcelain)\n \t\tdie(_(\"options '%s' and '%s' cannot be used together\"), \"--verbose\", \"--porcelain\");\n \telse if (!line_terminator && !porcelain)\n@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)\n \t};\n \tstruct worktree **worktrees, *wt;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_lock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)\n \tstruct worktree **worktrees, *wt;\n \tint ret;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_unlock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tchar *path;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_move_usage,\n+\t\t\t   0);\n \tif (ac != 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_move_usage, options);\n \n \tpath = prefix_filename(prefix, av[1]);\n \tstrbuf_addstr(&dst, path);\n@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tint ret = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_remove_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)\n \t};\n \tint rc = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);\n \tp = ac > 0 ? av : self;\n \tfor (; *p; p++)\n \t\trepair_worktree_at_path(*p, report_repair, &rc);\n@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)\n \tif (!prefix)\n \t\tprefix = \"\";\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);\n \treturn fn(ac, av, prefix);\n }\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462616","messageId":"patch-29.34-dc32043b203-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 29/34] doc txt & -h consistency: make \"diff-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:40Z","receivedAt":"2022-09-05T08:29:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"diff-tree -h\" output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-tree.c | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 23f58702fa0..85e8c81e594 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)\n }\n \n static const char diff_tree_usage[] =\n-\"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\\n\"\n+\"              [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\\n\"\n+\"              [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n \"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462617","messageId":"patch-34.34-c15c1422055-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 34/34] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:45Z","receivedAt":"2022-09-05T08:29:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's been a lot of incremental effort to make the SYNOPSIS output\nin our documentation consistent with the -h output,\ne.g. cbe485298bf (git reflog [expire|delete]: make -h output\nconsistent with SYNOPSIS, 2022-03-17) is one recent example, but that\neffort has been an uphill battle due to the lack of regression\ntesting.\n\nThis adds such regression testing, we can parse out the SYNOPSIS\noutput with \"sed\", and is turns out it's relatively easy to normalize\nit and the \"-h\" output to match on another.\n\nWe now ensure that we won't have regressions when it comes to the list\nof commands in \"expect_help_to_match_txt\" below, and in subsequent\ncommits we'll make more of them consistent.\n\nThe naïve parser here gets quite a few things wrong, but it doesn't\nneed to be perfect, just good enough that we can compare /some/ of\nthis help output. There's no cases where the output would match except\nfor the parser's stupidity, it's all cases of e.g. comparing the *.txt\nto non-parse_options() output.\n\nSince that output is wildly different than the *.txt anyway let's\nleave this for now, we can fix the parser some other time, or it won't\nbecome necessary as we'll e.g. convert more things to using\nparse_options().\n\nHaving a special-case for \"merge-tree\"'s 1f0c3a29da3 (merge-tree:\nimplement real merges, 2022-06-18) is a bit ugly, but preferred to\nblessing that \" (deprecated)\" pattern for other commands. We'd\nprobably want to add some other way of marking deprecated commands in\nthe SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is\nindistinguishable from the command taking an optional literal\n\"deprecated\" string as an argument.\n\nSome of the issues that are left:\n\n * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n   all showing \"git log\" and \"git show\" usage output. I.e. the\n   \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n   command we're running.\n\n * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n   of what command it's running. The same for \"annotate\" and \"blame\".\n\n * Commands which implement subcommands such as like\n   \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n   in a very different order in the *.txt and *.c. Fixing it would\n   require some verbose diffs, so it's been left alone for onw.\n\n * Commands such as \"format-patch\" have a very long argument list in\n   the *.txt, but just \"[<options>]\" in the *.c.\n\n   What to do about these has been left out of this series, except to\n   the extent that preceding commits changed \"[<options>]\" (or\n   equivalent) to the list of options in cases where that list of\n   options was tiny, or we clearly meant to exhaustively list the\n   options in both *.txt and *.c.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines |   3 +-\n t/t0450-txt-doc-vs-help.sh     | 179 +++++++++++++++++++++++++++++++++\n 2 files changed, 181 insertions(+), 1 deletion(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 0d959f8c96b..a60393df04a 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -634,7 +634,8 @@ Writing Documentation:\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n- pages:\n+ pages. The two should match, see t/t0450-txt-doc-vs-help.sh for\n+ (partial) regression testing.\n \n  Placeholders are spelled in lowercase and enclosed in angle brackets:\n    <file>\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..8af845bcd46\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,179 @@\n+#!/bin/sh\n+\n+test_description='compare (unbuilt) Documentation/*.txt to -h output\n+\n+Run this with --debug to see a summary of where we still fail to make\n+the two versions consistent with one another.'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+test_expect_success 'setup: list of txt v.s. help' '\n+\tcat >list <<-\\EOF\n+\tadd\n+\tam\n+\tapply\n+\tarchive\n+\tbisect\n+\tblame\n+\tbranch\n+\tcheck-ref-format\n+\tcheckout\n+\tcheckout-index\n+\tclone\n+\tcolumn\n+\tconfig\n+\tcredential\n+\tcredential-cache\n+\tcredential-store\n+\tfast-export\n+\tfast-import\n+\tfetch-pack\n+\tfmt-merge-msg\n+\tfor-each-ref\n+\tformat-patch\n+\tfsck-objects\n+\tfsmonitor--daemon\n+\tgc\n+\tgrep\n+\tindex-pack\n+\tinit-db\n+\tlog\n+\tls-files\n+\tls-tree\n+\tmailinfo\n+\tmailsplit\n+\tmaintenance\n+\tmerge\n+\tmerge-file\n+\tmerge-index\n+\tmerge-one-file\n+\tmulti-pack-index\n+\tname-rev\n+\tnotes\n+\tpack-objects\n+\tpush\n+\trange-diff\n+\trebase\n+\tremote\n+\tremote-ext\n+\tremote-fd\n+\trepack\n+\treset\n+\trestore\n+\trev-parse\n+\tshow\n+\tstage\n+\tswitch\n+\tupdate-index\n+\tupdate-ref\n+\twhatchanged\n+\tEOF\n+'\n+\n+test_expect_success 'setup: list of txt v.s. help is sorted' '\n+\tsort -u list >list.sorted &&\n+\tif ! test_cmp list list.sorted\n+\tthen\n+\t\tBUG \"please keep the command list sorted\"\n+\tfi\n+'\n+\n+builtin_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\ttest_when_finished \"rm -f out\" &&\n+\ttest_expect_code 129 git $builtin -h >out 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp\n+\t\t}' <out\n+}\n+\n+builtin_to_txt () {\n+\techo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n+}\n+\n+txt_synopsis () {\n+\tsed -n \\\n+\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\t/^\\[verse\\]$/d;\n+\t\t\ts/{litdd}/--/g;\n+\n+\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\tp;\n+\t\t}' \\\n+\t\t<\"$1\"\n+}\n+\n+HT=\"\t\"\n+align_after_nl () {\n+\tbuiltin=\"$1\" &&\n+\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n+\tpad=$(printf \"%${len}s\" \"\") &&\n+\n+\tsed \"s/^[ $HT][ $HT]*/$pad/\"\n+}\n+\n+test_debug '>failing'\n+while read builtin\n+do\n+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n+\n+\tif test -f \"$txt\"\n+\tthen\n+\t\ttest_set_prereq \"$preq\"\n+\tfi &&\n+\n+\tresult=\n+\tif grep -q \"^$builtin$\" list\n+\tthen\n+\t\tresult=failure\n+\telse\n+\t\tresult=success\n+\tfi &&\n+\n+\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n+\t\ttxt_synopsis \"$txt\" >txt.raw &&\n+\t\tif test \"$builtin\" = \"merge-tree\"\n+\t\tthen\n+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <txt.raw >txt.raw.new &&\n+\t\t\tmv txt.raw.new txt.raw\n+\t\tfi &&\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\n+\t\t# The *.txt and -h use different spacing for the\n+\t\t# alignment of continued usage output, normalize it.\n+\t\talign_after_nl \"$builtin\" <txt.raw >txt &&\n+\t\talign_after_nl \"$builtin\" <help.raw >help &&\n+\t\ttest_cmp txt help\n+\t'\n+\n+\tif test_have_prereq \"$preq\" && test -e txt && test -e help\n+\tthen\n+\t\ttest_debug '\n+\t\t\tif test_cmp txt help >cmp 2>/dev/null\n+\t\t\tthen\n+\t\t\t\techo \"=== DONE: $builtin ===\"\n+\t\t\telse\n+\t\t\t\techo \"=== TODO: $builtin ===\" &&\n+\t\t\t\tcat cmp\n+\t\t\tfi >>failing\n+\t\t'\n+\n+\t\t# Not in test_expect_success in case --run is being\n+\t\t# used with --debug\n+\t\trm -f txt help tmp 2>/dev/null\n+\tfi\n+done <builtins\n+\n+test_debug 'say \"$(cat failing)\"'\n+\n+test_done\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462618","messageId":"patch-30.34-0aea4ee2e03-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 30/34] doc txt & -h consistency: make \"commit\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:41Z","receivedAt":"2022-09-05T08:29:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"-h\" output of \"git commit\" consistent with the *.txt version\nby exhaustively listing the options that it takes.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/commit.c | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex 21ad4ccbf87..64f420bcbf6 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -40,7 +40,14 @@\n #include \"pretty.h\"\n \n static const char * const builtin_commit_usage[] = {\n-\tN_(\"git commit [<options>] [--] <pathspec>...\"),\n+\tN_(\"git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\\n\"\n+\t   \"           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\\n\"\n+\t   \"           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\\n\"\n+\t   \"           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\\n\"\n+\t   \"           [--date=<date>] [--cleanup=<mode>] [--[no-]status]\\n\"\n+\t   \"           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\\n\"\n+\t   \"           [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462619","messageId":"patch-33.34-280c3b56d97-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 33/34] doc txt & -h consistency: make \"worktree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:44Z","receivedAt":"2022-09-05T08:29:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"worktree\" -h output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex ba6846c3788..4a24d53be15 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -16,17 +16,18 @@\n #include \"quote.h\"\n \n #define BUILTIN_WORKTREE_ADD_USAGE \\\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+\tN_(\"git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\\n\" \\\n+\t   \"                 [-b <new-branch>] <path> [<commit-ish>]\")\n #define BUILTIN_WORKTREE_LIST_USAGE \\\n-\tN_(\"git worktree list [<options>]\")\n+\tN_(\"git worktree list [-v | --porcelain [-z]]\")\n #define BUILTIN_WORKTREE_LOCK_USAGE \\\n-\tN_(\"git worktree lock [<options>] <path>\")\n+\tN_(\"git worktree lock [--reason <string>] <worktree>\")\n #define BUILTIN_WORKTREE_MOVE_USAGE \\\n \tN_(\"git worktree move <worktree> <new-path>\")\n #define BUILTIN_WORKTREE_PRUNE_USAGE \\\n-\tN_(\"git worktree prune [<options>]\")\n+\tN_(\"git worktree prune [-n] [-v] [--expire <expire>]\")\n #define BUILTIN_WORKTREE_REMOVE_USAGE \\\n-\tN_(\"git worktree remove [<options>] <worktree>\")\n+\tN_(\"git worktree remove [-f] <worktree>\")\n #define BUILTIN_WORKTREE_REPAIR_USAGE \\\n \tN_(\"git worktree repair [<path>...]\")\n #define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462620","messageId":"patch-31.34-5da768a04bc-20220902T092734Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH 31/34] reflog doc: list real subcommands up-front","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-05T08:26:42Z","receivedAt":"2022-09-05T08:29:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"git reflog\" documentation to exhaustively list the\nsubcommands it accepts in the SYNOPSIS, as opposed to leaving that for\na \"[verse]\" in the DESCRIPTION section. This documentation style was\nadded in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how\nother commands which take subcommands are documented.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 15 ++++++---------\n 1 file changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 0537d4645be..ec64cbff4c6 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -8,14 +8,6 @@ git-reflog - Manage reflog information\n \n SYNOPSIS\n --------\n-[verse]\n-'git reflog' <subcommand> <options>\n-\n-DESCRIPTION\n------------\n-The command takes various subcommands, and different options\n-depending on the subcommand:\n-\n [verse]\n 'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n@@ -25,6 +17,10 @@ depending on the subcommand:\n \t[--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n 'git reflog exists' <ref>\n \n+DESCRIPTION\n+-----------\n+This command manages the information recorded in the reflogs.\n+\n Reference logs, or \"reflogs\", record when the tips of branches and\n other references were updated in the local repository. Reflogs are\n useful in various Git commands, to specify the old value of a\n@@ -33,7 +29,8 @@ moves ago\", `master@{one.week.ago}` means \"where master used to point\n to one week ago in this local repository\", and so on. See\n linkgit:gitrevisions[7] for more details.\n \n-This command manages the information recorded in the reflogs.\n+The command takes various subcommands, and different options\n+depending on the subcommand:\n \n The \"show\" subcommand (which is also the default, in the absence of\n any subcommands) shows the log of the reference provided in the\n-- \n2.37.3.1425.g73df845bcb2\n\n"},{"id":"462754","messageId":"xmqqedwnszsz.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-01.34-b8cbd443987-20220902T092734Z-avarab@gmail.com","subject":"Re: [PATCH 01/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-07T20:19:08Z","receivedAt":"2022-09-07T20:19:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> + Use spacing around \"|\" token(s), but not on the inside of \"[]()\"\n> + tokens:\n> +   Do: [-q | --quiet]\n> +   Don't: [-q|--quiet]\n\nIt is unclear what \"but not on ...\" in the description and it is\nstill unclear with the examples.  Does this mean\n\n\tDon't: ( -q | --quiet )\n\nIn other words, \"on the inside of\" above is meant to forbid spaces\nimmediately after opening or before closing a [] or () pair?\n\nOther than that, I think these are good guidelines to have.\n\nThanks.\n\n"},{"id":"462802","messageId":"220908.865yhyl31c.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqedwnszsz.fsf@gitster.g","subject":"Re: [PATCH 01/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-08T07:46:55Z","receivedAt":"2022-09-08T07:48:57Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Sep 07 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>> + Use spacing around \"|\" token(s), but not on the inside of \"[]()\"\n>> + tokens:\n>> +   Do: [-q | --quiet]\n>> +   Don't: [-q|--quiet]\n>\n> It is unclear what \"but not on ...\" in the description and it is\n> still unclear with the examples.  Does this mean\n>\n> \tDon't: ( -q | --quiet )\n>\n> In other words, \"on the inside of\" above is meant to forbid spaces\n> immediately after opening or before closing a [] or () pair?\n\nYes, that's what I was aiming for, and will obviously need to\nrephrase. I.e.:\n\n Don't: ( -q | --quiet)\n Do: (-q | --quiet)\n\n> Other than that, I think these are good guidelines to have.\n\n\"Other than that\" as in \"let's fix that phrasing\" or \"let's not have\nthat concept as part of these guidelines\".\n\nI think the phrasing obviously needs to be fixed, here I was just\nattempting to cover a blind spot where the guidelines said nothing, and\nI picked whatever was the most common convention (as the rest of the\nseries shows).\n"},{"id":"462810","messageId":"xmqqzgf9rf81.fsf@gitster.g","threadId":"58397","inReplyTo":"220908.865yhyl31c.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH 01/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-08T16:41:18Z","receivedAt":"2022-09-08T16:41:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> \"Other than that\" as in \"let's fix that phrasing\" or \"let's not have\n> that concept as part of these guidelines\".\n\n\"Other than that\" meaning \"I do not know what exactly you meant\nabout the 'inside of', so I do not think I can tell you to get rid\nof it altogether or fix it in some way, but other things looked OK\".\n\nI think \"( -q | --quiet )\" -> \"(-q | --quiet)\" is a good idea.\n\n> I think the phrasing obviously needs to be fixed, here I was just\n> attempting to cover a blind spot where the guidelines said nothing, and\n> I picked whatever was the most common convention (as the rest of the\n> series shows).\n"},{"id":"463238","messageId":"b1c44436-92d1-067c-fb0a-be4049f3031b@github.com","threadId":"58397","inReplyTo":"patch-07.34-a070c97f29b-20220902T092734Z-avarab@gmail.com","subject":"Re: [PATCH 07/34] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-09-19T22:09:56Z","receivedAt":"2022-09-19T22:10:04Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n> \"[(-o | --option) <argument>]\", we were previously claiming that only\n> the long option accepted the \"<argument>\", which isn't what we meant.\n> \n> Unlike a preceding commit where this was fixed for commands which had\n\nnit: if you're referring to patch 10 [1], it wouldn't be a \"preceding\"\ncommit. Otherwise, I'm not sure which commit you're referring to?\n\nIn any case, I'd personally prefer that this patch is combined with patch 10\nanyway, since both fix the same underlying issue (just in different places).\nNeither patch is particularly large, and it would be nice to make (and\nreview!) all of the \"fix alternates syntax\" changes at once.\n\n[1] https://lore.kernel.org/git/patch-10.34-965f6b3b3cb-20220902T092734Z-avarab@gmail.com/\n\n> inconsistent \"-h\" and *.txt, for \"stash\" it's been with us in both the\n> \"-h\" and *.txt since bd514cada4b (stash: introduce 'git stash store',\n> 2013-06-15).\n> \n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n"},{"id":"463239","messageId":"af319ab4-2351-2d74-e0c7-6153f229d88c@github.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"Re: [PATCH 00/34] doc/UX: make txt & -h output more consistent","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-09-19T22:15:33Z","receivedAt":"2022-09-19T22:15:51Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> We are currently wildly inconsistent in whether the SYNOPSIS in the\n> manual page matches the first line of the -h output, and as we add new\n> options we routinely forget to add them to one or the other (or both).\n> \n> Without a more complex approach it's hard to do something about the\n> \"or both\" case. But we can rather easily test whether the -h output\n> matches the *.txt version, and report differences.\n> \n> As this series shows that allows us to fix a lot of issues we've\n> effectively already \"fixed\", we just fixed them in one version, but\n> not the other.\n> \n> We now have a test that checks that these are the same for all\n> built-ins. Out of 141 built-in commands we still have 58 cases that\n> differ at the end of this series, but that's a lot better than before.\n\nThanks! Codifying these expectations into an automated check will be\nextremely helpful for avoiding easy-to-miss mistakes that could potentially\nconfuse end users.\n\n> \n> This series is 34 patches, but it's been structured in a way that\n> reviewers should be able to mostly trust the \"doc txt & -h\n> consistency\" commits already. In all of those cases we already have\n> the post-image in-tree, it's just in either the *.txt or -h version,\n> not both. All of the \"doc txt & -h consistency\" commits merely make\n> those consistent together.\n\nIn general, I don't think it's wise to implicitly trust *any* patches, no\nmatter how simple they appear. I know there are benefits to doing everything\nat once, but the volume and variety of these changes makes it difficult to\nreview the series and *confidently* say we haven't introduced any\nregressions, missed any cases, or made the \"wrong\" decisions w.r.t changing\neither the .txt or -h documentation to make them consistent.\n\nAfter reading through this series a few times, it looks like it contains a\nmix of:\n\n* updated syntax guidance in CodingGuidelines\n* clear syntax or naming fixes (e.g., adding a missing \"]\" to a '-h' output,\n  \"keyid\" -> \"key-id\" for translation purposes)\n* internal refactoring\n* changing an error message's content\n* changing the listed options and/or usage in '-h' and/or the .txt SYNOPSIS\n* adding an option description in a .txt doc\n* adding the new test\n\nIf I could offer a suggestion, my preference would be that you split the\nseries into three parts: one with the straightforward, easier-to-review\nchanges, another with the more substantial updates to user-facing\ndocs/information (which might warrant more discussion, i.e. which options we\nshould be showing for a command in the SYNOPSIS/-h), and the last catching\nany new inconsistencies & adding the test. That way, more involved\ndiscussion on some patches doesn't prevent *all* of them from being merged.\n\nI think the following patches would fit a \"straightforward,\neasier-to-review\" series:\n\n* Patch 1 (CodingGuidelines: update and clarify command-line conventions)\n* Patch 2 (builtin/bundle.c: use \\t, not fix indentation 2-SP indentation)\n* Patch 3 (bundle: define subcommand -h in terms of command -h)\n* Patch 5 (doc SYNOPSIS: don't use ' for subcommands)\n* Patch 6 (doc SYNOPSIS: consistently use ' for commands)\n* Patch 7 (doc SYNOPSIS & -h: fix incorrect alternates syntax)\n* Patch 8 (built-ins: consistently add \"\\n\" between \"usage\" and options)\n* Patch 9 (doc txt & -h consistency: word-wrap)\n* Patch 10 (doc txt & -h consistency: fix incorrect alternates syntax)\n* Patch 12 (doc txt & -h consistency: add missing \"]\" to bugreport \"-h\")\n* Patch 13 (doc txt & -h consistency: correct padding around \"[]()\")\n* Patch 14 (stash doc SYNOPSIS & -h: correct padding around \"[]()\")\n* Patch 15 (doc txt & -h consistency: use \"<options>\", not \"<options>...\")\n* Patch 16 (t/helper/test-proc-receive.c: use \"<options>\", not\n  \"<options>...\")\n* Patch 17 (doc txt & -h consistency: fix mismatching labels)\n* Patch 18 (doc txt & -h consistency: add or fix optional \"--\" syntax)\n\n(basically, 1-18, skipping patch 4 because it changes the content of an\nerror message & patch 11 because it adds an option to the -h of 'cat-file')\n\nIn terms of review, my only comment on those patches is that 7 & 10 could\nprobably benefit from being squashed together [1]. Otherwise, with the\nchanges you mentioned in response to Junio's feedback [2], I think that\nsubset of the series would be ready to merge.\n\nI hope that helps!\n-Victoria\n\n[1] https://lore.kernel.org/git/b1c44436-92d1-067c-fb0a-be4049f3031b@github.com/\n[2] https://lore.kernel.org/git/220908.865yhyl31c.gmgdl@evledraar.gmail.com/\n\n> \n> Ævar Arnfjörð Bjarmason (34):\n>   CodingGuidelines: update and clarify command-line conventions\n>   builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n>   bundle: define subcommand -h in terms of command -h\n>   blame: use a more detailed usage_msg_optf() error on bad -L\n>   doc SYNOPSIS: don't use ' for subcommands\n>   doc SYNOPSIS: consistently use ' for commands\n>   doc SYNOPSIS & -h: fix incorrect alternates syntax\n>   built-ins: consistently add \"\\n\" between \"usage\" and options\n>   doc txt & -h consistency: word-wrap\n>   doc txt & -h consistency: fix incorrect alternates syntax\n>   doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n>   doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n>   doc txt & -h consistency: correct padding around \"[]()\"\n>   stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n>   doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n>   t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n>   doc txt & -h consistency: fix mismatching labels\n>   doc txt & -h consistency: add or fix optional \"--\" syntax\n>   doc txt & -h consistency: make output order consistent\n>   doc txt & -h consistency: add missing options and labels\n>   doc txt & -h consistency: make \"rerere\" consistent\n>   doc txt & -h consistency: make \"read-tree\" consistent\n>   doc txt & -h consistency: make \"bundle\" consistent\n>   doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n>   doc txt & -h consistency: add missing options\n>   doc txt & -h consistency: make \"stash\" consistent\n>   doc txt & -h consistency: make \"annotate\" consistent\n>   doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n>   doc txt & -h consistency: make \"diff-tree\" consistent\n>   doc txt & -h consistency: make \"commit\" consistent\n>   reflog doc: list real subcommands up-front\n>   worktree: define subcommand -h in terms of command -h\n>   doc txt & -h consistency: make \"worktree\" consistent\n>   tests: start asserting that *.txt SYNOPSIS matches -h output\n> \n"},{"id":"463250","messageId":"07b35632-8e3c-fea1-0996-fb2e88ea6ba8@github.com","threadId":"58397","inReplyTo":"af319ab4-2351-2d74-e0c7-6153f229d88c@github.com","subject":"Re: [PATCH 00/34] doc/UX: make txt & -h output more consistent","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-09-20T00:57:18Z","receivedAt":"2022-09-20T00:57:25Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Victoria Dye wrote:\n> If I could offer a suggestion, my preference would be that you split the\n> series into three parts: one with the straightforward, easier-to-review\n> changes, another with the more substantial updates to user-facing\n> docs/information (which might warrant more discussion, i.e. which options we\n> should be showing for a command in the SYNOPSIS/-h), and the last catching\n> any new inconsistencies & adding the test. That way, more involved\n> discussion on some patches doesn't prevent *all* of them from being merged.\n> \n> I think the following patches would fit a \"straightforward,\n> easier-to-review\" series:\n> \n> * Patch 1 (CodingGuidelines: update and clarify command-line conventions)\n> * Patch 2 (builtin/bundle.c: use \\t, not fix indentation 2-SP indentation)\n> * Patch 3 (bundle: define subcommand -h in terms of command -h)\n> * Patch 5 (doc SYNOPSIS: don't use ' for subcommands)\n> * Patch 6 (doc SYNOPSIS: consistently use ' for commands)\n> * Patch 7 (doc SYNOPSIS & -h: fix incorrect alternates syntax)\n> * Patch 8 (built-ins: consistently add \"\\n\" between \"usage\" and options)\n> * Patch 9 (doc txt & -h consistency: word-wrap)\n> * Patch 10 (doc txt & -h consistency: fix incorrect alternates syntax)\n> * Patch 12 (doc txt & -h consistency: add missing \"]\" to bugreport \"-h\")\n> * Patch 13 (doc txt & -h consistency: correct padding around \"[]()\")\n> * Patch 14 (stash doc SYNOPSIS & -h: correct padding around \"[]()\")\n> * Patch 15 (doc txt & -h consistency: use \"<options>\", not \"<options>...\")\n> * Patch 16 (t/helper/test-proc-receive.c: use \"<options>\", not\n>   \"<options>...\")\n> * Patch 17 (doc txt & -h consistency: fix mismatching labels)\n> * Patch 18 (doc txt & -h consistency: add or fix optional \"--\" syntax)\n> \n> (basically, 1-18, skipping patch 4 because it changes the content of an\n> error message & patch 11 because it adds an option to the -h of 'cat-file')\n> \n> In terms of review, my only comment on those patches is that 7 & 10 could\n> probably benefit from being squashed together [1]. Otherwise, with the\n> changes you mentioned in response to Junio's feedback [2], I think that\n> subset of the series would be ready to merge.\n> \n\nI forgot to mention this in the previous message, but it's probably worth\nnoting - regardless of whether or not you split the series, I am still\nplanning to review the remaining patches you've submitted here (that is,\neverything *other than* what's in the list above, which I've already looked\nover/commented on). I likely won't get the chance until later this week at\nthe earliest, though.\n\nThanks!\n-Victoria\n"},{"id":"463620","messageId":"220926.86pmfi1id2.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"b1c44436-92d1-067c-fb0a-be4049f3031b@github.com","subject":"Re: [PATCH 07/34] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-26T11:28:49Z","receivedAt":"2022-09-26T13:00:54Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Sep 19 2022, Victoria Dye wrote:\n\n> Ævar Arnfjörð Bjarmason wrote:\n>> Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n>> \"[(-o | --option) <argument>]\", we were previously claiming that only\n>> the long option accepted the \"<argument>\", which isn't what we meant.\n>> \n>> Unlike a preceding commit where this was fixed for commands which had\n>\n> nit: if you're referring to patch 10 [1], it wouldn't be a \"preceding\"\n> commit. Otherwise, I'm not sure which commit you're referring to?\n\nThanks, yes this is incorrect. It's due to rebasing/reordering this &\nmissing this mention.\n\n> In any case, I'd personally prefer that this patch is combined with patch 10\n> anyway, since both fix the same underlying issue (just in different places).\n> Neither patch is particularly large, and it would be nice to make (and\n> review!) all of the \"fix alternates syntax\" changes at once.\n\nYes, it's the same issue, but I think I'll keep them split up (working\non a re-roll).\n\nThe reason is (as mentioned in the CL) to cleanly split up the\n\"consistency\" changes from the rest.\n\nI.e. in this one we need to change both *.c and *.txt versions, so it's\na \"new\" change, i.e. reviewers need to do more work to eyeball & review\na version that's never used that form in-tree.\n\nWhereas the \"consistency\" commits are ones where we *only* change one of\n*.c or *.txt, to make it consistent with the other existing and\ncorresponding form.\n\nThat still requires review to see which version should \"win\", but with\n34/34 (where we test all of those at the end) doesn't require the\nreviewer to consider whether the change is sensible at all (if it\ndoesn't make sense we already have that version in 1/2 places in-tree\nalready).\n"},{"id":"463802","messageId":"patch-v2-01.35-aecd3ff41f2-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 01/35] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:38:56Z","receivedAt":"2022-09-28T08:39:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 9fca21cc5f9..3d3bdeba9e4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -650,8 +650,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -665,6 +665,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not immediately after opening or\n+ before closing a [] or () pair:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463803","messageId":"patch-v2-02.35-63145b58504-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 02/35] builtin/bundle.c: use \\t, not fix indentation 2-SP indentation","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:38:57Z","receivedAt":"2022-09-28T08:40:02Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463804","messageId":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com","subject":"[PATCH v2 00/35] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:38:55Z","receivedAt":"2022-09-28T08:40:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"We are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nFor the rest of the general overview (the first paragraphs are\ncopy/pasted) see the v1 at:\nhttps://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/\n\nChanges since v1:\n\n * Clarified the CodingGuidelines update with Junio's suggested\n   wording/changes.\n\n * Fixed a mention to a \"preceding\" commit noted by Victoria.\n\n * Made one minor bit of \"sed\" syntax in 34/35 consistent with the\n   rest.\n\n * Added an assertion that \"-h\" output only has SP whitespace, not\n   TABs.\n\n * 20/35 shows a bug in v1 of this. I compared the -h and *.txt\n   output, but because I normalized (stripped away) the whitespace I\n   didn't notice that \"git tag\" was left unindented.\n\n   There's now a new test in 35/35 to test for that.\n\nVictoria: I decided not to go for your suggestion of trimming this\nseries down in [1]. Reasons:\n\n * It would take me time I don't have to spend on this, as some of it\n   isn't easy to cleanly re-arrange. E.g. the later \"make consistent\"\n   commits rely on earlier whitespace/basic syntax fixes.\n\n * A major advantage of reviewing this in one go is that the 34-35/35\n   tests at the end are asserting everything that came before\n   it.\n\n   That's what I meant re the \"mostly trust\" comment you replied to in\n   [1]. I.e. I aimed to make it easy for reviewers to trust that the\n   \"doc txt & -h consistency\" patches were only altering one side of\n   either -h or *.txt, with the other side being in-tree already.\n\n * I originally hacked this up with 34/35 coming first, but then to\n   make the commits atomic I needed to update the test with each\n   change to alter the list of built-ins expected to pass.\n\n   I think that original approach is arguably better, as you can\n   assert each commit in isolation, and it would certainly make it\n   easier to split this up. But to re-do it again at this point would\n   be more work & churn than I think this is worth.\n\nI'm attaching a \"Documentation/doc-diff @{u} HEAD\" below the range\ndiff, to make it easy to see what the end result of the *.txt changes\nhere is.\n\n1. https://lore.kernel.org/git/af319ab4-2351-2d74-e0c7-6153f229d88c@github.com/\n\nÆvar Arnfjörð Bjarmason (35):\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n  bundle: define subcommand -h in terms of command -h\n  blame: use a more detailed usage_msg_optf() error on bad -L\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  doc SYNOPSIS & -h: fix incorrect alternates syntax\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n  tests: assert consistent whitespace in -h output\n\n Documentation/CodingGuidelines                |  17 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |   6 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   2 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   2 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   2 +-\n Documentation/git-reflog.txt                  |  17 +-\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-send-pack.txt               |   3 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 +-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |   2 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  26 ++-\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 ++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 ++++---\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/worktree.c                            | 110 +++++++---\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 199 ++++++++++++++++++\n 78 files changed, 550 insertions(+), 185 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\nRange-diff against v1:\n 1:  b8cbd443987 !  1:  aecd3ff41f2 CodingGuidelines: update and clarify command-line conventions\n    @@ Documentation/CodingGuidelines: Writing Documentation:\n         [-q | --quiet]\n         [--utf8 | --no-utf8]\n      \n    -+ Use spacing around \"|\" token(s), but not on the inside of \"[]()\"\n    -+ tokens:\n    ++ Use spacing around \"|\" token(s), but not immediately after opening or\n    ++ before closing a [] or () pair:\n     +   Do: [-q | --quiet]\n     +   Don't: [-q|--quiet]\n     +\n 2:  66286fa3af7 =  2:  63145b58504 builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n 3:  b49268615c3 =  3:  6bcfab04cbe bundle: define subcommand -h in terms of command -h\n 4:  22c3d1a73dc =  4:  707cf48a900 blame: use a more detailed usage_msg_optf() error on bad -L\n 5:  dc66db38a62 =  5:  ad0216f798e doc SYNOPSIS: don't use ' for subcommands\n 6:  0b946d60fcc =  6:  adc18d392b5 doc SYNOPSIS: consistently use ' for commands\n 7:  a070c97f29b !  7:  3531d531a3f doc SYNOPSIS & -h: fix incorrect alternates syntax\n    @@ Commit message\n         \"[(-o | --option) <argument>]\", we were previously claiming that only\n         the long option accepted the \"<argument>\", which isn't what we meant.\n     \n    -    Unlike a preceding commit where this was fixed for commands which had\n    -    inconsistent \"-h\" and *.txt, for \"stash\" it's been with us in both the\n    -    \"-h\" and *.txt since bd514cada4b (stash: introduce 'git stash store',\n    -    2013-06-15).\n    +    This issue has been with us in both the \"-h\" and *.txt versions since\n    +    bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n    +\n    +    There are also issues with the alternates syntax for \"bugreport\" and\n    +    \"diagnose\", but in those cases only for one of *.c or *.txt, not\n    +    both. Those issues will be fixed in a subsequent \"consistency\" commit.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n 8:  75c39a2ff83 =  8:  4c68003904f built-ins: consistently add \"\\n\" between \"usage\" and options\n 9:  f79a6ead8b0 =  9:  a7d57827067 doc txt & -h consistency: word-wrap\n10:  965f6b3b3cb = 10:  93e63821bc6 doc txt & -h consistency: fix incorrect alternates syntax\n11:  698d8d3d53a = 11:  aaa36012fa2 doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n12:  55ce0f8632f = 12:  6501b9d1ecc doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n13:  d88690fa849 = 13:  5f421314536 doc txt & -h consistency: correct padding around \"[]()\"\n14:  12ec2627504 = 14:  6354bfea1b2 stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n15:  33d47a8a827 = 15:  28e1edaf68e doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n16:  1adbe9b7d12 = 16:  8cc40e09124 t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n17:  517f9f9a53f = 17:  97873747a1e doc txt & -h consistency: fix mismatching labels\n18:  df312ad3ceb = 18:  301280c9c3a doc txt & -h consistency: add or fix optional \"--\" syntax\n19:  77cf58aa9c7 = 19:  1b51906fa07 doc txt & -h consistency: make output order consistent\n20:  f6ecf6a38af ! 20:  1c2bc223c5d doc txt & -h consistency: add missing options and labels\n    @@ builtin/tag.c\n     -\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n     +\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n     +\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n    -+\t   \"[--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n    -+\t   \"[--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n    ++\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n    ++\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n      \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n      \tNULL\n      };\n21:  50e1a8c2b1e = 21:  5785ed1d667 doc txt & -h consistency: make \"rerere\" consistent\n22:  92c178d5303 = 22:  fde75be474a doc txt & -h consistency: make \"read-tree\" consistent\n23:  dee17f861b2 = 23:  a6a43d0b3fd doc txt & -h consistency: make \"bundle\" consistent\n24:  8cc52c68b67 = 24:  a4feebc5434 doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n25:  3b0295e3467 = 25:  a4d75ea691c doc txt & -h consistency: add missing options\n26:  3907f349948 = 26:  ac62cda1ab2 doc txt & -h consistency: make \"stash\" consistent\n27:  f6c9fb63a08 = 27:  42415194e3f doc txt & -h consistency: make \"annotate\" consistent\n28:  6607ed3e343 = 28:  42076626a08 doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n29:  dc32043b203 = 29:  a57b00648dc doc txt & -h consistency: make \"diff-tree\" consistent\n30:  0aea4ee2e03 = 30:  7289ab9e09b doc txt & -h consistency: make \"commit\" consistent\n31:  5da768a04bc = 31:  61a3c002690 reflog doc: list real subcommands up-front\n32:  5fa403db45a = 32:  a59f78d80c8 worktree: define subcommand -h in terms of command -h\n33:  280c3b56d97 = 33:  a63d8017381 doc txt & -h consistency: make \"worktree\" consistent\n34:  c15c1422055 ! 34:  aef2b7356dc tests: start asserting that *.txt SYNOPSIS matches -h output\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\t\t\t/^$/d;\n     +\t\t\ts/^usage: //;\n     +\t\t\ts/^ *or: //;\n    -+\t\t\tp\n    ++\t\t\tp;\n     +\t\t}' <out\n     +}\n     +\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +test_debug '>failing'\n     +while read builtin\n     +do\n    ++\ttest_expect_success \"$builtin -h output has no \\t\" '\n    ++\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    ++\t\t! grep \"$HT\" help.raw\n    ++\t'\n    ++\n     +\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n     +\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n     +\n -:  ----------- > 35:  c92a4f52a8c tests: assert consistent whitespace in -h output\n\nA manually produced doc-diff, as noted above:\n\t\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-annotate.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-annotate.1\n\tindex e1098d7841e..e696e5a03c7 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-annotate.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-annotate.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-annotate - Annotate file lines with commit information\n\t \n\t SYNOPSIS\n\t-       git annotate [<options>] <file> [<revision>]\n\t+       git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\n\t \n\t DESCRIPTION\n\t        Annotates each line in the given file with information from the commit\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-clean.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-clean.1\n\tindex cd823d5c176..13e20af3996 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-clean.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-clean.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-clean - Remove untracked files from the working tree\n\t \n\t SYNOPSIS\n\t-       git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n\t+       git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\n\t \n\t DESCRIPTION\n\t        Cleans the working tree by recursively removing files that are not\n\t@@ -14,16 +14,16 @@ DESCRIPTION\n\t        is specified, ignored files are also removed. This can, for example, be\n\t        useful to remove all build products.\n\t \n\t-       If any optional <path>... arguments are given, only those paths are\n\t+       If any optional <pathspec>... arguments are given, only those paths are\n\t        affected.\n\t \n\t OPTIONS\n\t        -d\n\t-           Normally, when no <path> is specified, git clean will not recurse\n\t-           into untracked directories to avoid removing too much. Specify -d\n\t-           to have it recurse into such directories as well. If any paths are\n\t-           specified, -d is irrelevant; all untracked files matching the\n\t-           specified paths (with exceptions for nested git directories\n\t+           Normally, when no <pathspec> is specified, git clean will not\n\t+           recurse into untracked directories to avoid removing too much.\n\t+           Specify -d to have it recurse into such directories as well. If any\n\t+           paths are specified, -d is irrelevant; all untracked files matching\n\t+           the specified paths (with exceptions for nested git directories\n\t            mentioned under --force) will be removed.\n\t \n\t        -f, --force\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-commit-graph.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-commit-graph.1\n\tindex 919c4015a5b..10e5b7f1fb9 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-commit-graph.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-commit-graph.1\n\t@@ -5,7 +5,10 @@ NAME\n\t \n\t SYNOPSIS\n\t        git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\n\t-       git commit-graph write <options> [--object-dir <dir>] [--[no-]progress]\n\t+       git commit-graph write [--object-dir <dir>] [--append]\n\t+                               [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n\t+                               [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n\t+                               <split options>\n\t \n\t DESCRIPTION\n\t        Manage the serialized commit-graph file.\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-credential-cache--daemon.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-credential-cache--daemon.1\n\tindex 6199b539d04..e81cabc3e9a 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-credential-cache--daemon.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-credential-cache--daemon.1\n\t@@ -5,7 +5,7 @@ NAME\n\t        memory\n\t \n\t SYNOPSIS\n\t-       git credential-cache--daemon [--debug] <socket>\n\t+       git credential-cache--daemon [--debug] <socket-path>\n\t \n\t DESCRIPTION\n\t            Note\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-diff-files.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-diff-files.1\n\tindex b0f4ed10de0..91c261e610d 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-diff-files.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-diff-files.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-diff-files - Compares files in the working tree and the index\n\t \n\t SYNOPSIS\n\t-       git diff-files [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n\t+       git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n\t \n\t DESCRIPTION\n\t        Compares the files in the working tree and the index. When paths are\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-hash-object.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-hash-object.1\n\tindex c7627bbf999..674c62143c8 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-hash-object.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-hash-object.1\n\t@@ -5,7 +5,8 @@ NAME\n\t        a file\n\t \n\t SYNOPSIS\n\t-       git hash-object [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n\t+       git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\n\t+                       [--stdin [--literally]] [--] <file>...\n\t        git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\n\t \n\t DESCRIPTION\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-interpret-trailers.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-interpret-trailers.1\n\tindex 1eaf26fec4c..ac4dfeaa0cf 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-interpret-trailers.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-interpret-trailers.1\n\t@@ -5,8 +5,9 @@ NAME\n\t        messages\n\t \n\t SYNOPSIS\n\t-       git interpret-trailers [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n\t-       git interpret-trailers [<options>] [--parse] [<file>...]\n\t+       git interpret-trailers [--in-place] [--trim-empty]\n\t+                               [(--trailer <token>[(=|:)<value>])...]\n\t+                               [--parse] [<file>...]\n\t \n\t DESCRIPTION\n\t        Help parsing or adding trailers lines, that look similar to RFC 822\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-merge-base.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-merge-base.1\n\tindex bb77c49baed..700d00f5e86 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-merge-base.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-merge-base.1\n\t@@ -4,8 +4,8 @@ NAME\n\t        git-merge-base - Find as good common ancestors as possible for a merge\n\t \n\t SYNOPSIS\n\t-       git merge-base [-a|--all] <commit> <commit>...\n\t-       git merge-base [-a|--all] --octopus <commit>...\n\t+       git merge-base [-a | --all] <commit> <commit>...\n\t+       git merge-base [-a | --all] --octopus <commit>...\n\t        git merge-base --is-ancestor <commit> <commit>\n\t        git merge-base --independent <commit>...\n\t        git merge-base --fork-point <ref> [<commit>]\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-mv.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-mv.1\n\tindex 68bd3298b6d..c608c146efc 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-mv.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-mv.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-mv - Move or rename a file, a directory, or a symlink\n\t \n\t SYNOPSIS\n\t-       git mv <options>... <args>...\n\t+       git mv [<options>] <source>... <destination>\n\t \n\t DESCRIPTION\n\t        Move or rename a file, directory or symlink.\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-pack-redundant.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-pack-redundant.1\n\tindex 6336769ea00..36e19089eda 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-pack-redundant.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-pack-redundant.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-pack-redundant - Find redundant pack files\n\t \n\t SYNOPSIS\n\t-       git pack-redundant [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n\t+       git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\n\t \n\t DESCRIPTION\n\t        This program computes which packs in your repository are redundant. The\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-prune-packed.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-prune-packed.1\n\tindex 2de5e6f2ddf..542cbe2780c 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-prune-packed.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-prune-packed.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-prune-packed - Remove extra objects that are already in pack files\n\t \n\t SYNOPSIS\n\t-       git prune-packed [-n|--dry-run] [-q|--quiet]\n\t+       git prune-packed [-n | --dry-run] [-q | --quiet]\n\t \n\t DESCRIPTION\n\t        This program searches the $GIT_OBJECT_DIRECTORY for all objects that\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-read-tree.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-read-tree.1\n\tindex 2d7366df2dc..0d08a46f13b 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-read-tree.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-read-tree.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-read-tree - Reads tree information into the index\n\t \n\t SYNOPSIS\n\t-       git read-tree [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n\t+       git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n\t                        [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n\t                        (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n\t \n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-receive-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-receive-pack.1\n\tindex 557b090b02e..bcd953a65f7 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-receive-pack.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-receive-pack.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-receive-pack - Receive what is pushed into the repository\n\t \n\t SYNOPSIS\n\t-       git-receive-pack <directory>\n\t+       git receive-pack <git-dir>\n\t \n\t DESCRIPTION\n\t        Invoked by git send-pack and updates the repository with the\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-reflog.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-reflog.1\n\tindex 78f0c8969d6..97101386014 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-reflog.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-reflog.1\n\t@@ -4,19 +4,16 @@ NAME\n\t        git-reflog - Manage reflog information\n\t \n\t SYNOPSIS\n\t-       git reflog <subcommand> <options>\n\t+       git reflog [show] [<log-options>] [<ref>]\n\t+       git reflog expire [--expire=<time>] [--expire-unreachable=<time>]\n\t+               [--rewrite] [--updateref] [--stale-fix]\n\t+               [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n\t+       git reflog delete [--rewrite] [--updateref]\n\t+               [--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n\t+       git reflog exists <ref>\n\t \n\t DESCRIPTION\n\t-       The command takes various subcommands, and different options depending\n\t-       on the subcommand:\n\t-\n\t-           git reflog [show] [<log-options>] [<ref>]\n\t-           git reflog expire [--expire=<time>] [--expire-unreachable=<time>]\n\t-                   [--rewrite] [--updateref] [--stale-fix]\n\t-                   [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n\t-           git reflog delete [--rewrite] [--updateref]\n\t-                   [--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n\t-           git reflog exists <ref>\n\t+       This command manages the information recorded in the reflogs.\n\t \n\t        Reference logs, or \"reflogs\", record when the tips of branches and\n\t        other references were updated in the local repository. Reflogs are\n\t@@ -26,7 +23,8 @@ DESCRIPTION\n\t        week ago in this local repository\", and so on. See gitrevisions(7) for\n\t        more details.\n\t \n\t-       This command manages the information recorded in the reflogs.\n\t+       The command takes various subcommands, and different options depending\n\t+       on the subcommand:\n\t \n\t        The \"show\" subcommand (which is also the default, in the absence of any\n\t        subcommands) shows the log of the reference provided in the\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-rerere.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-rerere.1\n\tindex 92b7d74d266..7fe89de8d53 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-rerere.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-rerere.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-rerere - Reuse recorded resolution of conflicted merges\n\t \n\t SYNOPSIS\n\t-       git rerere [clear|forget <pathspec>|diff|remaining|status|gc]\n\t+       git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\n\t \n\t DESCRIPTION\n\t        In a workflow employing relatively long lived topic branches, the\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-send-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-send-pack.1\n\tindex 56700af6311..f727babc314 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-send-pack.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-send-pack.1\n\t@@ -4,7 +4,8 @@ NAME\n\t        git-send-pack - Push objects over Git protocol to another repository\n\t \n\t SYNOPSIS\n\t-       git send-pack [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n\t+       git send-pack [--mirror] [--dry-run] [--force]\n\t+                       [--receive-pack=<git-receive-pack>]\n\t                        [--verbose] [--thin] [--atomic]\n\t                        [--[no-]signed|--signed=(true|false|if-asked)]\n\t                        [<host>:]<directory> (--all | <ref>...)\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-branch.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-branch.1\n\tindex b81c4999fa8..29480d4f8d7 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-branch.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-branch.1\n\t@@ -4,12 +4,12 @@ NAME\n\t        git-show-branch - Show branches and their commits\n\t \n\t SYNOPSIS\n\t-       git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n\t+       git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n\t                        [--current] [--color[=<when>] | --no-color] [--sparse]\n\t                        [--more=<n> | --list | --independent | --merge-base]\n\t                        [--no-name | --sha1-name] [--topics]\n\t                        [(<rev> | <glob>)...]\n\t-       git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n\t+       git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n\t \n\t DESCRIPTION\n\t        Shows the commit ancestry graph starting from the commits named with\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-ref.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-ref.1\n\tindex 05008ff520e..c9cb2839742 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-show-ref.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-show-ref.1\n\t@@ -4,8 +4,8 @@ NAME\n\t        git-show-ref - List references in a local repository\n\t \n\t SYNOPSIS\n\t-       git show-ref [-q|--quiet] [--verify] [--head] [-d|--dereference]\n\t-                    [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n\t+       git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\n\t+                    [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n\t                     [--heads] [--] [<pattern>...]\n\t        git show-ref --exclude-existing[=<pattern>]\n\t \n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-sparse-checkout.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-sparse-checkout.1\n\tindex 93c601af41d..42f20178480 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-sparse-checkout.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-sparse-checkout.1\n\t@@ -5,7 +5,7 @@ NAME\n\t        files\n\t \n\t SYNOPSIS\n\t-       git sparse-checkout <subcommand> [<options>]\n\t+       git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\n\t \n\t DESCRIPTION\n\t        This command is used to create sparse checkouts, which change the\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-stash.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-stash.1\n\tindex 27123a702e3..e56c0d42f00 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-stash.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-stash.1\n\t@@ -5,17 +5,20 @@ NAME\n\t \n\t SYNOPSIS\n\t        git stash list [<log-options>]\n\t-       git stash show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n\t-       git stash drop [-q|--quiet] [<stash>]\n\t-       git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n\t+       git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n\t+       git stash drop [-q | --quiet] [<stash>]\n\t+       git stash pop [--index] [-q | --quiet] [<stash>]\n\t+       git stash apply [--index] [-q | --quiet] [<stash>]\n\t        git stash branch <branchname> [<stash>]\n\t-       git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n\t-                    [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n\t+       git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n\t+                    [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n\t                     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n\t                     [--] [<pathspec>...]]\n\t+       git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n\t+                    [-u | --include-untracked] [-a | --all] [<message>]\n\t        git stash clear\n\t        git stash create [<message>]\n\t-       git stash store [-m|--message <message>] [-q|--quiet] <commit>\n\t+       git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\n\t \n\t DESCRIPTION\n\t        Use git stash when you want to record the current state of the working\n\t@@ -39,7 +42,7 @@ DESCRIPTION\n\t \n\t COMMANDS\n\t        push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index]\n\t-       [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message\n\t+       [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message)\n\t        <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--]\n\t        [<pathspec>...]\n\t            Save your local modifications to a new stash entry and roll them\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-status.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-status.1\n\tindex 40481e33502..def2218250f 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-status.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-status.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-status - Show the working tree status\n\t \n\t SYNOPSIS\n\t-       git status [<options>...] [--] [<pathspec>...]\n\t+       git status [<options>] [--] [<pathspec>...]\n\t \n\t DESCRIPTION\n\t        Displays paths that have differences between the index file and the\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-tag.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-tag.1\n\tindex 7b8a1f7121c..72082aade13 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-tag.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-tag.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-tag - Create, list, delete or verify a tag object signed with GPG\n\t \n\t SYNOPSIS\n\t-       git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n\t+       git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n\t                <tagname> [<commit> | <object>]\n\t        git tag -d <tagname>...\n\t        git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-update-server-info.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-update-server-info.1\n\tindex 8453bc47398..5495562a6d7 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-update-server-info.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-update-server-info.1\n\t@@ -5,7 +5,7 @@ NAME\n\t        servers\n\t \n\t SYNOPSIS\n\t-       git update-server-info\n\t+       git update-server-info [-f | --force]\n\t \n\t DESCRIPTION\n\t        A dumb server that does not do on-the-fly pack generations must have\n\t@@ -14,6 +14,10 @@ DESCRIPTION\n\t        references and packs the server has. This command generates such\n\t        auxiliary files.\n\t \n\t+OPTIONS\n\t+       -f, --force\n\t+           Allow adding otherwise ignored files.\n\t+\n\t OUTPUT\n\t        Currently the command updates the following files. Please see\n\t        gitrepository-layout(5) for description of what they are for:\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-upload-archive.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-upload-archive.1\n\tindex 95e69407775..4f81618976a 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-upload-archive.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-upload-archive.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-upload-archive - Send archive back to git-archive\n\t \n\t SYNOPSIS\n\t-       git upload-archive <directory>\n\t+       git upload-archive <repository>\n\t \n\t DESCRIPTION\n\t        Invoked by git archive --remote and sends a generated archive to the\n\t@@ -46,7 +46,7 @@ SECURITY\n\t        non-smart-http.\n\t \n\t OPTIONS\n\t-       <directory>\n\t+       <repository>\n\t            The repository to get a tar archive from.\n\t \n\t GIT\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-var.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-var.1\n\tindex e8981b47f97..dc25589cc08 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-var.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-var.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-var - Show a Git logical variable\n\t \n\t SYNOPSIS\n\t-       git var ( -l | <variable> )\n\t+       git var (-l | <variable>)\n\t \n\t DESCRIPTION\n\t        Prints a Git logical variable.\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-commit.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-commit.1\n\tindex 0d7dd5135b6..e7884d403a4 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-commit.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-commit.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-verify-commit - Check the GPG signature of commits\n\t \n\t SYNOPSIS\n\t-       git verify-commit <commit>...\n\t+       git verify-commit [-v | --verbose] <commit>...\n\t \n\t DESCRIPTION\n\t        Validates the GPG signature created by git commit -S.\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-pack.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-pack.1\n\tindex 7dc7eac065c..4c8cc24ab06 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-pack.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-pack.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-verify-pack - Validate packed Git archive files\n\t \n\t SYNOPSIS\n\t-       git verify-pack [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n\t+       git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n\t \n\t DESCRIPTION\n\t        Reads given idx file for packed Git archive created with the git\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-tag.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-tag.1\n\tindex 58d3d9ad5dd..02b8f38db8d 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-verify-tag.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-verify-tag.1\n\t@@ -4,7 +4,7 @@ NAME\n\t        git-verify-tag - Check the GPG signature of tags\n\t \n\t SYNOPSIS\n\t-       git verify-tag [--format=<format>] <tag>...\n\t+       git verify-tag [-v | --verbose] [--format=<format>] <tag>...\n\t \n\t DESCRIPTION\n\t        Validates the gpg signature created by git tag.\n\tdiff --git a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-worktree.1 b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-worktree.1\n\tindex 40ba511d7a8..cb5aebfca95 100644\n\t--- a/2a7d63a2453e2c30353342a2c9385fa22a846987/home/avar/share/man/man1/git-worktree.1\n\t+++ b/c92a4f52a8c961b9153647d88c22941cba93b087/home/avar/share/man/man1/git-worktree.1\n\t@@ -4,7 +4,8 @@ NAME\n\t        git-worktree - Manage multiple working trees\n\t \n\t SYNOPSIS\n\t-       git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n\t+       git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n\t+                          [-b <new-branch>] <path> [<commit-ish>]\n\t        git worktree list [-v | --porcelain [-z]]\n\t        git worktree lock [--reason <string>] <worktree>\n\t        git worktree move <worktree> <new-path>\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463805","messageId":"patch-v2-03.35-6bcfab04cbe-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 03/35] bundle: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:38:58Z","receivedAt":"2022-09-28T08:40:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git bundle\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 29 +++++++++++++++++++----------\n 1 file changed, 19 insertions(+), 10 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 5c78894afd5..1b08700bf9e 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -11,31 +11,40 @@\n  * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n  */\n \n-static const char * const builtin_bundle_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-\tN_(\"git bundle verify [<options>] <file>\"),\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n-\tNULL\n+#define BUILTIN_BUNDLE_CREATE_USAGE \\\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n+\tN_(\"git bundle verify [<options>] <file>\")\n+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n+\tN_(\"git bundle list-heads <file> [<refname>...]\")\n+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n+\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\n+static char const * const builtin_bundle_usage[] = {\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n+\tNULL,\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-\tN_(\"git bundle verify [<options>] <file>\"),\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463806","messageId":"patch-v2-04.35-707cf48a900-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 04/35] blame: use a more detailed usage_msg_optf() error on bad -L","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:38:59Z","receivedAt":"2022-09-28T08:40:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Improve the error message emitted when there's a bad -L argument, and\ndo so using the parse-options.c flavor of \"usage()\", instead of using\nthe non-parse-options.c usage() function. This was the last user of\nusage() in this file.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/blame.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex a9fe8cf7a68..8ec59fa2096 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tanchor = 1;\n \trange_set_init(&ranges, range_list.nr);\n \tfor (range_i = 0; range_i < range_list.nr; ++range_i) {\n+\t\tconst char *arg = range_list.items[range_i].string;\n \t\tlong bottom, top;\n-\t\tif (parse_range_arg(range_list.items[range_i].string,\n-\t\t\t\t    nth_line_cb, &sb, lno, anchor,\n+\t\tif (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n-\t\t\tusage(blame_usage);\n+\t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n+\t\t\t\t       blame_opt_usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463807","messageId":"patch-v2-07.35-3531d531a3f-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 07/35] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:02Z","receivedAt":"2022-09-28T08:40:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis issue has been with us in both the \"-h\" and *.txt versions since\nbd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n\nThere are also issues with the alternates syntax for \"bugreport\" and\n\"diagnose\", but in those cases only for one of *.c or *.txt, not\nboth. Those issues will be fixed in a subsequent \"consistency\" commit.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 6 +++---\n builtin/stash.c             | 6 +++---\n 2 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex c5d70918283..4856f452511 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -14,12 +14,12 @@ SYNOPSIS\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n+\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n \n DESCRIPTION\n -----------\n@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n COMMANDS\n --------\n \n-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>...]::\n+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>...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 2274aae2556..51d40efaac7 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n \tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [-m|--message <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n \tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463808","messageId":"patch-v2-05.35-ad0216f798e-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 05/35] doc SYNOPSIS: don't use ' for subcommands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:00Z","receivedAt":"2022-09-28T08:40:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Almost all of our documentation doesn't use \"'\" syntax for\nsubcommands, but these did, let's make them consistent with the\nrest.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex db9d46edfa9..0537d4645be 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [<log-options>] [<ref>]\n+'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4cfc8833780..4b613d4140c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n \n DESCRIPTION\n -----------\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463809","messageId":"patch-v2-06.35-adc18d392b5-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 06/35] doc SYNOPSIS: consistently use ' for commands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:01Z","receivedAt":"2022-09-28T08:40:23Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Most of our commands use ''-quotation only for the name of the command\nitself, and not its (optional) arguments. Let's do the same for these.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-export.txt     | 2 +-\n Documentation/git-sparse-checkout.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 1978dbdc6ad..4643ddbe68f 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [<options>]' | 'git fast-import'\n+'git fast-export' [<options>] | 'git fast-import'\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 3776705bf53..872436d7426 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [<options>]'\n+'git sparse-checkout' <subcommand> [<options>]\n \n \n DESCRIPTION\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463810","messageId":"patch-v2-08.35-4c68003904f-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 08/35] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:03Z","receivedAt":"2022-09-28T08:40:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change commands in the \"diff\" family and \"rev-list\" to separate the\nusage information and option listing with an empty line.\n\nIn the case of \"git diff -h\" we did this already (but let's use a\nconsistent \"\\n\" pattern there), for the rest these are now consistent\nwith how the parse_options() API would emit usage.\n\nAs we'll see in a subsequent commit this also helps to make the \"git\n<cmd> -h\" output more easily machine-readable, as we can assume that\nthe usage usage information is separated from the options by an empty\nline.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-files.c | 1 +\n builtin/diff-index.c | 1 +\n builtin/diff-tree.c  | 1 +\n builtin/diff.c       | 3 ++-\n builtin/rev-list.c   | 1 +\n 5 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/diff-files.c b/builtin/diff-files.c\nindex 92cf6e1e922..096ea2fedbc 100644\n--- a/builtin/diff-files.c\n+++ b/builtin/diff-files.c\n@@ -15,6 +15,7 @@\n \n static const char diff_files_usage[] =\n \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_files(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 7d158af6b6d..e667cf52e7d 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -11,6 +11,7 @@\n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 116097a404a..23f58702fa0 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)\n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n \"  --cc          show combined diff for merge commits removing uninteresting hunks\\n\"\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 54bb3de964c..67760b67552 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =\n \"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>\\n\"\n-\"   or: git diff [<options>] --no-index [--] <path> <path>\\n\"\n+\"   or: git diff [<options>] --no-index [--] <path> <path>\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n static const char *blob_path(struct object_array_entry *entry)\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex fba6f5d51f3..f67e2b33555 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -21,6 +21,7 @@\n \n static const char rev_list_usage[] =\n \"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n \"    --max-age=<epoch>\\n\"\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463811","messageId":"patch-v2-09.35-a7d57827067-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 09/35] doc txt & -h consistency: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:04Z","receivedAt":"2022-09-28T08:40:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere the *.txt and -h output didn't match as far as word-wrapping was\nconcerned.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-hash-object.txt | 3 ++-\n Documentation/git-worktree.txt    | 3 ++-\n builtin/bugreport.c               | 3 ++-\n builtin/commit-graph.c            | 8 ++++----\n builtin/commit-tree.c             | 4 ++--\n builtin/diagnose.c                | 3 ++-\n builtin/init-db.c                 | 3 ++-\n builtin/interpret-trailers.c      | 4 +++-\n builtin/read-tree.c               | 4 +++-\n builtin/show-branch.c             | 3 ++-\n builtin/show-ref.c                | 4 +++-\n 11 files changed, 27 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex df9e2c58bdb..58670ef12f7 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+\t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \n DESCRIPTION\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex ada30c86a7c..063d6eeb99d 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees\n SYNOPSIS\n --------\n [verse]\n-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n+\t\t   [-b <new-branch>] <path> [<commit-ish>]\n 'git worktree list' [-v | --porcelain [-z]]\n 'git worktree lock' [--reason <string>] <worktree>\n 'git worktree move' <worktree> <new-path>\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 530895be55f..faa268f3cfb 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]\"),\n+\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 51557fe786e..cd346f95f08 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -13,10 +13,10 @@\n \tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append] \" \\\n-\t   \"[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] \" \\\n-\t   \"[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] \" \\\n-\t   \"<split options>\")\n+\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n+\t   \"                       <split options>\")\n \n static const char * builtin_commit_graph_verify_usage[] = {\n \tBUILTIN_COMMIT_GRAPH_VERIFY_USAGE,\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 63ea3229333..e4b85d29d56 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,8 +15,8 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n-\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] \"\n-\t\t\"[(-F <file>)...] <tree>\"),\n+\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n+\t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 576e0e8e385..28c394a62a5 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,8 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]\"),\n+\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 546f9c595e7..08ba006d55e 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n }\n \n static const char *const init_db_usage[] = {\n-\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]\"),\n+\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 84748eafc01..4cf0cf265dc 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -13,7 +13,9 @@\n #include \"config.h\"\n \n static const char * const git_interpret_trailers_usage[] = {\n-\tN_(\"git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]\"),\n+\tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n+\t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n+\t   \"                       [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 9f1f33e9546..b3a389e1b1f 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)\n }\n \n static const char * const read_tree_usage[] = {\n-\tN_(\"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+\tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n+\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n \ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex d3f5715e3e3..c013abaf942 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {\n     N_(\"git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\\n\"\n        \"                [--current] [--color[=<when>] | --no-color] [--sparse]\\n\"\n        \"                [--more=<n> | --list | --independent | --merge-base]\\n\"\n-       \"                [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\"),\n+       \"                [--no-name | --sha1-name] [--topics]\\n\"\n+       \"                [(<rev> | <glob>)...]\"),\n     N_(\"git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\"),\n     NULL\n };\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 48569061087..3af6a53ee97 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -9,7 +9,9 @@\n #include \"parse-options.h\"\n \n static const char * const show_ref_usage[] = {\n-\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]\"),\n+\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\\n\"\n+\t   \"             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\\n\"\n+\t   \"             [--heads] [--] [<pattern>...]\"),\n \tN_(\"git show-ref --exclude-existing[=<pattern>]\"),\n \tNULL\n };\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463812","messageId":"patch-v2-10.35-93e63821bc6-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 10/35] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:05Z","receivedAt":"2022-09-28T08:40:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis syntax issue for \"bugreport\" originated in\n238b439d698 (bugreport: add tool to generate debugging info,\n2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\ncreate 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n\"bugreport\" documentation and code.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/diagnose.c  | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex faa268f3cfb..23170113cc8 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 28c394a62a5..474de9ec647 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463813","messageId":"patch-v2-16.35-8cc40e09124-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 16/35] t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:11Z","receivedAt":"2022-09-28T08:40:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"As in a preceding commit use \"<options>\", not \"<options>...\", in this\ncase there is no *.txt version, but let's fix this one too while we're\nat it.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/helper/test-proc-receive.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\nindex cc08506cf0b..a4b305f4947 100644\n--- a/t/helper/test-proc-receive.c\n+++ b/t/helper/test-proc-receive.c\n@@ -6,7 +6,7 @@\n #include \"test-tool.h\"\n \n static const char *proc_receive_usage[] = {\n-\t\"test-tool proc-receive [<options>...]\",\n+\t\"test-tool proc-receive [<options>]\",\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463814","messageId":"patch-v2-14.35-6354bfea1b2-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 14/35] stash doc SYNOPSIS & -h: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:09Z","receivedAt":"2022-09-28T08:40:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 12 ++++++------\n builtin/stash.c             | 28 ++++++++++++++--------------\n 2 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 4856f452511..ea16d2eae7c 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,17 +9,17 @@ SYNOPSIS\n --------\n [verse]\n 'git stash' list [<log-options>]\n-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n-'git stash' drop [-q|--quiet] [<stash>]\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n+'git stash' drop [-q | --quiet] [<stash>]\n+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 51d40efaac7..d91cf5fd3e1 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -24,16 +24,16 @@\n static const char * const git_stash_usage[] = {\n \tN_(\"git stash list [<options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n-\tN_(\"git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n-\tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"               [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463815","messageId":"patch-v2-13.35-5f421314536-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 13/35] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:08Z","receivedAt":"2022-09-28T08:40:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-diff-files.txt     | 2 +-\n Documentation/git-merge-base.txt     | 4 ++--\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-prune-packed.txt   | 2 +-\n Documentation/git-rerere.txt         | 2 +-\n Documentation/git-show-branch.txt    | 4 ++--\n Documentation/git-show-ref.txt       | 4 ++--\n Documentation/git-var.txt            | 2 +-\n Documentation/git-verify-pack.txt    | 2 +-\n builtin/bugreport.c                  | 2 +-\n builtin/diagnose.c                   | 2 +-\n builtin/sparse-checkout.c            | 2 +-\n 12 files changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex bf1febb9ae7..591e3801b7b 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b01ba3d3565 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n+'git merge-base' [-a | --all] <commit> <commit>...\n+'git merge-base' [-a | --all] --octopus <commit>...\n 'git merge-base' --is-ancestor <commit> <commit>\n 'git merge-base' --independent <commit>...\n 'git merge-base' --fork-point <ref> [<commit>]\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e52..dda80a740c8 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 9fed59a3172..844d6f808a0 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n SYNOPSIS\n --------\n [verse]\n-'git prune-packed' [-n|--dry-run] [-q|--quiet]\n+'git prune-packed' [-n | --dry-run] [-q | --quiet]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4b613d4140c..9d0e6f53e7e 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex e5ec6b467f9..71f608b1ff1 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits\n SYNOPSIS\n --------\n [verse]\n-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n \t\t[(<rev> | <glob>)...]\n-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ab4d271925d..d1d56f68b43 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository\n SYNOPSIS\n --------\n [verse]\n-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]\n-\t     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]\n+\t     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n \t     [--heads] [--] [<pattern>...]\n 'git show-ref' --exclude-existing[=<pattern>]\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex 387cc1b9142..6aa521fab23 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -9,7 +9,7 @@ git-var - Show a Git logical variable\n SYNOPSIS\n --------\n [verse]\n-'git var' ( -l | <variable> )\n+'git var' (-l | <variable>)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c20..b8720dce8ab 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files\n SYNOPSIS\n --------\n [verse]\n-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n \n \n DESCRIPTION\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex bb138161943..61d93383f51 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 474de9ec647..d52015c67a4 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 287716db68e..aac0f708e42 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init|list|set|add|reapply|disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463816","messageId":"patch-v2-11.35-aaa36012fa2-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 11/35] doc txt & -h consistency: add \"-z\" to cat-file \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:06Z","receivedAt":"2022-09-28T08:40:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited\ninput with `-z`, 2022-07-22), before that change the SYNOPSIS and \"-h\"\noutput were the same, but not afterwards.\n\nThat change followed a similar earlier divergence in\n473fa2df08d (Documentation: add --batch-command to cat-file synopsis,\n2022-04-07). Subsequent commits will fix this sort of thing more\nsystematically, but let's fix this one as a one-off.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/cat-file.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 989eee0bb4c..fa7bd891692 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] <object>\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t   \"             [--buffer] [--follow-symlinks] [--unordered]\\n\"\n-\t\t   \"             [--textconv | --filters]\"),\n+\t\t   \"             [--textconv | --filters] [-z]\"),\n \t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n \t\t   \"             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\"),\n \t\tNULL\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463817","messageId":"patch-v2-12.35-6501b9d1ecc-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 12/35] doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:07Z","receivedAt":"2022-09-28T08:40:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\nin aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n2022-08-12): We need to close the \"[\" we opened. The\ncorresponding *.txt change did not have the same issue.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 23170113cc8..bb138161943 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n \n static const char * const bugreport_usage[] = {\n \tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n-\t   \"              [--diagnose[=<mode>]\"),\n+\t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463818","messageId":"patch-v2-15.35-28e1edaf68e-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 15/35] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:10Z","receivedAt":"2022-09-28T08:40:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"It's arguably more correct to say \"[<option>...]\" than either of these\nforms, but the vast majority of our documentation uses the\n\"[<options>]\" form to indicate an arbitrary number of options, let's\ndo the same in these cases, which were the odd ones out.\n\nIn the case of \"mv\" let's add the missing \"[]\" to indicate that these\nare optional.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-mv.txt     | 2 +-\n Documentation/git-status.txt | 2 +-\n builtin/pack-objects.c       | 4 ++--\n 3 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 79449bf98fe..972a055fbd8 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' <options>... <args>...\n+'git mv' [<options>] <args>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 54a4b29b473..5e438a7fdc1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -9,7 +9,7 @@ git-status - Show the working tree status\n SYNOPSIS\n --------\n [verse]\n-'git status' [<options>...] [--] [<pathspec>...]\n+'git status' [<options>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3658c05cafc..573d0b20b76 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,\n #define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)\n \n static const char *pack_usage[] = {\n-\tN_(\"git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]\"),\n-\tN_(\"git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463819","messageId":"patch-v2-18.35-301280c9c3a-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 18/35] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:13Z","receivedAt":"2022-09-28T08:41:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add the \"[--]\" for those cases where the *.txt and -h were\ninconsistent, or where we incorrectly stated in one but not the other\nthat the \"--\" was mandatory.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/for-each-repo.c | 2 +-\n builtin/rev-list.c      | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex c6379b783c8..d45d873f579 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n+\tN_(\"git for-each-repo --config=<config> [--] <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex ada68a4af5e..3cc8aad52ed 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463820","messageId":"patch-v2-17.35-97873747a1e-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 17/35] doc txt & -h consistency: fix mismatching labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:12Z","receivedAt":"2022-09-28T08:41:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various inconsistencies between command SYNOPSIS and the\ncorresponding -h output where our translatable labels didn't match\nup.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt                    | 6 +++---\n Documentation/git-credential-cache--daemon.txt | 2 +-\n Documentation/git-mv.txt                       | 2 +-\n Documentation/git-receive-pack.txt             | 2 +-\n Documentation/git-tag.txt                      | 2 +-\n Documentation/git-upload-archive.txt           | 4 ++--\n builtin/bugreport.c                            | 2 +-\n builtin/clean.c                                | 2 +-\n builtin/commit-graph.c                         | 4 ++--\n builtin/credential-cache--daemon.c             | 2 +-\n builtin/for-each-repo.c                        | 2 +-\n builtin/pack-redundant.c                       | 2 +-\n builtin/rerere.c                               | 2 +-\n builtin/rev-list.c                             | 2 +-\n builtin/stash.c                                | 2 +-\n builtin/unpack-file.c                          | 2 +-\n builtin/upload-archive.c                       | 2 +-\n builtin/worktree.c                             | 2 +-\n 18 files changed, 22 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 91742633fa8..3f16f200d9a 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\n-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n \n DESCRIPTION\n -----------\n@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n \n-If any optional `<path>...` arguments are given, only those paths\n+If any optional `<pathspec>...` arguments are given, only those paths\n are affected.\n \n OPTIONS\n -------\n -d::\n-\tNormally, when no <path> is specified, git clean will not\n+\tNormally, when no <pathspec> is specified, git clean will not\n \trecurse into untracked directories to avoid removing too much.\n \tSpecify -d to have it recurse into such directories as well.\n \tIf any paths are specified, -d is irrelevant; all untracked\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 01e1c214dd8..74832d06806 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 972a055fbd8..c612a5fd5b9 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [<options>] <args>...\n+'git mv' [<options>] <source>... <destination>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 014a78409b9..eec1268b10f 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31a97a1b6c5..c15ec895720 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n \t<tagname> [<commit> | <object>]\n 'git tag' -d <tagname>...\n 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex fba0f1c1b27..e8eb10baad7 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n SYNOPSIS\n --------\n [verse]\n-'git upload-archive' <directory>\n+'git upload-archive' <repository>\n \n DESCRIPTION\n -----------\n@@ -54,7 +54,7 @@ access via non-smart-http.\n \n OPTIONS\n -------\n-<directory>::\n+<repository>::\n \tThe repository to get a tar archive from.\n \n GIT\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 61d93383f51..96052541cbf 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 5466636e666..6f039f555b2 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex cd346f95f08..b656a535c05 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -10,10 +10,10 @@\n #include \"tag.h\"\n \n #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n-\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n+\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n \t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex 4c6c89ab0de..ca672a6a619 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex fd86e5a8619..c6379b783c8 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <command-args>\"),\n+\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c\nindex ed9b9013a5f..ecd49ca268f 100644\n--- a/builtin/pack-redundant.c\n+++ b/builtin/pack-redundant.c\n@@ -14,7 +14,7 @@\n #define BLKSIZE 512\n \n static const char pack_redundant_usage[] =\n-\"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)\";\n+\"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\";\n \n static int load_all_packs, verbose, alt_odb;\n \ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 83d7a778e37..12570537d37 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <path>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n \tNULL,\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex f67e2b33555..ada68a4af5e 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex d91cf5fd3e1..83c9591ea6d 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -22,7 +22,7 @@\n #define INCLUDE_ALL_FILES 2\n \n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tN_(\"git stash list [<log-options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n \tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\ndiff --git a/builtin/unpack-file.c b/builtin/unpack-file.c\nindex 58652229f27..9e8119dd354 100644\n--- a/builtin/unpack-file.c\n+++ b/builtin/unpack-file.c\n@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)\n \tstruct object_id oid;\n \n \tif (argc != 2 || !strcmp(argv[1], \"-h\"))\n-\t\tusage(\"git unpack-file <sha1>\");\n+\t\tusage(\"git unpack-file <blob>\");\n \tif (get_oid(argv[1], &oid))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n \ndiff --git a/builtin/upload-archive.c b/builtin/upload-archive.c\nindex 98d028dae67..945ee2b4126 100644\n--- a/builtin/upload-archive.c\n+++ b/builtin/upload-archive.c\n@@ -10,7 +10,7 @@\n #include \"strvec.h\"\n \n static const char upload_archive_usage[] =\n-\t\"git upload-archive <repo>\";\n+\t\"git upload-archive <repository>\";\n \n static const char deadchild[] =\n \"git upload-archive: archiver died with error\";\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex c6710b25520..5bfc18e5a24 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {\n \tN_(\"git worktree prune [<options>]\"),\n \tN_(\"git worktree remove [<options>] <worktree>\"),\n \tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <path>\"),\n+\tN_(\"git worktree unlock <worktree>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463821","messageId":"patch-v2-19.35-1b51906fa07-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 19/35] doc txt & -h consistency: make output order consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:14Z","receivedAt":"2022-09-28T08:41:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix cases where the SYNOPSIS and -h output was presented in a\ndifferent order.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/merge-base.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex a11f8c6e4bb..6f3941f2a49 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n static const char * const merge_base_usage[] = {\n \tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n \tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n+\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n \tNULL\n };\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463822","messageId":"patch-v2-20.35-1c2bc223c5d-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 20/35] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:15Z","receivedAt":"2022-09-28T08:41:14Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various issues of SYNOPSIS and -h output syntax where:\n\n * Options such as --force were missing entirely\n * ...or the short option, such as -f\n\n * We said \"opts\" or \"options\", but could instead enumerate\n   the (small) set of supported options\n\n * argument labels were missing entirely (ls-remote)\n\n * How we referred to an argument was inconsistent between the two,\n   e.g. <pack> v.s. <pack>.idx.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-send-pack.txt          |  3 ++-\n Documentation/git-sparse-checkout.txt    |  2 +-\n Documentation/git-update-server-info.txt |  8 +++++++-\n Documentation/git-verify-commit.txt      |  2 +-\n Documentation/git-verify-tag.txt         |  2 +-\n builtin/credential-cache--daemon.c       |  2 +-\n builtin/describe.c                       |  5 +++--\n builtin/diff-index.c                     |  2 +-\n builtin/help.c                           |  2 +-\n builtin/ls-remote.c                      |  2 +-\n builtin/pack-refs.c                      |  2 +-\n builtin/revert.c                         |  9 +++++----\n builtin/send-pack.c                      |  1 +\n builtin/sparse-checkout.c                |  2 +-\n builtin/symbolic-ref.c                   |  5 +++--\n builtin/tag.c                            | 10 ++++++----\n builtin/update-server-info.c             |  2 +-\n builtin/upload-pack.c                    |  3 ++-\n builtin/verify-pack.c                    |  2 +-\n help.c                                   |  2 +-\n 20 files changed, 41 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex be41f119740..047713e3a81 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n+'git send-pack' [--mirror] [--dry-run] [--force]\n+\t\t[--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n \t\t[--[no-]signed|--signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 872436d7426..68392d2a56e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout' <subcommand> [<options>]\n+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\nindex 969bb2e15f1..4e6bf44427f 100644\n--- a/Documentation/git-update-server-info.txt\n+++ b/Documentation/git-update-server-info.txt\n@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n SYNOPSIS\n --------\n [verse]\n-'git update-server-info'\n+'git update-server-info' [-f | --force]\n \n DESCRIPTION\n -----------\n@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n what references and packs the server has.  This command\n generates such auxiliary files.\n \n+OPTIONS\n+-------\n+-f::\n+--force::\n+\tAllow adding otherwise ignored files.\n+\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\nindex 92097f6673d..96d10cfdffe 100644\n--- a/Documentation/git-verify-commit.txt\n+++ b/Documentation/git-verify-commit.txt\n@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n SYNOPSIS\n --------\n [verse]\n-'git verify-commit' <commit>...\n+'git verify-commit' [-v | --verbose] <commit>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\nindex 0b8075dad96..a454df2711e 100644\n--- a/Documentation/git-verify-tag.txt\n+++ b/Documentation/git-verify-tag.txt\n@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n SYNOPSIS\n --------\n [verse]\n-'git verify-tag' [--format=<format>] <tag>...\n+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex ca672a6a619..d4eb0097d24 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n+\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex e17c4b4c69b..23e3f05fb10 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -23,8 +23,9 @@\n define_commit_slab(commit_names, struct commit_name *);\n \n static const char * const describe_usage[] = {\n-\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n-\tN_(\"git describe [<options>] --dirty\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n+\tN_(\"git describe <blob>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex e667cf52e7d..aea139b9d8f 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -9,7 +9,7 @@\n #include \"submodule.h\"\n \n static const char diff_cache_usage[] =\n-\"git diff-index [-m] [--cached] \"\n+\"git diff-index [-m] [--cached] [--merge-base] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n \"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/help.c b/builtin/help.c\nindex 6f2796f211e..53f2812dfb1 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex df44e5cc0d1..5d5ac038716 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -7,7 +7,7 @@\n \n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n-\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n+\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n \t   \"              [--symref] [<repository> [<refs>...]]\"),\n \tNULL\n };\ndiff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\nindex cfbd5c36c76..27c2ca06acb 100644\n--- a/builtin/pack-refs.c\n+++ b/builtin/pack-refs.c\n@@ -5,7 +5,7 @@\n #include \"repository.h\"\n \n static char const * const pack_refs_usage[] = {\n-\tN_(\"git pack-refs [<options>]\"),\n+\tN_(\"git pack-refs [--all] [--no-prune]\"),\n \tNULL\n };\n \ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex ee2a0807f01..ee32c714a76 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -21,14 +21,15 @@\n  */\n \n static const char * const revert_usage[] = {\n-\tN_(\"git revert [<options>] <commit-ish>...\"),\n-\tN_(\"git revert <subcommand>\"),\n+\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n-\tN_(\"git cherry-pick <subcommand>\"),\n+\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n+\t   \"                [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \ndiff --git a/builtin/send-pack.c b/builtin/send-pack.c\nindex 64962be0168..dd9d2c4acc4 100644\n--- a/builtin/send-pack.c\n+++ b/builtin/send-pack.c\n@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n+\t   \"              [--[no-]signed|--signed=(true|false|if-asked)]\\n\"\n \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n \tNULL,\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex aac0f708e42..58a22503f04 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\nindex 1b0f10225f0..50b6df78df0 100644\n--- a/builtin/symbolic-ref.c\n+++ b/builtin/symbolic-ref.c\n@@ -5,8 +5,9 @@\n #include \"parse-options.h\"\n \n static const char * const git_symbolic_ref_usage[] = {\n-\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n-\tN_(\"git symbolic-ref -d [-q] <name>\"),\n+\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n+\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n+\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n \tNULL\n };\n \ndiff --git a/builtin/tag.c b/builtin/tag.c\nindex 75dece0e4f1..d428c45dc8d 100644\n--- a/builtin/tag.c\n+++ b/builtin/tag.c\n@@ -23,11 +23,13 @@\n #include \"date.h\"\n \n static const char * const git_tag_usage[] = {\n-\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n-\t   \"        <tagname> [<head>]\"),\n+\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n+\t   \"        <tagname> [<commit> | <object>]\"),\n \tN_(\"git tag -d <tagname>...\"),\n-\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n-\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n+\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n+\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n+\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n+\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n \tNULL\n };\ndiff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\nindex 880fffec587..d2239c9ef4d 100644\n--- a/builtin/update-server-info.c\n+++ b/builtin/update-server-info.c\n@@ -4,7 +4,7 @@\n #include \"parse-options.h\"\n \n static const char * const update_server_info_usage[] = {\n-\t\"git update-server-info [--force]\",\n+\t\"git update-server-info [-f | --force]\",\n \tNULL\n };\n \ndiff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\nindex 125af53885f..25b69da2bf2 100644\n--- a/builtin/upload-pack.c\n+++ b/builtin/upload-pack.c\n@@ -8,7 +8,8 @@\n #include \"serve.h\"\n \n static const char * const upload_pack_usage[] = {\n-\tN_(\"git upload-pack [<options>] <dir>\"),\n+\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n+\t   \"                [--advertise-refs] <directory>\"),\n \tNULL\n };\n \ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex 05c52135946..27d6f75fd8a 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n \tNULL\n };\n \ndiff --git a/help.c b/help.c\nindex d04542d8261..f1e090a4428 100644\n--- a/help.c\n+++ b/help.c\n@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \tstruct strbuf buf = STRBUF_INIT;\n \tint build_options = 0;\n \tconst char * const usage[] = {\n-\t\tN_(\"git version [<options>]\"),\n+\t\tN_(\"git version [--build-options]\"),\n \t\tNULL\n \t};\n \tstruct option options[] = {\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463823","messageId":"patch-v2-21.35-5785ed1d667-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 21/35] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:16Z","receivedAt":"2022-09-28T08:41:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\nthe order that they're discussed in the \"COMMANDS\" section of the\ndocumentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rerere.txt | 2 +-\n builtin/rerere.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 9d0e6f53e7e..992b469270c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 12570537d37..8b7392d5b44 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n \tNULL,\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463824","messageId":"patch-v2-23.35-a6a43d0b3fd-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 23/35] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:18Z","receivedAt":"2022-09-28T08:41:23Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend the -h output to match that of the *.txt output, the differences\nwere fairly small. In the case of \"[<options>]\" we only have a few of\nthem, so let's exhaustively list them as in the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 1b08700bf9e..544c78a5f3a 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,13 +12,14 @@\n  */\n \n #define BUILTIN_BUNDLE_CREATE_USAGE \\\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n+\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n-\tN_(\"git bundle verify [<options>] <file>\")\n+\tN_(\"git bundle verify [-q | --quiet] <file>\")\n #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n \tN_(\"git bundle list-heads <file> [<refname>...]\")\n #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n-\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n \n static char const * const builtin_bundle_usage[] = {\n \tBUILTIN_BUNDLE_CREATE_USAGE,\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463825","messageId":"patch-v2-22.35-fde75be474a-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 22/35] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:17Z","receivedAt":"2022-09-28T08:41:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The C version was right to use \"()\" in place of \"[]\", let's update\nthe *.txt version accordingly, and furthermore list the *.c options in\nthe same order as the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-read-tree.txt | 2 +-\n builtin/read-tree.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex b9bfdc0a319..7567955bad8 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n SYNOPSIS\n --------\n [verse]\n-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex b3a389e1b1f..f4cbe460b97 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n \n static const char * const read_tree_usage[] = {\n \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n-\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463826","messageId":"patch-v2-27.35-42415194e3f-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 27/35] doc txt & -h consistency: make \"annotate\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:22Z","receivedAt":"2022-09-28T08:41:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cmd_blame() already detected whether it was processing \"blame\" or\n\"annotate\", but it didn't adjust its usage output accordingly. Let's\ndo that.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-annotate.txt |  2 +-\n builtin/blame.c                | 21 +++++++++++++++------\n 2 files changed, 16 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex e44a831339d..5ae8aabe0f8 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [<options>] <file> [<revision>]\n+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex 8ec59fa2096..be9e091a86b 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -30,6 +30,7 @@\n #include \"tag.h\"\n \n static char blame_usage[] = N_(\"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n+static char annotate_usage[] = N_(\"git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n \n static const char *blame_opt_usage[] = {\n \tblame_usage,\n@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {\n \tNULL\n };\n \n+static const char *annotate_opt_usage[] = {\n+\tannotate_usage,\n+\t\"\",\n+\tN_(\"<rev-opts> are documented in git-rev-list(1)\"),\n+\tNULL\n+};\n+\n static int longest_file;\n static int longest_author;\n static int max_orig_digits;\n@@ -899,6 +907,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tlong anchor;\n \tconst int hexsz = the_hash_algo->hexsz;\n \tlong num_lines = 0;\n+\tconst char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n \n \tsetup_default_color_by_age();\n \tgit_config(git_blame_config, &output_option);\n@@ -914,7 +923,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tparse_options_start(&ctx, argc, argv, prefix, options,\n \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n \tfor (;;) {\n-\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n+\t\tswitch (parse_options_step(&ctx, options, usage)) {\n \t\tcase PARSE_OPT_NON_OPTION:\n \t\tcase PARSE_OPT_UNKNOWN:\n \t\t\tbreak;\n@@ -934,7 +943,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\tctx.argv[0] = \"--children\";\n \t\t\treverse = 1;\n \t\t}\n-\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n+\t\tparse_revision_opt(&revs, &ctx, options, usage);\n \t}\n parse_done:\n \trevision_opts_finish(&revs);\n@@ -1040,7 +1049,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\tswitch (argc - dashdash_pos - 1) {\n \t\tcase 2: /* (1b) */\n \t\t\tif (argc != 4)\n-\t\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\t\tusage_with_options(usage, options);\n \t\t\t/* reorder for the new way: <rev> -- <path> */\n \t\t\targv[1] = argv[3];\n \t\t\targv[3] = argv[2];\n@@ -1051,11 +1060,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\targv[argc] = NULL;\n \t\t\tbreak;\n \t\tdefault:\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\t}\n \t} else {\n \t\tif (argc < 2)\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n \t\t\tpath = add_prefix(prefix, argv[1]);\n \t\t\targv[1] = argv[2];\n@@ -1114,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n \t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n-\t\t\t\t       blame_opt_usage, options, arg);\n+\t\t\t\t       usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463827","messageId":"patch-v2-24.35-a4feebc5434-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 24/35] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:19Z","receivedAt":"2022-09-28T08:41:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\nreceive-pack\" and \"git credential-cache--daemon\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-receive-pack.txt | 2 +-\n builtin/credential-cache--daemon.c | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex eec1268b10f..92452334ac4 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <git-dir>\n+'git receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex d4eb0097d24..f3c89831d4a 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\n@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n {\n \tconst char * const usage[] = {\n-\t\t\"git credential-cache--daemon [options] <action>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\t\"\",\n \t\t\"credential-cache--daemon is disabled in this build of Git\",\n \t\tNULL\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463828","messageId":"patch-v2-25.35-a4d75ea691c-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 25/35] doc txt & -h consistency: add missing options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:20Z","receivedAt":"2022-09-28T08:41:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change those built-in commands that were attempting to exhaustively\nthe options in the \"-h\" output to actually do so, and always\nhave *.txt documentation know about the exhaustive list of options.\n\nLet's also fix the documentation and -h output for those built-in\ncommands where the *.txt and -h output was a mismatch of missing\noptions on both sides.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-commit-graph.txt       | 5 ++++-\n Documentation/git-interpret-trailers.txt | 5 +++--\n builtin/commit-tree.c                    | 1 +\n builtin/fsck.c                           | 5 ++++-\n builtin/hash-object.c                    | 5 +++--\n builtin/init-db.c                        | 2 ++\n builtin/interpret-trailers.c             | 2 +-\n builtin/rm.c                             | 4 +++-\n 8 files changed, 21 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 36fe56c2c71..82175ae62a1 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -10,7 +10,10 @@ SYNOPSIS\n --------\n [verse]\n 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n+'git commit-graph write' [--object-dir <dir>] [--append]\n+\t\t\t[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n+\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n+\t\t\t<split options>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 6d6197cd0a4..22ff3a603e0 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [<options>] [--parse] [<file>...]\n+'git interpret-trailers' [--in-place] [--trim-empty]\n+\t\t\t[(--trailer <token>[(=|:)<value>])...]\n+\t\t\t[--parse] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex e4b85d29d56..cc8d584be2f 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,6 +15,7 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n+\tN_(\"git commit-tree <tree> [(-p <parent>)...]\"),\n \tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n \t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\ndiff --git a/builtin/fsck.c b/builtin/fsck.c\nindex f7916f06ed5..ef273321d0b 100644\n--- a/builtin/fsck.c\n+++ b/builtin/fsck.c\n@@ -821,7 +821,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,\n }\n \n static char const * const fsck_usage[] = {\n-\tN_(\"git fsck [<options>] [<object>...]\"),\n+\tN_(\"git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\\n\"\n+\t   \"         [--[no-]full] [--strict] [--verbose] [--lost-found]\\n\"\n+\t   \"         [--[no-]dangling] [--[no-]progress] [--connectivity-only]\\n\"\n+\t   \"         [--[no-]name-objects] [<object>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex fbae878c2b9..11c3dfe0441 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -80,8 +80,9 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n-\t\t\"git hash-object  --stdin-paths\",\n+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\\n\"\n+\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n \t\tNULL\n \t};\n \tconst char *type = blob_type;\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 08ba006d55e..dcaaf102eaf 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n \n static const char *const init_db_usage[] = {\n \tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--separate-git-dir <git-dir>] [--object-format=<format>]\\n\"\n+\t   \"         [-b <branch-name> | --initial-branch=<branch-name>]\\n\"\n \t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 4cf0cf265dc..e58627c72a9 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -15,7 +15,7 @@\n static const char * const git_interpret_trailers_usage[] = {\n \tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n \t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n-\t   \"                       [<file>...]\"),\n+\t   \"                       [--parse] [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex b6ba859fe42..f0d025a4e23 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -17,7 +17,9 @@\n #include \"pathspec.h\"\n \n static const char * const builtin_rm_usage[] = {\n-\tN_(\"git rm [<options>] [--] <file>...\"),\n+\tN_(\"git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\\n\"\n+\t   \"       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"       [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463829","messageId":"patch-v2-31.35-61a3c002690-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 31/35] reflog doc: list real subcommands up-front","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:26Z","receivedAt":"2022-09-28T08:42:11Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"git reflog\" documentation to exhaustively list the\nsubcommands it accepts in the SYNOPSIS, as opposed to leaving that for\na \"[verse]\" in the DESCRIPTION section. This documentation style was\nadded in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how\nother commands which take subcommands are documented.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 15 ++++++---------\n 1 file changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 0537d4645be..ec64cbff4c6 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -8,14 +8,6 @@ git-reflog - Manage reflog information\n \n SYNOPSIS\n --------\n-[verse]\n-'git reflog' <subcommand> <options>\n-\n-DESCRIPTION\n------------\n-The command takes various subcommands, and different options\n-depending on the subcommand:\n-\n [verse]\n 'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n@@ -25,6 +17,10 @@ depending on the subcommand:\n \t[--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n 'git reflog exists' <ref>\n \n+DESCRIPTION\n+-----------\n+This command manages the information recorded in the reflogs.\n+\n Reference logs, or \"reflogs\", record when the tips of branches and\n other references were updated in the local repository. Reflogs are\n useful in various Git commands, to specify the old value of a\n@@ -33,7 +29,8 @@ moves ago\", `master@{one.week.ago}` means \"where master used to point\n to one week ago in this local repository\", and so on. See\n linkgit:gitrevisions[7] for more details.\n \n-This command manages the information recorded in the reflogs.\n+The command takes various subcommands, and different options\n+depending on the subcommand:\n \n The \"show\" subcommand (which is also the default, in the absence of\n any subcommands) shows the log of the reference provided in the\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463830","messageId":"patch-v2-26.35-ac62cda1ab2-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 26/35] doc txt & -h consistency: make \"stash\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:21Z","receivedAt":"2022-09-28T08:42:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend both the the -h output and *.txt to match one another. In this\ncase the *.txt didn't list the \"save\" subcommand, and the \"-h\" was\nsimilarly missing some commands.\n\nLet's also convert the *.c code to use a macro definition, similar to\nthat used in preceding commits. This avoids duplication.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt |  5 ++-\n builtin/stash.c             | 73 ++++++++++++++++++++++++-------------\n 2 files changed, 52 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex ea16d2eae7c..f4bb6114d91 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,12 +11,15 @@ SYNOPSIS\n 'git stash' list [<log-options>]\n 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n 'git stash' drop [-q | --quiet] [<stash>]\n-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n+'git stash' pop [--index] [-q | --quiet] [<stash>]\n+'git stash' apply [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [<message>]\n 'git stash' clear\n 'git stash' create [<message>]\n 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 83c9591ea6d..446a0089e84 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -21,72 +21,95 @@\n \n #define INCLUDE_ALL_FILES 2\n \n+#define BUILTIN_STASH_LIST_USAGE \\\n+\tN_(\"git stash list [<log-options>]\")\n+#define BUILTIN_STASH_SHOW_USAGE \\\n+\tN_(\"git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\")\n+#define BUILTIN_STASH_DROP_USAGE \\\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_POP_USAGE \\\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_APPLY_USAGE \\\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_BRANCH_USAGE \\\n+\tN_(\"git stash branch <branchname> [<stash>]\")\n+#define BUILTIN_STASH_STORE_USAGE \\\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\")\n+#define BUILTIN_STASH_PUSH_USAGE \\\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\" \\\n+\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\" \\\n+\t   \"          [--] [<pathspec>...]]\")\n+#define BUILTIN_STASH_SAVE_USAGE \\\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\")\n+#define BUILTIN_STASH_CREATE_USAGE \\\n+\tN_(\"git stash create [<message>]\")\n+#define BUILTIN_STASH_CLEAR_USAGE \\\n+\t\"git stash clear\"\n+\n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<log-options>]\"),\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n-\t\"git stash clear\",\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n+\tBUILTIN_STASH_SHOW_USAGE,\n+\tBUILTIN_STASH_DROP_USAGE,\n+\tBUILTIN_STASH_POP_USAGE,\n+\tBUILTIN_STASH_APPLY_USAGE,\n+\tBUILTIN_STASH_BRANCH_USAGE,\n+\tBUILTIN_STASH_PUSH_USAGE,\n+\tBUILTIN_STASH_SAVE_USAGE,\n+\tBUILTIN_STASH_CLEAR_USAGE,\n+\tBUILTIN_STASH_CREATE_USAGE,\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_list_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_show_usage[] = {\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n+\tBUILTIN_STASH_SHOW_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_DROP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_POP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_APPLY_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_branch_usage[] = {\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_clear_usage[] = {\n-\t\"git stash clear\",\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n+\tBUILTIN_STASH_PUSH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_SAVE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463831","messageId":"patch-v2-28.35-42076626a08-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 28/35] doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:23Z","receivedAt":"2022-09-28T08:42:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Correct uses of \"<label>...\" where we really meant to say\n\"[<label>...]\", i.e. the command in question taken an optional set of\n\"<label>\". As the CodingGuidelines notes \"[o]ptional parts [should be]\nenclosed in square brackets\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt | 2 +-\n builtin/clean.c             | 2 +-\n builtin/commit.c            | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 3f16f200d9a..db996a15e23 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\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>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 6f039f555b2..40ff2c578de 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex fcf9c85947e..21ad4ccbf87 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {\n };\n \n static const char * const builtin_status_usage[] = {\n-\tN_(\"git status [<options>] [--] <pathspec>...\"),\n+\tN_(\"git status [<options>] [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463832","messageId":"patch-v2-32.35-a59f78d80c8-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 32/35] worktree: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:27Z","receivedAt":"2022-09-28T08:42:26Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git worktree\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------\n 1 file changed, 84 insertions(+), 25 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 5bfc18e5a24..ba6846c3788 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -15,15 +15,72 @@\n #include \"worktree.h\"\n #include \"quote.h\"\n \n-static const char * const worktree_usage[] = {\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\"),\n-\tN_(\"git worktree list [<options>]\"),\n-\tN_(\"git worktree lock [<options>] <path>\"),\n-\tN_(\"git worktree move <worktree> <new-path>\"),\n-\tN_(\"git worktree prune [<options>]\"),\n-\tN_(\"git worktree remove [<options>] <worktree>\"),\n-\tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <worktree>\"),\n+#define BUILTIN_WORKTREE_ADD_USAGE \\\n+\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+#define BUILTIN_WORKTREE_LIST_USAGE \\\n+\tN_(\"git worktree list [<options>]\")\n+#define BUILTIN_WORKTREE_LOCK_USAGE \\\n+\tN_(\"git worktree lock [<options>] <path>\")\n+#define BUILTIN_WORKTREE_MOVE_USAGE \\\n+\tN_(\"git worktree move <worktree> <new-path>\")\n+#define BUILTIN_WORKTREE_PRUNE_USAGE \\\n+\tN_(\"git worktree prune [<options>]\")\n+#define BUILTIN_WORKTREE_REMOVE_USAGE \\\n+\tN_(\"git worktree remove [<options>] <worktree>\")\n+#define BUILTIN_WORKTREE_REPAIR_USAGE \\\n+\tN_(\"git worktree repair [<path>...]\")\n+#define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n+\tN_(\"git worktree unlock <worktree>\")\n+\n+static const char * const git_worktree_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_add_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tNULL,\n+};\n+\n+static const char * const git_worktree_list_usage[] = {\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_lock_usage[] = {\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_move_usage[] = {\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_prune_usage[] = {\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_remove_usage[] = {\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_repair_usage[] = {\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_unlock_usage[] = {\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n \tNULL\n };\n \n@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,\n+\t\t\t   0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_prune_usage, options);\n \tprune_worktrees();\n \treturn 0;\n }\n@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)\n \n \tmemset(&opts, 0, sizeof(opts));\n \topts.checkout = 1;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);\n \tif (!!opts.detach + !!new_branch + !!new_branch_force > 1)\n \t\tdie(_(\"options '%s', '%s', and '%s' cannot be used together\"), \"-b\", \"-B\", \"--detach\");\n \tif (lock_reason && !keep_locked)\n@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\topts.keep_locked = _(\"added with --lock\");\n \n \tif (ac < 1 || ac > 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_add_usage, options);\n \n \tpath = prefix_filename(prefix, av[0]);\n \tbranch = ac < 2 ? \"HEAD\" : av[1];\n@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_list_usage, options);\n \telse if (verbose && porcelain)\n \t\tdie(_(\"options '%s' and '%s' cannot be used together\"), \"--verbose\", \"--porcelain\");\n \telse if (!line_terminator && !porcelain)\n@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)\n \t};\n \tstruct worktree **worktrees, *wt;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_lock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)\n \tstruct worktree **worktrees, *wt;\n \tint ret;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_unlock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tchar *path;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_move_usage,\n+\t\t\t   0);\n \tif (ac != 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_move_usage, options);\n \n \tpath = prefix_filename(prefix, av[1]);\n \tstrbuf_addstr(&dst, path);\n@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tint ret = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_remove_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)\n \t};\n \tint rc = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);\n \tp = ac > 0 ? av : self;\n \tfor (; *p; p++)\n \t\trepair_worktree_at_path(*p, report_repair, &rc);\n@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)\n \tif (!prefix)\n \t\tprefix = \"\";\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);\n \treturn fn(ac, av, prefix);\n }\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463833","messageId":"patch-v2-33.35-a63d8017381-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 33/35] doc txt & -h consistency: make \"worktree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:28Z","receivedAt":"2022-09-28T08:42:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"worktree\" -h output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex ba6846c3788..4a24d53be15 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -16,17 +16,18 @@\n #include \"quote.h\"\n \n #define BUILTIN_WORKTREE_ADD_USAGE \\\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+\tN_(\"git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\\n\" \\\n+\t   \"                 [-b <new-branch>] <path> [<commit-ish>]\")\n #define BUILTIN_WORKTREE_LIST_USAGE \\\n-\tN_(\"git worktree list [<options>]\")\n+\tN_(\"git worktree list [-v | --porcelain [-z]]\")\n #define BUILTIN_WORKTREE_LOCK_USAGE \\\n-\tN_(\"git worktree lock [<options>] <path>\")\n+\tN_(\"git worktree lock [--reason <string>] <worktree>\")\n #define BUILTIN_WORKTREE_MOVE_USAGE \\\n \tN_(\"git worktree move <worktree> <new-path>\")\n #define BUILTIN_WORKTREE_PRUNE_USAGE \\\n-\tN_(\"git worktree prune [<options>]\")\n+\tN_(\"git worktree prune [-n] [-v] [--expire <expire>]\")\n #define BUILTIN_WORKTREE_REMOVE_USAGE \\\n-\tN_(\"git worktree remove [<options>] <worktree>\")\n+\tN_(\"git worktree remove [-f] <worktree>\")\n #define BUILTIN_WORKTREE_REPAIR_USAGE \\\n \tN_(\"git worktree repair [<path>...]\")\n #define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463834","messageId":"patch-v2-29.35-a57b00648dc-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 29/35] doc txt & -h consistency: make \"diff-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:24Z","receivedAt":"2022-09-28T08:42:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"diff-tree -h\" output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-tree.c | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 23f58702fa0..85e8c81e594 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)\n }\n \n static const char diff_tree_usage[] =\n-\"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\\n\"\n+\"              [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\\n\"\n+\"              [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n \"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463835","messageId":"patch-v2-35.35-c92a4f52a8c-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 35/35] tests: assert consistent whitespace in -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:30Z","receivedAt":"2022-09-28T08:42:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test for the *.txt and *.c output assertions which asserts that\nfor \"-h\" lines that aren't the \"usage: \" or \" or: \" lines they start\nwith the same amount of whitespace. This ensures that we won't have\nbuggy output like:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n       [--create-reflog] [...]\n\nWhich should instead be like this instead, i.e. the options lines\nshould be aligned:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n               [--create-reflog] [...]\n\nIt would be better to be able to use \"test_cmp\" here, i.e. to\nconstruct the output we expect, and compare it against the actual\noutput.\n\nFor most built-in commands this would be rather straightforward. In\n\"t0450-txt-doc-vs-help.sh\" we already compute the whitespace that a\n\"git-$builtin\" needs, and strip away \"usage: \" or \" or: \" from the\nstart of lines. The problem is:\n\n * For commands that implement subcommands, such as \"git bundle\", we\n   don't know whether e.g. \"git bundle create\" is the subcommand\n   \"create\", or the argument \"create\" to \"bundle\" for the purposes of\n   alignment.\n\n   We *do* have that information from the *.txt version, since the\n   part within the ''-quotes should be the command & subcommand, but\n   that isn't consistent (e.g. see \"git bundle\" and \"git\n   commit-graph\", only the latter is correct), and parsing that out\n   would be non-trivial.\n\n * If we were to make this stricter we have various\n   non-parse_options() users (e.g. \"git diff-tree\") that don't have the\n   nicely aligned output which we've had since\n   4631cfc20bd (parse-options: properly align continued usage output,\n   2021-09-21).\n\nSo rather than make perfect the enemy of the good let's assert that\nfor those lines that are indented they should all use the same\nindentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 9b1c70ef40c..5c1d01d2c66 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -129,6 +129,21 @@ do\n \t\t! grep \"$HT\" help.raw\n \t'\n \n+\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\t\tsed -n \\\n+\t\t\t-e \"/^ / {\n+\t\t\t\ts/[^ ].*//;\n+\t\t\t\tp;\n+\t\t\t}\" \\\n+\t\t\t<help.raw >help &&\n+\t\tsort -u help >help.ws &&\n+\t\tif test -s help.ws\n+\t\tthen\n+\t\t\ttest_line_count = 1 help.ws\n+\t\tfi\n+\t'\n+\n \ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n \tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463836","messageId":"patch-v2-30.35-7289ab9e09b-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 30/35] doc txt & -h consistency: make \"commit\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:25Z","receivedAt":"2022-09-28T08:42:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"-h\" output of \"git commit\" consistent with the *.txt version\nby exhaustively listing the options that it takes.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/commit.c | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex 21ad4ccbf87..64f420bcbf6 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -40,7 +40,14 @@\n #include \"pretty.h\"\n \n static const char * const builtin_commit_usage[] = {\n-\tN_(\"git commit [<options>] [--] <pathspec>...\"),\n+\tN_(\"git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\\n\"\n+\t   \"           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\\n\"\n+\t   \"           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\\n\"\n+\t   \"           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\\n\"\n+\t   \"           [--date=<date>] [--cleanup=<mode>] [--[no-]status]\\n\"\n+\t   \"           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\\n\"\n+\t   \"           [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463837","messageId":"patch-v2-34.35-aef2b7356dc-20220928T082458Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v2 34/35] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T08:39:29Z","receivedAt":"2022-09-28T08:42:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's been a lot of incremental effort to make the SYNOPSIS output\nin our documentation consistent with the -h output,\ne.g. cbe485298bf (git reflog [expire|delete]: make -h output\nconsistent with SYNOPSIS, 2022-03-17) is one recent example, but that\neffort has been an uphill battle due to the lack of regression\ntesting.\n\nThis adds such regression testing, we can parse out the SYNOPSIS\noutput with \"sed\", and is turns out it's relatively easy to normalize\nit and the \"-h\" output to match on another.\n\nWe now ensure that we won't have regressions when it comes to the list\nof commands in \"expect_help_to_match_txt\" below, and in subsequent\ncommits we'll make more of them consistent.\n\nThe naïve parser here gets quite a few things wrong, but it doesn't\nneed to be perfect, just good enough that we can compare /some/ of\nthis help output. There's no cases where the output would match except\nfor the parser's stupidity, it's all cases of e.g. comparing the *.txt\nto non-parse_options() output.\n\nSince that output is wildly different than the *.txt anyway let's\nleave this for now, we can fix the parser some other time, or it won't\nbecome necessary as we'll e.g. convert more things to using\nparse_options().\n\nHaving a special-case for \"merge-tree\"'s 1f0c3a29da3 (merge-tree:\nimplement real merges, 2022-06-18) is a bit ugly, but preferred to\nblessing that \" (deprecated)\" pattern for other commands. We'd\nprobably want to add some other way of marking deprecated commands in\nthe SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is\nindistinguishable from the command taking an optional literal\n\"deprecated\" string as an argument.\n\nSome of the issues that are left:\n\n * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n   all showing \"git log\" and \"git show\" usage output. I.e. the\n   \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n   command we're running.\n\n * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n   of what command it's running. The same for \"annotate\" and \"blame\".\n\n * Commands which implement subcommands such as like\n   \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n   in a very different order in the *.txt and *.c. Fixing it would\n   require some verbose diffs, so it's been left alone for onw.\n\n * Commands such as \"format-patch\" have a very long argument list in\n   the *.txt, but just \"[<options>]\" in the *.c.\n\n   What to do about these has been left out of this series, except to\n   the extent that preceding commits changed \"[<options>]\" (or\n   equivalent) to the list of options in cases where that list of\n   options was tiny, or we clearly meant to exhaustively list the\n   options in both *.txt and *.c.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines |   3 +-\n t/t0450-txt-doc-vs-help.sh     | 184 +++++++++++++++++++++++++++++++++\n 2 files changed, 186 insertions(+), 1 deletion(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 3d3bdeba9e4..4b10e832752 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -634,7 +634,8 @@ Writing Documentation:\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n- pages:\n+ pages. The two should match, see t/t0450-txt-doc-vs-help.sh for\n+ (partial) regression testing.\n \n  Placeholders are spelled in lowercase and enclosed in angle brackets:\n    <file>\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..9b1c70ef40c\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,184 @@\n+#!/bin/sh\n+\n+test_description='compare (unbuilt) Documentation/*.txt to -h output\n+\n+Run this with --debug to see a summary of where we still fail to make\n+the two versions consistent with one another.'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+test_expect_success 'setup: list of txt v.s. help' '\n+\tcat >list <<-\\EOF\n+\tadd\n+\tam\n+\tapply\n+\tarchive\n+\tbisect\n+\tblame\n+\tbranch\n+\tcheck-ref-format\n+\tcheckout\n+\tcheckout-index\n+\tclone\n+\tcolumn\n+\tconfig\n+\tcredential\n+\tcredential-cache\n+\tcredential-store\n+\tfast-export\n+\tfast-import\n+\tfetch-pack\n+\tfmt-merge-msg\n+\tfor-each-ref\n+\tformat-patch\n+\tfsck-objects\n+\tfsmonitor--daemon\n+\tgc\n+\tgrep\n+\tindex-pack\n+\tinit-db\n+\tlog\n+\tls-files\n+\tls-tree\n+\tmailinfo\n+\tmailsplit\n+\tmaintenance\n+\tmerge\n+\tmerge-file\n+\tmerge-index\n+\tmerge-one-file\n+\tmulti-pack-index\n+\tname-rev\n+\tnotes\n+\tpack-objects\n+\tpush\n+\trange-diff\n+\trebase\n+\tremote\n+\tremote-ext\n+\tremote-fd\n+\trepack\n+\treset\n+\trestore\n+\trev-parse\n+\tshow\n+\tstage\n+\tswitch\n+\tupdate-index\n+\tupdate-ref\n+\twhatchanged\n+\tEOF\n+'\n+\n+test_expect_success 'setup: list of txt v.s. help is sorted' '\n+\tsort -u list >list.sorted &&\n+\tif ! test_cmp list list.sorted\n+\tthen\n+\t\tBUG \"please keep the command list sorted\"\n+\tfi\n+'\n+\n+builtin_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\ttest_when_finished \"rm -f out\" &&\n+\ttest_expect_code 129 git $builtin -h >out 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp;\n+\t\t}' <out\n+}\n+\n+builtin_to_txt () {\n+\techo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n+}\n+\n+txt_synopsis () {\n+\tsed -n \\\n+\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\t/^\\[verse\\]$/d;\n+\t\t\ts/{litdd}/--/g;\n+\n+\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\tp;\n+\t\t}' \\\n+\t\t<\"$1\"\n+}\n+\n+HT=\"\t\"\n+align_after_nl () {\n+\tbuiltin=\"$1\" &&\n+\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n+\tpad=$(printf \"%${len}s\" \"\") &&\n+\n+\tsed \"s/^[ $HT][ $HT]*/$pad/\"\n+}\n+\n+test_debug '>failing'\n+while read builtin\n+do\n+\ttest_expect_success \"$builtin -h output has no \\t\" '\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\t\t! grep \"$HT\" help.raw\n+\t'\n+\n+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n+\n+\tif test -f \"$txt\"\n+\tthen\n+\t\ttest_set_prereq \"$preq\"\n+\tfi &&\n+\n+\tresult=\n+\tif grep -q \"^$builtin$\" list\n+\tthen\n+\t\tresult=failure\n+\telse\n+\t\tresult=success\n+\tfi &&\n+\n+\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n+\t\ttxt_synopsis \"$txt\" >txt.raw &&\n+\t\tif test \"$builtin\" = \"merge-tree\"\n+\t\tthen\n+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <txt.raw >txt.raw.new &&\n+\t\t\tmv txt.raw.new txt.raw\n+\t\tfi &&\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\n+\t\t# The *.txt and -h use different spacing for the\n+\t\t# alignment of continued usage output, normalize it.\n+\t\talign_after_nl \"$builtin\" <txt.raw >txt &&\n+\t\talign_after_nl \"$builtin\" <help.raw >help &&\n+\t\ttest_cmp txt help\n+\t'\n+\n+\tif test_have_prereq \"$preq\" && test -e txt && test -e help\n+\tthen\n+\t\ttest_debug '\n+\t\t\tif test_cmp txt help >cmp 2>/dev/null\n+\t\t\tthen\n+\t\t\t\techo \"=== DONE: $builtin ===\"\n+\t\t\telse\n+\t\t\t\techo \"=== TODO: $builtin ===\" &&\n+\t\t\t\tcat cmp\n+\t\t\tfi >>failing\n+\t\t'\n+\n+\t\t# Not in test_expect_success in case --run is being\n+\t\t# used with --debug\n+\t\trm -f txt help tmp 2>/dev/null\n+\tfi\n+done <builtins\n+\n+test_debug 'say \"$(cat failing)\"'\n+\n+test_done\n-- \n2.38.0.rc1.925.gb61c5ccd7da\n\n"},{"id":"463859","messageId":"xmqqpmffv24a.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v2-01.35-aecd3ff41f2-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 01/35] CodingGuidelines: update and clarify command-line conventions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-28T17:29:41Z","receivedAt":"2022-09-28T17:29:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n>   Optional parts are enclosed in square brackets:\n> -   [<extra>]\n> -   (Zero or one <extra>.)\n> +   [<file>...]\n> +   (Zero or more of <file>.)\n\nOK.\n\n> + Use spacing around \"|\" token(s), but not immediately after opening or\n> + before closing a [] or () pair:\n> +   Do: [-q | --quiet]\n> +   Don't: [-q|--quiet]\n> +\n> + Don't use spacing around \"|\" tokens when they're used to seperate the\n> + alternate arguments of an option:\n> +    Do: --track[=(direct|inherit)]\n> +    Don't: --track[=(direct | inherit)]\n> +\n\nHmph, that sounds inconsistent; I would have expected the same use\n(or omission) of space around the vertical bar.  But if that is the\nprevailing style, I won't complain about writing it down.\n\nThanks.\n\n"},{"id":"463868","messageId":"xmqqk05ntlye.fsf@gitster.g","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 00/35] doc/UX: make txt & -h output more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-28T18:04:09Z","receivedAt":"2022-09-28T18:04:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Victoria: I decided not to go for your suggestion of trimming this\n> series down in [1]. Reasons:\n>\n>  * It would take me time I don't have to spend on this, as some of it\n>    isn't easy to cleanly re-arrange. E.g. the later \"make consistent\"\n>    commits rely on earlier whitespace/basic syntax fixes.\n\nA devil's advocate question.  If even the original author feels it\ndoes not deserve his or her time to clean up the series, how does it\npossibly deserve reviewers' time to review such a series?\n\n>  * A major advantage of reviewing this in one go is that the 34-35/35\n>    tests at the end are asserting everything that came before\n>    it.\n\nYes, but it does not assert anything about the other patches not\ndoing unrelated things while at it.  So tests cannot be blindly\ntrusted (in other words you have to be also trustworthy, if the\nreviewers are expected to swallow this huge series uninspected).\n\nI'll give it a read-over when I find time.  Thanks for working on\nit.\n"},{"id":"463882","messageId":"220928.864jwrw8w0.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqk05ntlye.fsf@gitster.g","subject":"Re: [PATCH v2 00/35] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-28T20:10:33Z","receivedAt":"2022-09-28T20:18:13Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Sep 28 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>> Victoria: I decided not to go for your suggestion of trimming this\n>> series down in [1]. Reasons:\n>>\n>>  * It would take me time I don't have to spend on this, as some of it\n>>    isn't easy to cleanly re-arrange. E.g. the later \"make consistent\"\n>>    commits rely on earlier whitespace/basic syntax fixes.\n>\n> A devil's advocate question.  If even the original author feels it\n> does not deserve his or her time to clean up the series, how does it\n> possibly deserve reviewers' time to review such a series?\n\nSo, I'm clearly doing a bad job of explaining this (and I'm not saying\nI'm not also lazy!), but with the latter part of that I meant that I\ntook pains to optimize this for overall reviewer time.\n\nI.e. at the start of the series (made up example, but it'll suffice) we\nmight have stuff like this:\n\n\t*.txt usage: (foo|bar) <file>\n\t-h usage:    (foo | bar ) <dir>\n\nThe start of this series fixes a bunch of misc issues like whitespace\nissues, so we can e.g. turn that into:\n\n\t*.txt usage: (foo | bar) <file>\n\t-h usage:    (foo | bar) <dir>\n\nAt *that* point I can include the s/dir/file/ change on one side in a\n\"doc txt & -h consistency\" commit, and end up with, say:\n\n\t*.txt usage: (foo | bar) <file>\n\t-h usage:    (foo | bar) <file>\n\nSo, I can say for the \"doc txt & -h consistency\" that we had the \"(foo |\nbar) <file>\" version in-tree already, but that's only the case if you'll\nbuy the earlier whitespace-only change.\n\nI think that's easier to reason about & review than a bunch of \"here I'm\nchanging the label, and some whitespace issues, and blah blah\".\n\nI.e. the reviewer only has to pay attention to the first change being a\nwhitespace-only change, and can then be assured that post-whitespace\nchange we're just changing one side to be consistent with the other.\n\nWe then test that consistency at the end of the series.\n\n>>  * A major advantage of reviewing this in one go is that the 34-35/35\n>>    tests at the end are asserting everything that came before\n>>    it.\n>\n> Yes, but it does not assert anything about the other patches not\n> doing unrelated things while at it.  So tests cannot be blindly\n> trusted (in other words you have to be also trustworthy, if the\n> reviewers are expected to swallow this huge series uninspected).\n>\n> I'll give it a read-over when I find time.  Thanks for working on\n> it.\n\nRight, I didn't mean to say that these could be blindly trusted, just\nthat the series was working towards splitting up little fixes like\nwhatespace fixes, and at *that point* the reader should be assured that\none side of the commits with \"doc txt & -h consistency\" in the subject\nis in-tree already.\n\nOf course that at the minimum needs a review for *which side* we should\npick :)\n"},{"id":"463883","messageId":"xmqq7d1ns0qy.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v2-34.35-aef2b7356dc-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 34/35] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-28T20:27:33Z","receivedAt":"2022-09-28T20:27:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> There's been a lot of incremental effort to make the SYNOPSIS output\n> in our documentation consistent with the -h output,\n> e.g. cbe485298bf (git reflog [expire|delete]: make -h output\n> consistent with SYNOPSIS, 2022-03-17) is one recent example, but that\n> effort has been an uphill battle due to the lack of regression\n> testing.\n>\n> This adds such regression testing, we can parse out the SYNOPSIS\n> output with \"sed\", and is turns out it's relatively easy to normalize\n> it and the \"-h\" output to match on another.\n>\n> We now ensure that we won't have regressions when it comes to the list\n> of commands in \"expect_help_to_match_txt\" below, and in subsequent\n> commits we'll make more of them consistent.\n\nCall that file as such, not a plain \"list\".  It might be useful to\nhave it in Documentation/ or somewhere outside the test script so\nthat people who work on making the match know where to look, as you\nare updating CodingGuidelines for this change anyway.\n\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -634,7 +634,8 @@ Writing Documentation:\n>  \n>   A few commented examples follow to provide reference when writing or\n>   modifying command usage strings and synopsis sections in the manual\n> - pages:\n> + pages. The two should match, see t/t0450-txt-doc-vs-help.sh for\n> + (partial) regression testing.\n\n> +test_expect_success 'setup: list of txt v.s. help is sorted' '\n> +\tsort -u list >list.sorted &&\n> +\tif ! test_cmp list list.sorted\n> +\tthen\n> +\t\tBUG \"please keep the command list sorted\"\n> +\tfi\n> +'\n\nIf the list becomes an external file, we probably could add a\n\"recommended pre-commit hook\" for developers to reduce mistakes,\nprotecting us even from developers who forgets to run tests.\n\nOr even a \"clean\" filter that automatically sorts, specified via the\nattribute for that file, but that wouldn't protect us from careless\ndevelopers who are unlikely to enable the filter X-<.\n\n> +while read builtin\n> +do\n> +...\n> +done <builtins\n\nFun!\n\n\n"},{"id":"463888","messageId":"CAPig+cT+-bT0FUVYaGnMqwbAYasJPp2Ci+gC8=qRPf7vpxj=gQ@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v2-02.35-63145b58504-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 02/35] builtin/bundle.c: use \\t, not fix indentation 2-SP indentation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-09-28T23:35:31Z","receivedAt":"2022-09-28T23:35:47Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Sep 28, 2022 at 4:41 AM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n\nNot worth a reroll, but doesn't this have one to many instances of\n\"indentation\"? Also: s/fix/fixed/ ?\n\nI'd probably have written it simply as:\n\n    builtin/bundle.c: indent with tabs\n\n> Fix indentation issues introduced with 73c3253d75e (bundle: framework\n> for options before bundle file, 2019-11-10), and carried forward in\n> some subsequent commits.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n\nThe patch itself makes sense.\n"},{"id":"463890","messageId":"CAPig+cRyyGnUa8sjy63=AMdqZ6vF_7nXnUwbAFvvjYYNDCB=FA@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v2-08.35-4c68003904f-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 08/35] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-09-28T23:51:46Z","receivedAt":"2022-09-28T23:52:02Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Sep 28, 2022 at 4:42 AM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> Change commands in the \"diff\" family and \"rev-list\" to separate the\n> usage information and option listing with an empty line.\n>\n> In the case of \"git diff -h\" we did this already (but let's use a\n> consistent \"\\n\" pattern there), for the rest these are now consistent\n> with how the parse_options() API would emit usage.\n>\n> As we'll see in a subsequent commit this also helps to make the \"git\n> <cmd> -h\" output more easily machine-readable, as we can assume that\n> the usage usage information is separated from the options by an empty\n\ns/usage usage/usage/\n\n> line.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n> +\"\\n\"\n>  COMMON_DIFF_OPTIONS_HELP;\n>\n>  \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n>  \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n> +\"\\n\"\n>  \"  -r            diff recursively\\n\"\n\nThe patch itself was a confusing read until I realized that\nCOMMON_DIFF_OPTIONS_HELP embeds its own \"\\n\" as the first character.\n"},{"id":"463895","messageId":"CAPig+cS01QEcAvr0yqhdhGc8MtvHMofKOHSeJZy2yFqq0Oqo8Q@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v2-20.35-1c2bc223c5d-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 20/35] doc txt & -h consistency: add missing options and labels","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-09-29T03:04:49Z","receivedAt":"2022-09-29T03:05:10Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Sep 28, 2022 at 4:43 AM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> Fix various issues of SYNOPSIS and -h output syntax where:\n>\n>  * Options such as --force were missing entirely\n>  * ...or the short option, such as -f\n>\n>  * We said \"opts\" or \"options\", but could instead enumerate\n>    the (small) set of supported options\n>\n>  * argument labels were missing entirely (ls-remote)\n>\n>  * How we referred to an argument was inconsistent between the two,\n>    e.g. <pack> v.s. <pack>.idx.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n\nA few minor comments (probably not worth a re-roll)...\n\n> diff --git a/builtin/help.c b/builtin/help.c\n> @@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n>  static const char * const builtin_help_usage[] = {\n> -       \"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n> +       \"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n\nThis is merely removing an extra \"]\", thus should it instead be\nbundled along with [12/35] (after generalizing the commit message of\n[12/35] a bit)?\n\n> diff --git a/builtin/send-pack.c b/builtin/send-pack.c\n> @@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n>            \"              [--verbose] [--thin] [--atomic]\\n\"\n> +          \"              [--[no-]signed|--signed=(true|false|if-asked)]\\n\"\n\nShould there be spaces around the leftmost vertical bar per [14/35]?\n\n    [--[no-]signed | --signed=(true|false|if-asked)]\n\n> diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\n> @@ -20,7 +20,7 @@\n>  static char const * const builtin_sparse_checkout_usage[] = {\n> -       N_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n> +       N_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n\nDoes this change belong in [15/35] where you also add \"[\" and \"]\"\naround \"<options>\" for the 'mv' command? Citing [15/35]:\n\n    In the case of \"mv\" let's add the missing \"[]\" to indicate that these\n    are optional.\n\n> diff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\n> @@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n>  static const char * const verify_pack_usage[] = {\n> -       N_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n> +       N_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n\nPart of this change makes sense in this patch, but doesn't the \"[--]\"\npart belong in [18/35]?\n"},{"id":"463896","messageId":"CAPig+cSwokKApLJi6xHVUs1JZGJkjdxd0wkLT1Hqsr9UpPN-JQ@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v2-25.35-a4d75ea691c-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 25/35] doc txt & -h consistency: add missing options","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-09-29T04:36:45Z","receivedAt":"2022-09-29T04:37:02Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Sep 28, 2022 at 4:45 AM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> Change those built-in commands that were attempting to exhaustively\n> the options in the \"-h\" output to actually do so, and always\n\ns/exhaustively/exhaustively list/\n\n> have *.txt documentation know about the exhaustive list of options.\n>\n> Let's also fix the documentation and -h output for those built-in\n> commands where the *.txt and -h output was a mismatch of missing\n> options on both sides.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n> diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\n>  'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n> -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n> +'git commit-graph write' [--object-dir <dir>] [--append]\n> +                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n\nShould there be spaces around the vertical bars per [14/35]?\n\n    [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n\n> +                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n> +                       <split options>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> -'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n> -'git interpret-trailers' [<options>] [--parse] [<file>...]\n> +'git interpret-trailers' [--in-place] [--trim-empty]\n> +                       [(--trailer <token>[(=|:)<value>])...]\n> +                       [--parse] [<file>...]\n\nThis changes the interpretation from two distinct operating modes to a\nsingle mode. I had to go study the git-interpret-trailers\ndocumentation to convince myself that the revised synopsis is correct\nand matches the implementation, and that the old documented dual-mode\nbehavior was misleading. This probably should have been mentioned in\nthe commit message, or this change could have been split out to its\nown patch (not that I'm advocating making this series even longer).\n\n> diff --git a/builtin/hash-object.c b/builtin/hash-object.c\n>  int cmd_hash_object(int argc, const char **argv, const char *prefix)\n>  {\n>         static const char * const hash_object_usage[] = {\n> -               N_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n> -               \"git hash-object  --stdin-paths\",\n> +               N_(\"git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\\n\"\n> +                  \"                [--stdin [--literally]] [--] <file>...\"),\n> +               N_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n\nThis removes spaces around vertical bars, which seems to contradict\n[14/35] (unless I'm misunderstanding [14/35]).\n"},{"id":"463897","messageId":"CAPig+cRm5U45dhQuW1xAmhPZ=rn4b=QoRv1t0u3RtFaC374Y9w@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v2-26.35-ac62cda1ab2-20220928T082458Z-avarab@gmail.com","subject":"Re: [PATCH v2 26/35] doc txt & -h consistency: make \"stash\" consistent","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-09-29T04:41:44Z","receivedAt":"2022-09-29T04:41:58Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Sep 28, 2022 at 4:44 AM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> Amend both the the -h output and *.txt to match one another. In this\n\ns/the the/the/\n\n> case the *.txt didn't list the \"save\" subcommand, and the \"-h\" was\n> similarly missing some commands.\n>\n> Let's also convert the *.c code to use a macro definition, similar to\n> that used in preceding commits. This avoids duplication.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n> diff --git a/builtin/stash.c b/builtin/stash.c\n> @@ -21,72 +21,95 @@\n>  static const char * const git_stash_usage[] = {\n> +       BUILTIN_STASH_LIST_USAGE,\n> +       BUILTIN_STASH_SHOW_USAGE,\n> +       BUILTIN_STASH_DROP_USAGE,\n> +       BUILTIN_STASH_POP_USAGE,\n> +       BUILTIN_STASH_APPLY_USAGE,\n> +       BUILTIN_STASH_BRANCH_USAGE,\n> +       BUILTIN_STASH_PUSH_USAGE,\n> +       BUILTIN_STASH_SAVE_USAGE,\n> +       BUILTIN_STASH_CLEAR_USAGE,\n> +       BUILTIN_STASH_CREATE_USAGE,\n> +       BUILTIN_STASH_STORE_USAGE,\n>         NULL\n>  };\n>\n>  static const char * const git_stash_branch_usage[] = {\n> -       N_(\"git stash branch <branchname> [<stash>]\"),\n> +       BUILTIN_STASH_BRANCH_USAGE,\n>         NULL\n>  };\n>\n>  static const char * const git_stash_clear_usage[] = {\n> -       \"git stash clear\",\n> +       BUILTIN_STASH_BRANCH_USAGE,\n>         NULL\n>  };\n\nCopy/paste error: s/BRANCH/CLEAR/\n"},{"id":"463965","messageId":"xmqqzgegkcwb.fsf@gitster.g","threadId":"58397","inReplyTo":"xmqqpmffv24a.fsf@gitster.g","subject":"Re: [PATCH v2 01/35] CodingGuidelines: update and clarify command-line conventions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T17:09:08Z","receivedAt":"2022-09-30T17:09:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>>   Optional parts are enclosed in square brackets:\n>> -   [<extra>]\n>> -   (Zero or one <extra>.)\n>> +   [<file>...]\n>> +   (Zero or more of <file>.)\n>\n> OK.\n>\n>> + Use spacing around \"|\" token(s), but not immediately after opening or\n>> + before closing a [] or () pair:\n>> +   Do: [-q | --quiet]\n>> +   Don't: [-q|--quiet]\n>> +\n>> + Don't use spacing around \"|\" tokens when they're used to seperate the\n>> + alternate arguments of an option:\n>> +    Do: --track[=(direct|inherit)]\n>> +    Don't: --track[=(direct | inherit)]\n>> +\n>\n> Hmph, that sounds inconsistent; I would have expected the same use\n> (or omission) of space around the vertical bar.  But if that is the\n> prevailing style, I won't complain about writing it down.\n\nPerhaps in order to avoid \"Huh? isn't that inconsistent?\" knee-jerk\nreaction, it may be a good idea to explain the reason why?\n\nI am guessing that the difference between the two has something to\ndo with the desire to make it compact when it appears as a \"value\"\nfor something (signalled after a \"=\" sign), but (1) I am not sure if\nyou share the reasoning, and more importantly (2) I am failing to\ncome up with a concise way to phrase it.\n\nThanks.\n"},{"id":"463970","messageId":"220930.865yh4vk94.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqzgegkcwb.fsf@gitster.g","subject":"Re: [PATCH v2 01/35] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T17:27:54Z","receivedAt":"2022-09-30T17:34:57Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Sep 30 2022, Junio C Hamano wrote:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>>\n>>>   Optional parts are enclosed in square brackets:\n>>> -   [<extra>]\n>>> -   (Zero or one <extra>.)\n>>> +   [<file>...]\n>>> +   (Zero or more of <file>.)\n>>\n>> OK.\n>>\n>>> + Use spacing around \"|\" token(s), but not immediately after opening or\n>>> + before closing a [] or () pair:\n>>> +   Do: [-q | --quiet]\n>>> +   Don't: [-q|--quiet]\n>>> +\n>>> + Don't use spacing around \"|\" tokens when they're used to seperate the\n>>> + alternate arguments of an option:\n>>> +    Do: --track[=(direct|inherit)]\n>>> +    Don't: --track[=(direct | inherit)]\n>>> +\n>>\n>> Hmph, that sounds inconsistent; I would have expected the same use\n>> (or omission) of space around the vertical bar.  But if that is the\n>> prevailing style, I won't complain about writing it down.\n>\n> Perhaps in order to avoid \"Huh? isn't that inconsistent?\" knee-jerk\n> reaction, it may be a good idea to explain the reason why?\n\nI have a prepared v3 I was about to submit soon which points to existing\nexamples in the commit message, namely:\n\n\tgit grep -E -o '=\\([^)]+\\|[^)]+\\)' -- builtin Documentation/\n\n> I am guessing that the difference between the two has something to\n> do with the desire to make it compact when it appears as a \"value\"\n> for something (signalled after a \"=\" sign), but (1) I am not sure if\n> you share the reasoning, and more importantly (2) I am failing to\n> come up with a concise way to phrase it.\n\nI'm afraid mind reading is not one of my many talents :)\n\nI wasn't seeking to come up with some post-hoc rationalization for\nthese, but just to fill in the gaps in the CodingGuidelines.\n\nAny such guidelines are ultimately rather arbitrary, but I think most\nwould agree that whatever arbitrary thing we use we should probably pick\none if we can help it.\n\nWhich is what this series is aiming to do, i.e. to make these consistent\nwith the prevailing style, and homogenize the style of the *.txt and -h\nversion.\n\nI think that's reason enough, i.e. to just decree \"this is how it is\".\n\nLooking back at history you seem to have had the first commit with this\nsyntax, with many other people following shortly thereafter:\n\n\tgit log --reverse -p -G'--.*=\\([^)]+\\|[^)]+\\)' --\n\nSo if you want a rationale there your guess is probably better than\nmine...\n"},{"id":"463973","messageId":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com","subject":"[PATCH v3 00/36] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:23Z","receivedAt":"2022-09-30T18:08:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"We are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nFor the rest of the general overview (the first paragraphs are\ncopy/pasted) see the v1 at:\nhttps://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/;\nFor v2 see:\nhttps://lore.kernel.org/git/cover-v2-00.35-00000000000-20220928T082458Z-avarab@gmail.com/\n\nChanges since v2:\n\n * Numerous issues raised by Eric Sunshine, thanks a lot! I believe\n   this re-roll addresses all of them.\n\n * The 1/36 commit message attempts to explain the --foo=(x|y)\n   v.s. (--foo | --bar) whitespace inconsistency.\n\n * The list of command mismatches is now a file at\n   t/t0450/txt-help-mismatches, instead of being embedded in the test\n   (per Junio's request).\n\nÆvar Arnfjörð Bjarmason (36):\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: indent with tabs\n  bundle: define subcommand -h in terms of command -h\n  blame: use a more detailed usage_msg_optf() error on bad -L\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  doc SYNOPSIS & -h: fix incorrect alternates syntax\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc SYNOPSIS & -h: word-wrap\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n  tests: assert consistent whitespace in -h output\n\n Documentation/CodingGuidelines                |  14 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |   6 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   2 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   2 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   2 +-\n Documentation/git-reflog.txt                  |  17 +--\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-send-pack.txt               |   5 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 ++-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |   2 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  26 ++--\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 +++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 ++++++----\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/worktree.c                            | 110 ++++++++++----\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 136 ++++++++++++++++++\n t/t0450/txt-help-mismatches                   |  58 ++++++++\n 79 files changed, 544 insertions(+), 185 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n create mode 100644 t/t0450/txt-help-mismatches\n\nRange-diff against v2:\n 1:  aecd3ff41f2 !  1:  1611913e321 CodingGuidelines: update and clarify command-line conventions\n    @@ Commit message\n            alternatives, this is not a new policy, but just codifies what's\n            already the pattern in the most wide use in the documentation.\n     \n    +    Having a space around \" | \" for flags, but not for flag values is\n    +    inconsistent, but this style guide codifies existing\n    +    patterns. Grepping shows that we don't have any instance matching the\n    +    second \"Don't\" example:\n    +\n    +            git grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/CodingGuidelines ##\n 2:  63145b58504 !  2:  b2d76494a34 builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    builtin/bundle.c: use \\t, not fix indentation 2-SP indentation\n    +    builtin/bundle.c: indent with tabs\n     \n         Fix indentation issues introduced with 73c3253d75e (bundle: framework\n         for options before bundle file, 2019-11-10), and carried forward in\n 3:  6bcfab04cbe =  3:  953a72abee1 bundle: define subcommand -h in terms of command -h\n 4:  707cf48a900 =  4:  a8312c50f01 blame: use a more detailed usage_msg_optf() error on bad -L\n 5:  ad0216f798e =  5:  ec977f7c8fe doc SYNOPSIS: don't use ' for subcommands\n 6:  adc18d392b5 =  6:  b0ae035500c doc SYNOPSIS: consistently use ' for commands\n 7:  3531d531a3f =  7:  829bdf58499 doc SYNOPSIS & -h: fix incorrect alternates syntax\n 8:  4c68003904f !  8:  e9924890620 built-ins: consistently add \"\\n\" between \"usage\" and options\n    @@ Commit message\n     \n         As we'll see in a subsequent commit this also helps to make the \"git\n         <cmd> -h\" output more easily machine-readable, as we can assume that\n    -    the usage usage information is separated from the options by an empty\n    -    line.\n    +    the usage information is separated from the options by an empty line.\n    +\n    +    Note that \"COMMON_DIFF_OPTIONS_HELP\" starts with a \"\\n\", so the\n    +    seeming omission of a \"\\n\" here is correct, the second one is provided\n    +    by the macro.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n -:  ----------- >  9:  516af07e8a8 doc SYNOPSIS & -h: word-wrap\n 9:  a7d57827067 ! 10:  1a02f7c76cd doc txt & -h consistency: word-wrap\n    @@ Commit message\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## Documentation/git-hash-object.txt ##\n    -@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file\n    - SYNOPSIS\n    - --------\n    - [verse]\n    --'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n    -+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n    -+\t\t[--stdin [--literally]] [--] <file>...\n    - 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n    - \n    - DESCRIPTION\n    -\n      ## Documentation/git-worktree.txt ##\n     @@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees\n      SYNOPSIS\n10:  93e63821bc6 = 11:  7794c3d6ef5 doc txt & -h consistency: fix incorrect alternates syntax\n11:  aaa36012fa2 = 12:  357a228000c doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n12:  6501b9d1ecc ! 13:  57cbaee9826 doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    doc txt & -h consistency: add missing \"]\" to bugreport \"-h\"\n    +    doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n     \n         Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\n         in aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n         2022-08-12): We need to close the \"[\" we opened. The\n         corresponding *.txt change did not have the same issue.\n     \n    +    The \"help -h\" output then had one \"]\" too many, which is an issue\n    +    introduced in b40845293b5 (help: correct the usage string in -h and\n    +    documentation, 2021-09-10).\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## builtin/bugreport.c ##\n    @@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, i\n      \tNULL\n      };\n      \n    +\n    + ## builtin/help.c ##\n    +@@ builtin/help.c: static struct option builtin_help_options[] = {\n    + };\n    + \n    + static const char * const builtin_help_usage[] = {\n    +-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n    ++\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n    + \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n    + \t\"git help [-g|--guides]\",\n    + \t\"git help [-c|--config]\",\n13:  5f421314536 ! 14:  a29af2dcc4f doc txt & -h consistency: correct padding around \"[]()\"\n    @@ Documentation/git-diff-files.txt: git-diff-files - Compares files in the working\n      DESCRIPTION\n      -----------\n     \n    + ## Documentation/git-hash-object.txt ##\n    +@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file\n    + SYNOPSIS\n    + --------\n    + [verse]\n    +-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n    ++'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]\n    + \t\t[--stdin [--literally]] [--] <file>...\n    + 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n    + \n    +\n      ## Documentation/git-merge-base.txt ##\n     @@ Documentation/git-merge-base.txt: git-merge-base - Find as good common ancestors as possible for a merge\n      SYNOPSIS\n    @@ Documentation/git-rerere.txt: git-rerere - Reuse recorded resolution of conflict\n      DESCRIPTION\n      -----------\n     \n    + ## Documentation/git-send-pack.txt ##\n    +@@ Documentation/git-send-pack.txt: SYNOPSIS\n    + [verse]\n    + 'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n    + \t\t[--verbose] [--thin] [--atomic]\n    +-\t\t[--[no-]signed|--signed=(true|false|if-asked)]\n    ++\t\t[--[no-]signed | --signed=(true|false|if-asked)]\n    + \t\t[<host>:]<directory> (--all | <ref>...)\n    + \n    + DESCRIPTION\n    +\n      ## Documentation/git-show-branch.txt ##\n     @@ Documentation/git-show-branch.txt: git-show-branch - Show branches and their commits\n      SYNOPSIS\n    @@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, i\n      \tNULL\n      };\n     \n    + ## builtin/commit-graph.c ##\n    +@@\n    + \n    + #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n    + \tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n    +-\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n    ++\t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n    + \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n    + \t   \"                       <split options>\")\n    + \n    +\n      ## builtin/diagnose.c ##\n     @@\n      #include \"diagnose.h\"\n14:  6354bfea1b2 = 15:  589705cf6fa stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n15:  28e1edaf68e ! 16:  db850539d2a doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n    @@ Commit message\n         \"[<options>]\" form to indicate an arbitrary number of options, let's\n         do the same in these cases, which were the odd ones out.\n     \n    -    In the case of \"mv\" let's add the missing \"[]\" to indicate that these\n    -    are optional.\n    +    In the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\n    +    to indicate that these are optional.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    @@ builtin/pack-objects.c: static inline void oe_set_delta_size(struct packing_data\n      \tNULL\n      };\n      \n    +\n    + ## builtin/sparse-checkout.c ##\n    +@@\n    + static const char *empty_base = \"\";\n    + \n    + static char const * const builtin_sparse_checkout_usage[] = {\n    +-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n    ++\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n    + \tNULL\n    + };\n    + \n16:  8cc40e09124 = 17:  041aa64f3c7 t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n17:  97873747a1e ! 18:  3a439c4401d doc txt & -h consistency: fix mismatching labels\n    @@ builtin/commit-graph.c\n      #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n     -\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n     +\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n    - \t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n    + \t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n      \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n      \t   \"                       <split options>\")\n     \n    @@ builtin/upload-archive.c\n      static const char deadchild[] =\n      \"git upload-archive: archiver died with error\";\n     \n    + ## builtin/verify-pack.c ##\n    +@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has\n    + }\n    + \n    + static const char * const verify_pack_usage[] = {\n    +-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n    ++\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n    + \tNULL\n    + };\n    + \n    +\n      ## builtin/worktree.c ##\n     @@ builtin/worktree.c: static const char * const worktree_usage[] = {\n      \tN_(\"git worktree prune [<options>]\"),\n18:  301280c9c3a ! 19:  3bfdd3fb79e doc txt & -h consistency: add or fix optional \"--\" syntax\n    @@ builtin/rev-list.c\n      \"\\n\"\n      \"  limiting output:\\n\"\n      \"    --max-count=<n>\\n\"\n    +\n    + ## builtin/verify-pack.c ##\n    +@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has\n    + }\n    + \n    + static const char * const verify_pack_usage[] = {\n    +-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n    ++\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n    + \tNULL\n    + };\n    + \n19:  1b51906fa07 = 20:  98bdd0353cf doc txt & -h consistency: make output order consistent\n20:  1c2bc223c5d ! 21:  1713227d497 doc txt & -h consistency: add missing options and labels\n    @@ Documentation/git-send-pack.txt: git-send-pack - Push objects over Git protocol\n     +'git send-pack' [--mirror] [--dry-run] [--force]\n     +\t\t[--receive-pack=<git-receive-pack>]\n      \t\t[--verbose] [--thin] [--atomic]\n    - \t\t[--[no-]signed|--signed=(true|false|if-asked)]\n    + \t\t[--[no-]signed | --signed=(true|false|if-asked)]\n      \t\t[<host>:]<directory> (--all | <ref>...)\n     \n      ## Documentation/git-sparse-checkout.txt ##\n    @@ builtin/diff-index.c\n      \"\\n\"\n      COMMON_DIFF_OPTIONS_HELP;\n     \n    - ## builtin/help.c ##\n    -@@ builtin/help.c: static struct option builtin_help_options[] = {\n    - };\n    - \n    - static const char * const builtin_help_usage[] = {\n    --\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n    -+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n    - \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n    - \t\"git help [-g|--guides]\",\n    - \t\"git help [-c|--config]\",\n    -\n      ## builtin/ls-remote.c ##\n     @@\n      \n    @@ builtin/send-pack.c: static const char * const send_pack_usage[] = {\n      \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n      \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n      \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n    -+\t   \"              [--[no-]signed|--signed=(true|false|if-asked)]\\n\"\n    ++\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n      \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n      \tNULL,\n      };\n     \n    - ## builtin/sparse-checkout.c ##\n    -@@\n    - static const char *empty_base = \"\";\n    - \n    - static char const * const builtin_sparse_checkout_usage[] = {\n    --\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n    -+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n    - \tNULL\n    - };\n    - \n    -\n      ## builtin/symbolic-ref.c ##\n     @@\n      #include \"parse-options.h\"\n    @@ builtin/upload-pack.c\n      };\n      \n     \n    - ## builtin/verify-pack.c ##\n    -@@ builtin/verify-pack.c: static int verify_one_pack(const char *path, unsigned int flags, const char *has\n    - }\n    - \n    - static const char * const verify_pack_usage[] = {\n    --\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n    -+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n    - \tNULL\n    - };\n    - \n    -\n      ## help.c ##\n     @@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)\n      \tstruct strbuf buf = STRBUF_INIT;\n21:  5785ed1d667 = 22:  702eb747c0f doc txt & -h consistency: make \"rerere\" consistent\n22:  fde75be474a = 23:  01e20b8e452 doc txt & -h consistency: make \"read-tree\" consistent\n23:  a6a43d0b3fd = 24:  7f93da79fee doc txt & -h consistency: make \"bundle\" consistent\n24:  a4feebc5434 = 25:  ab109f73264 doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n25:  a4d75ea691c ! 26:  d57635b2707 doc txt & -h consistency: add missing options\n    @@ Commit message\n         doc txt & -h consistency: add missing options\n     \n         Change those built-in commands that were attempting to exhaustively\n    -    the options in the \"-h\" output to actually do so, and always\n    +    list the options in the \"-h\" output to actually do so, and always\n         have *.txt documentation know about the exhaustive list of options.\n     \n         Let's also fix the documentation and -h output for those built-in\n         commands where the *.txt and -h output was a mismatch of missing\n         options on both sides.\n     \n    +    In the case of \"interpret-trailers\" fixing the missing options reveals\n    +    that the *.txt version was implicitly claiming that the command had\n    +    two operating modes, which a look at the -h version (and studying the\n    +    documentation) will show is not the case.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-commit-graph.txt ##\n    @@ Documentation/git-commit-graph.txt: SYNOPSIS\n      'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n     -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n     +'git commit-graph write' [--object-dir <dir>] [--append]\n    -+\t\t\t[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\n    ++\t\t\t[--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n     +\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n     +\t\t\t<split options>\n      \n    @@ builtin/fsck.c: static int mark_packed_for_connectivity(const struct object_id *\n      \n     \n      ## builtin/hash-object.c ##\n    -@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n    - int cmd_hash_object(int argc, const char **argv, const char *prefix)\n    +@@ builtin/hash-object.c: int cmd_hash_object(int argc, const char **argv, const char *prefix)\n      {\n      \tstatic const char * const hash_object_usage[] = {\n    --\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n    + \t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n    +-\t\t   \"                [--stdin] [--] <file>...\"),\n     -\t\t\"git hash-object  --stdin-paths\",\n    -+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\\n\"\n     +\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n     +\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n      \t\tNULL\n26:  ac62cda1ab2 ! 27:  ac959d0cfc1 doc txt & -h consistency: make \"stash\" consistent\n    @@ Metadata\n      ## Commit message ##\n         doc txt & -h consistency: make \"stash\" consistent\n     \n    -    Amend both the the -h output and *.txt to match one another. In this\n    -    case the *.txt didn't list the \"save\" subcommand, and the \"-h\" was\n    +    Amend both the -h output and *.txt to match one another. In this case\n    +    the *.txt didn't list the \"save\" subcommand, and the \"-h\" was\n         similarly missing some commands.\n     \n         Let's also convert the *.c code to use a macro definition, similar to\n    @@ builtin/stash.c\n      \n      static const char * const git_stash_clear_usage[] = {\n     -\t\"git stash clear\",\n    -+\tBUILTIN_STASH_BRANCH_USAGE,\n    ++\tBUILTIN_STASH_CLEAR_USAGE,\n      \tNULL\n      };\n      \n27:  42415194e3f = 28:  f617375ea9e doc txt & -h consistency: make \"annotate\" consistent\n28:  42076626a08 = 29:  c96c3fc6d8d doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n29:  a57b00648dc = 30:  34b778dd176 doc txt & -h consistency: make \"diff-tree\" consistent\n30:  7289ab9e09b = 31:  336fc749f1c doc txt & -h consistency: make \"commit\" consistent\n31:  61a3c002690 = 32:  81024d1c3cd reflog doc: list real subcommands up-front\n32:  a59f78d80c8 = 33:  76e6b7d296a worktree: define subcommand -h in terms of command -h\n33:  a63d8017381 = 34:  efd0c2c634d doc txt & -h consistency: make \"worktree\" consistent\n34:  aef2b7356dc ! 35:  22da68abce3 tests: start asserting that *.txt SYNOPSIS matches -h output\n    @@ Commit message\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## Documentation/CodingGuidelines ##\n    -@@ Documentation/CodingGuidelines: Writing Documentation:\n    - \n    -  A few commented examples follow to provide reference when writing or\n    -  modifying command usage strings and synopsis sections in the manual\n    -- pages:\n    -+ pages. The two should match, see t/t0450-txt-doc-vs-help.sh for\n    -+ (partial) regression testing.\n    - \n    -  Placeholders are spelled in lowercase and enclosed in angle brackets:\n    -    <file>\n    -\n      ## t/t0450-txt-doc-vs-help.sh (new) ##\n     @@\n     +#!/bin/sh\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\tgit --list-cmds=builtins >builtins\n     +'\n     +\n    -+test_expect_success 'setup: list of txt v.s. help' '\n    -+\tcat >list <<-\\EOF\n    -+\tadd\n    -+\tam\n    -+\tapply\n    -+\tarchive\n    -+\tbisect\n    -+\tblame\n    -+\tbranch\n    -+\tcheck-ref-format\n    -+\tcheckout\n    -+\tcheckout-index\n    -+\tclone\n    -+\tcolumn\n    -+\tconfig\n    -+\tcredential\n    -+\tcredential-cache\n    -+\tcredential-store\n    -+\tfast-export\n    -+\tfast-import\n    -+\tfetch-pack\n    -+\tfmt-merge-msg\n    -+\tfor-each-ref\n    -+\tformat-patch\n    -+\tfsck-objects\n    -+\tfsmonitor--daemon\n    -+\tgc\n    -+\tgrep\n    -+\tindex-pack\n    -+\tinit-db\n    -+\tlog\n    -+\tls-files\n    -+\tls-tree\n    -+\tmailinfo\n    -+\tmailsplit\n    -+\tmaintenance\n    -+\tmerge\n    -+\tmerge-file\n    -+\tmerge-index\n    -+\tmerge-one-file\n    -+\tmulti-pack-index\n    -+\tname-rev\n    -+\tnotes\n    -+\tpack-objects\n    -+\tpush\n    -+\trange-diff\n    -+\trebase\n    -+\tremote\n    -+\tremote-ext\n    -+\tremote-fd\n    -+\trepack\n    -+\treset\n    -+\trestore\n    -+\trev-parse\n    -+\tshow\n    -+\tstage\n    -+\tswitch\n    -+\tupdate-index\n    -+\tupdate-ref\n    -+\twhatchanged\n    -+\tEOF\n    -+'\n    -+\n    -+test_expect_success 'setup: list of txt v.s. help is sorted' '\n    -+\tsort -u list >list.sorted &&\n    -+\tif ! test_cmp list list.sorted\n    ++test_expect_success 'list of txt and help mismatches is sorted' '\n    ++\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n    ++\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n     +\tthen\n    -+\t\tBUG \"please keep the command list sorted\"\n    ++\t\tBUG \"please keep the list of txt and help mismatches sorted\"\n     +\tfi\n     +'\n     +\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\tfi &&\n     +\n     +\tresult=\n    -+\tif grep -q \"^$builtin$\" list\n    ++\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n     +\tthen\n     +\t\tresult=failure\n     +\telse\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +test_debug 'say \"$(cat failing)\"'\n     +\n     +test_done\n    +\n    + ## t/t0450/txt-help-mismatches (new) ##\n    +@@\n    ++add\n    ++am\n    ++apply\n    ++archive\n    ++bisect\n    ++blame\n    ++branch\n    ++check-ref-format\n    ++checkout\n    ++checkout-index\n    ++clone\n    ++column\n    ++config\n    ++credential\n    ++credential-cache\n    ++credential-store\n    ++fast-export\n    ++fast-import\n    ++fetch-pack\n    ++fmt-merge-msg\n    ++for-each-ref\n    ++format-patch\n    ++fsck-objects\n    ++fsmonitor--daemon\n    ++gc\n    ++grep\n    ++index-pack\n    ++init-db\n    ++log\n    ++ls-files\n    ++ls-tree\n    ++mailinfo\n    ++mailsplit\n    ++maintenance\n    ++merge\n    ++merge-file\n    ++merge-index\n    ++merge-one-file\n    ++multi-pack-index\n    ++name-rev\n    ++notes\n    ++pack-objects\n    ++push\n    ++range-diff\n    ++rebase\n    ++remote\n    ++remote-ext\n    ++remote-fd\n    ++repack\n    ++reset\n    ++restore\n    ++rev-parse\n    ++show\n    ++stage\n    ++switch\n    ++update-index\n    ++update-ref\n    ++whatchanged\n35:  c92a4f52a8c = 36:  b56113dd620 tests: assert consistent whitespace in -h output\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463974","messageId":"patch-v3-02.36-b2d76494a34-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 02/36] builtin/bundle.c: indent with tabs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:25Z","receivedAt":"2022-09-30T18:08:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463975","messageId":"patch-v3-01.36-1611913e321-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 01/36] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:24Z","receivedAt":"2022-09-30T18:08:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nHaving a space around \" | \" for flags, but not for flag values is\ninconsistent, but this style guide codifies existing\npatterns. Grepping shows that we don't have any instance matching the\nsecond \"Don't\" example:\n\n\tgit grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 9fca21cc5f9..3d3bdeba9e4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -650,8 +650,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -665,6 +665,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not immediately after opening or\n+ before closing a [] or () pair:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463976","messageId":"patch-v3-04.36-a8312c50f01-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:27Z","receivedAt":"2022-09-30T18:08:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Improve the error message emitted when there's a bad -L argument, and\ndo so using the parse-options.c flavor of \"usage()\", instead of using\nthe non-parse-options.c usage() function. This was the last user of\nusage() in this file.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/blame.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex a9fe8cf7a68..8ec59fa2096 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tanchor = 1;\n \trange_set_init(&ranges, range_list.nr);\n \tfor (range_i = 0; range_i < range_list.nr; ++range_i) {\n+\t\tconst char *arg = range_list.items[range_i].string;\n \t\tlong bottom, top;\n-\t\tif (parse_range_arg(range_list.items[range_i].string,\n-\t\t\t\t    nth_line_cb, &sb, lno, anchor,\n+\t\tif (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n-\t\t\tusage(blame_usage);\n+\t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n+\t\t\t\t       blame_opt_usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463977","messageId":"patch-v3-03.36-953a72abee1-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 03/36] bundle: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:26Z","receivedAt":"2022-09-30T18:08:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git bundle\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 29 +++++++++++++++++++----------\n 1 file changed, 19 insertions(+), 10 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 5c78894afd5..1b08700bf9e 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -11,31 +11,40 @@\n  * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n  */\n \n-static const char * const builtin_bundle_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-\tN_(\"git bundle verify [<options>] <file>\"),\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n-\tNULL\n+#define BUILTIN_BUNDLE_CREATE_USAGE \\\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n+\tN_(\"git bundle verify [<options>] <file>\")\n+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n+\tN_(\"git bundle list-heads <file> [<refname>...]\")\n+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n+\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\n+static char const * const builtin_bundle_usage[] = {\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n+\tNULL,\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-\tN_(\"git bundle verify [<options>] <file>\"),\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463978","messageId":"patch-v3-05.36-ec977f7c8fe-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:28Z","receivedAt":"2022-09-30T18:08:49Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Almost all of our documentation doesn't use \"'\" syntax for\nsubcommands, but these did, let's make them consistent with the\nrest.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex db9d46edfa9..0537d4645be 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [<log-options>] [<ref>]\n+'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4cfc8833780..4b613d4140c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n \n DESCRIPTION\n -----------\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463979","messageId":"patch-v3-06.36-b0ae035500c-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 06/36] doc SYNOPSIS: consistently use ' for commands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:29Z","receivedAt":"2022-09-30T18:08:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Most of our commands use ''-quotation only for the name of the command\nitself, and not its (optional) arguments. Let's do the same for these.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-export.txt     | 2 +-\n Documentation/git-sparse-checkout.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 1978dbdc6ad..4643ddbe68f 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [<options>]' | 'git fast-import'\n+'git fast-export' [<options>] | 'git fast-import'\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 3776705bf53..872436d7426 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [<options>]'\n+'git sparse-checkout' <subcommand> [<options>]\n \n \n DESCRIPTION\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463980","messageId":"patch-v3-07.36-829bdf58499-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:30Z","receivedAt":"2022-09-30T18:09:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis issue has been with us in both the \"-h\" and *.txt versions since\nbd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n\nThere are also issues with the alternates syntax for \"bugreport\" and\n\"diagnose\", but in those cases only for one of *.c or *.txt, not\nboth. Those issues will be fixed in a subsequent \"consistency\" commit.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 6 +++---\n builtin/stash.c             | 6 +++---\n 2 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex c5d70918283..4856f452511 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -14,12 +14,12 @@ SYNOPSIS\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n+\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n \n DESCRIPTION\n -----------\n@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n COMMANDS\n --------\n \n-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>...]::\n+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>...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 2274aae2556..51d40efaac7 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n \tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [-m|--message <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n \tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463981","messageId":"patch-v3-09.36-516af07e8a8-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 09/36] doc SYNOPSIS & -h: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:32Z","receivedAt":"2022-09-30T18:09:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere both the -h output and *.txt were lacking in word-wrapping.\n\nThere are many more built-ins that could use this treatment, this\nchange is narrowed to those where this whitespace change is needed to\nmake the -h and *.txt consistent in the end.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-hash-object.txt | 3 ++-\n builtin/hash-object.c             | 3 ++-\n 2 files changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex df9e2c58bdb..58670ef12f7 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+\t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \n DESCRIPTION\ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex fbae878c2b9..f7c16802f0c 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n+\t\t   \"                [--stdin] [--] <file>...\"),\n \t\t\"git hash-object  --stdin-paths\",\n \t\tNULL\n \t};\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463982","messageId":"patch-v3-08.36-e9924890620-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 08/36] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:31Z","receivedAt":"2022-09-30T18:09:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change commands in the \"diff\" family and \"rev-list\" to separate the\nusage information and option listing with an empty line.\n\nIn the case of \"git diff -h\" we did this already (but let's use a\nconsistent \"\\n\" pattern there), for the rest these are now consistent\nwith how the parse_options() API would emit usage.\n\nAs we'll see in a subsequent commit this also helps to make the \"git\n<cmd> -h\" output more easily machine-readable, as we can assume that\nthe usage information is separated from the options by an empty line.\n\nNote that \"COMMON_DIFF_OPTIONS_HELP\" starts with a \"\\n\", so the\nseeming omission of a \"\\n\" here is correct, the second one is provided\nby the macro.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-files.c | 1 +\n builtin/diff-index.c | 1 +\n builtin/diff-tree.c  | 1 +\n builtin/diff.c       | 3 ++-\n builtin/rev-list.c   | 1 +\n 5 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/diff-files.c b/builtin/diff-files.c\nindex 92cf6e1e922..096ea2fedbc 100644\n--- a/builtin/diff-files.c\n+++ b/builtin/diff-files.c\n@@ -15,6 +15,7 @@\n \n static const char diff_files_usage[] =\n \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_files(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 7d158af6b6d..e667cf52e7d 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -11,6 +11,7 @@\n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 116097a404a..23f58702fa0 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)\n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n \"  --cc          show combined diff for merge commits removing uninteresting hunks\\n\"\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 54bb3de964c..67760b67552 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =\n \"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>\\n\"\n-\"   or: git diff [<options>] --no-index [--] <path> <path>\\n\"\n+\"   or: git diff [<options>] --no-index [--] <path> <path>\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n static const char *blob_path(struct object_array_entry *entry)\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex fba6f5d51f3..f67e2b33555 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -21,6 +21,7 @@\n \n static const char rev_list_usage[] =\n \"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n \"    --max-age=<epoch>\\n\"\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463983","messageId":"patch-v3-10.36-1a02f7c76cd-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 10/36] doc txt & -h consistency: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:33Z","receivedAt":"2022-09-30T18:09:28Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere the *.txt and -h output didn't match as far as word-wrapping was\nconcerned.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-worktree.txt | 3 ++-\n builtin/bugreport.c            | 3 ++-\n builtin/commit-graph.c         | 8 ++++----\n builtin/commit-tree.c          | 4 ++--\n builtin/diagnose.c             | 3 ++-\n builtin/init-db.c              | 3 ++-\n builtin/interpret-trailers.c   | 4 +++-\n builtin/read-tree.c            | 4 +++-\n builtin/show-branch.c          | 3 ++-\n builtin/show-ref.c             | 4 +++-\n 10 files changed, 25 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex ada30c86a7c..063d6eeb99d 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees\n SYNOPSIS\n --------\n [verse]\n-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n+\t\t   [-b <new-branch>] <path> [<commit-ish>]\n 'git worktree list' [-v | --porcelain [-z]]\n 'git worktree lock' [--reason <string>] <worktree>\n 'git worktree move' <worktree> <new-path>\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 530895be55f..faa268f3cfb 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]\"),\n+\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 51557fe786e..cd346f95f08 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -13,10 +13,10 @@\n \tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append] \" \\\n-\t   \"[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] \" \\\n-\t   \"[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] \" \\\n-\t   \"<split options>\")\n+\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n+\t   \"                       <split options>\")\n \n static const char * builtin_commit_graph_verify_usage[] = {\n \tBUILTIN_COMMIT_GRAPH_VERIFY_USAGE,\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 63ea3229333..e4b85d29d56 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,8 +15,8 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n-\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] \"\n-\t\t\"[(-F <file>)...] <tree>\"),\n+\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n+\t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 576e0e8e385..28c394a62a5 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,8 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]\"),\n+\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 546f9c595e7..08ba006d55e 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n }\n \n static const char *const init_db_usage[] = {\n-\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]\"),\n+\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 84748eafc01..4cf0cf265dc 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -13,7 +13,9 @@\n #include \"config.h\"\n \n static const char * const git_interpret_trailers_usage[] = {\n-\tN_(\"git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]\"),\n+\tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n+\t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n+\t   \"                       [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 9f1f33e9546..b3a389e1b1f 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)\n }\n \n static const char * const read_tree_usage[] = {\n-\tN_(\"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+\tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n+\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n \ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex d3f5715e3e3..c013abaf942 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {\n     N_(\"git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\\n\"\n        \"                [--current] [--color[=<when>] | --no-color] [--sparse]\\n\"\n        \"                [--more=<n> | --list | --independent | --merge-base]\\n\"\n-       \"                [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\"),\n+       \"                [--no-name | --sha1-name] [--topics]\\n\"\n+       \"                [(<rev> | <glob>)...]\"),\n     N_(\"git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\"),\n     NULL\n };\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 48569061087..3af6a53ee97 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -9,7 +9,9 @@\n #include \"parse-options.h\"\n \n static const char * const show_ref_usage[] = {\n-\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]\"),\n+\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\\n\"\n+\t   \"             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\\n\"\n+\t   \"             [--heads] [--] [<pattern>...]\"),\n \tN_(\"git show-ref --exclude-existing[=<pattern>]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463984","messageId":"patch-v3-11.36-7794c3d6ef5-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:34Z","receivedAt":"2022-09-30T18:09:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis syntax issue for \"bugreport\" originated in\n238b439d698 (bugreport: add tool to generate debugging info,\n2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\ncreate 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n\"bugreport\" documentation and code.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/diagnose.c  | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex faa268f3cfb..23170113cc8 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 28c394a62a5..474de9ec647 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463985","messageId":"patch-v3-12.36-357a228000c-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 12/36] doc txt & -h consistency: add \"-z\" to cat-file \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:35Z","receivedAt":"2022-09-30T18:09:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited\ninput with `-z`, 2022-07-22), before that change the SYNOPSIS and \"-h\"\noutput were the same, but not afterwards.\n\nThat change followed a similar earlier divergence in\n473fa2df08d (Documentation: add --batch-command to cat-file synopsis,\n2022-04-07). Subsequent commits will fix this sort of thing more\nsystematically, but let's fix this one as a one-off.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/cat-file.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 989eee0bb4c..fa7bd891692 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] <object>\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t   \"             [--buffer] [--follow-symlinks] [--unordered]\\n\"\n-\t\t   \"             [--textconv | --filters]\"),\n+\t\t   \"             [--textconv | --filters] [-z]\"),\n \t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n \t\t   \"             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\"),\n \t\tNULL\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463986","messageId":"patch-v3-13.36-57cbaee9826-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 13/36] doc txt & -h consistency: balance unbalanced \"[\" and \"]\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:36Z","receivedAt":"2022-09-30T18:09:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\nin aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n2022-08-12): We need to close the \"[\" we opened. The\ncorresponding *.txt change did not have the same issue.\n\nThe \"help -h\" output then had one \"]\" too many, which is an issue\nintroduced in b40845293b5 (help: correct the usage string in -h and\ndocumentation, 2021-09-10).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/help.c      | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 23170113cc8..bb138161943 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n \n static const char * const bugreport_usage[] = {\n \tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n-\t   \"              [--diagnose[=<mode>]\"),\n+\t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 6f2796f211e..53f2812dfb1 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463987","messageId":"patch-v3-15.36-589705cf6fa-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 15/36] stash doc SYNOPSIS & -h: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:38Z","receivedAt":"2022-09-30T18:10:02Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 12 ++++++------\n builtin/stash.c             | 28 ++++++++++++++--------------\n 2 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 4856f452511..ea16d2eae7c 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,17 +9,17 @@ SYNOPSIS\n --------\n [verse]\n 'git stash' list [<log-options>]\n-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n-'git stash' drop [-q|--quiet] [<stash>]\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n+'git stash' drop [-q | --quiet] [<stash>]\n+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 51d40efaac7..d91cf5fd3e1 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -24,16 +24,16 @@\n static const char * const git_stash_usage[] = {\n \tN_(\"git stash list [<options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n-\tN_(\"git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n-\tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"               [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463988","messageId":"patch-v3-14.36-a29af2dcc4f-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 14/36] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:37Z","receivedAt":"2022-09-30T18:10:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-diff-files.txt     | 2 +-\n Documentation/git-hash-object.txt    | 2 +-\n Documentation/git-merge-base.txt     | 4 ++--\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-prune-packed.txt   | 2 +-\n Documentation/git-rerere.txt         | 2 +-\n Documentation/git-send-pack.txt      | 2 +-\n Documentation/git-show-branch.txt    | 4 ++--\n Documentation/git-show-ref.txt       | 4 ++--\n Documentation/git-var.txt            | 2 +-\n Documentation/git-verify-pack.txt    | 2 +-\n builtin/bugreport.c                  | 2 +-\n builtin/commit-graph.c               | 2 +-\n builtin/diagnose.c                   | 2 +-\n builtin/sparse-checkout.c            | 2 +-\n 15 files changed, 18 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex bf1febb9ae7..591e3801b7b 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex 58670ef12f7..472b5bb995b 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]\n \t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b01ba3d3565 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n+'git merge-base' [-a | --all] <commit> <commit>...\n+'git merge-base' [-a | --all] --octopus <commit>...\n 'git merge-base' --is-ancestor <commit> <commit>\n 'git merge-base' --independent <commit>...\n 'git merge-base' --fork-point <ref> [<commit>]\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e52..dda80a740c8 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 9fed59a3172..844d6f808a0 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n SYNOPSIS\n --------\n [verse]\n-'git prune-packed' [-n|--dry-run] [-q|--quiet]\n+'git prune-packed' [-n | --dry-run] [-q | --quiet]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4b613d4140c..9d0e6f53e7e 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex be41f119740..e0c71623432 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n-\t\t[--[no-]signed|--signed=(true|false|if-asked)]\n+\t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\n \n DESCRIPTION\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex e5ec6b467f9..71f608b1ff1 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits\n SYNOPSIS\n --------\n [verse]\n-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n \t\t[(<rev> | <glob>)...]\n-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ab4d271925d..d1d56f68b43 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository\n SYNOPSIS\n --------\n [verse]\n-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]\n-\t     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]\n+\t     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n \t     [--heads] [--] [<pattern>...]\n 'git show-ref' --exclude-existing[=<pattern>]\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex 387cc1b9142..6aa521fab23 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -9,7 +9,7 @@ git-var - Show a Git logical variable\n SYNOPSIS\n --------\n [verse]\n-'git var' ( -l | <variable> )\n+'git var' (-l | <variable>)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c20..b8720dce8ab 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files\n SYNOPSIS\n --------\n [verse]\n-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n \n \n DESCRIPTION\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex bb138161943..61d93383f51 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex cd346f95f08..13cbb75ca28 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -14,7 +14,7 @@\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n \tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n-\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 474de9ec647..d52015c67a4 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 287716db68e..aac0f708e42 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init|list|set|add|reapply|disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463989","messageId":"patch-v3-16.36-db850539d2a-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 16/36] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:39Z","receivedAt":"2022-09-30T18:10:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"It's arguably more correct to say \"[<option>...]\" than either of these\nforms, but the vast majority of our documentation uses the\n\"[<options>]\" form to indicate an arbitrary number of options, let's\ndo the same in these cases, which were the odd ones out.\n\nIn the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\nto indicate that these are optional.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-mv.txt     | 2 +-\n Documentation/git-status.txt | 2 +-\n builtin/pack-objects.c       | 4 ++--\n builtin/sparse-checkout.c    | 2 +-\n 4 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 79449bf98fe..972a055fbd8 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' <options>... <args>...\n+'git mv' [<options>] <args>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 54a4b29b473..5e438a7fdc1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -9,7 +9,7 @@ git-status - Show the working tree status\n SYNOPSIS\n --------\n [verse]\n-'git status' [<options>...] [--] [<pathspec>...]\n+'git status' [<options>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3658c05cafc..573d0b20b76 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,\n #define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)\n \n static const char *pack_usage[] = {\n-\tN_(\"git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]\"),\n-\tN_(\"git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex aac0f708e42..58a22503f04 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463990","messageId":"patch-v3-17.36-041aa64f3c7-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 17/36] t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:40Z","receivedAt":"2022-09-30T18:10:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"As in a preceding commit use \"<options>\", not \"<options>...\", in this\ncase there is no *.txt version, but let's fix this one too while we're\nat it.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/helper/test-proc-receive.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\nindex cc08506cf0b..a4b305f4947 100644\n--- a/t/helper/test-proc-receive.c\n+++ b/t/helper/test-proc-receive.c\n@@ -6,7 +6,7 @@\n #include \"test-tool.h\"\n \n static const char *proc_receive_usage[] = {\n-\t\"test-tool proc-receive [<options>...]\",\n+\t\"test-tool proc-receive [<options>]\",\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463991","messageId":"patch-v3-18.36-3a439c4401d-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:41Z","receivedAt":"2022-09-30T18:10:35Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various inconsistencies between command SYNOPSIS and the\ncorresponding -h output where our translatable labels didn't match\nup.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt                    | 6 +++---\n Documentation/git-credential-cache--daemon.txt | 2 +-\n Documentation/git-mv.txt                       | 2 +-\n Documentation/git-receive-pack.txt             | 2 +-\n Documentation/git-tag.txt                      | 2 +-\n Documentation/git-upload-archive.txt           | 4 ++--\n builtin/bugreport.c                            | 2 +-\n builtin/clean.c                                | 2 +-\n builtin/commit-graph.c                         | 4 ++--\n builtin/credential-cache--daemon.c             | 2 +-\n builtin/for-each-repo.c                        | 2 +-\n builtin/pack-redundant.c                       | 2 +-\n builtin/rerere.c                               | 2 +-\n builtin/rev-list.c                             | 2 +-\n builtin/stash.c                                | 2 +-\n builtin/unpack-file.c                          | 2 +-\n builtin/upload-archive.c                       | 2 +-\n builtin/verify-pack.c                          | 2 +-\n builtin/worktree.c                             | 2 +-\n 19 files changed, 23 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 91742633fa8..3f16f200d9a 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\n-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n \n DESCRIPTION\n -----------\n@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n \n-If any optional `<path>...` arguments are given, only those paths\n+If any optional `<pathspec>...` arguments are given, only those paths\n are affected.\n \n OPTIONS\n -------\n -d::\n-\tNormally, when no <path> is specified, git clean will not\n+\tNormally, when no <pathspec> is specified, git clean will not\n \trecurse into untracked directories to avoid removing too much.\n \tSpecify -d to have it recurse into such directories as well.\n \tIf any paths are specified, -d is irrelevant; all untracked\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 01e1c214dd8..74832d06806 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 972a055fbd8..c612a5fd5b9 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [<options>] <args>...\n+'git mv' [<options>] <source>... <destination>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 014a78409b9..eec1268b10f 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31a97a1b6c5..c15ec895720 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n \t<tagname> [<commit> | <object>]\n 'git tag' -d <tagname>...\n 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex fba0f1c1b27..e8eb10baad7 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n SYNOPSIS\n --------\n [verse]\n-'git upload-archive' <directory>\n+'git upload-archive' <repository>\n \n DESCRIPTION\n -----------\n@@ -54,7 +54,7 @@ access via non-smart-http.\n \n OPTIONS\n -------\n-<directory>::\n+<repository>::\n \tThe repository to get a tar archive from.\n \n GIT\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 61d93383f51..96052541cbf 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 5466636e666..6f039f555b2 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 13cbb75ca28..e8f77f535f3 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -10,10 +10,10 @@\n #include \"tag.h\"\n \n #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n-\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n+\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n \t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex 4c6c89ab0de..ca672a6a619 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex fd86e5a8619..c6379b783c8 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <command-args>\"),\n+\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c\nindex ed9b9013a5f..ecd49ca268f 100644\n--- a/builtin/pack-redundant.c\n+++ b/builtin/pack-redundant.c\n@@ -14,7 +14,7 @@\n #define BLKSIZE 512\n \n static const char pack_redundant_usage[] =\n-\"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)\";\n+\"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\";\n \n static int load_all_packs, verbose, alt_odb;\n \ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 83d7a778e37..12570537d37 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <path>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n \tNULL,\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex f67e2b33555..ada68a4af5e 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex d91cf5fd3e1..83c9591ea6d 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -22,7 +22,7 @@\n #define INCLUDE_ALL_FILES 2\n \n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tN_(\"git stash list [<log-options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n \tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\ndiff --git a/builtin/unpack-file.c b/builtin/unpack-file.c\nindex 58652229f27..9e8119dd354 100644\n--- a/builtin/unpack-file.c\n+++ b/builtin/unpack-file.c\n@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)\n \tstruct object_id oid;\n \n \tif (argc != 2 || !strcmp(argv[1], \"-h\"))\n-\t\tusage(\"git unpack-file <sha1>\");\n+\t\tusage(\"git unpack-file <blob>\");\n \tif (get_oid(argv[1], &oid))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n \ndiff --git a/builtin/upload-archive.c b/builtin/upload-archive.c\nindex 98d028dae67..945ee2b4126 100644\n--- a/builtin/upload-archive.c\n+++ b/builtin/upload-archive.c\n@@ -10,7 +10,7 @@\n #include \"strvec.h\"\n \n static const char upload_archive_usage[] =\n-\t\"git upload-archive <repo>\";\n+\t\"git upload-archive <repository>\";\n \n static const char deadchild[] =\n \"git upload-archive: archiver died with error\";\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex 05c52135946..db9ac5c4606 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n \tNULL\n };\n \ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex c6710b25520..5bfc18e5a24 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {\n \tN_(\"git worktree prune [<options>]\"),\n \tN_(\"git worktree remove [<options>] <worktree>\"),\n \tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <path>\"),\n+\tN_(\"git worktree unlock <worktree>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463992","messageId":"patch-v3-19.36-3bfdd3fb79e-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 19/36] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:42Z","receivedAt":"2022-09-30T18:10:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add the \"[--]\" for those cases where the *.txt and -h were\ninconsistent, or where we incorrectly stated in one but not the other\nthat the \"--\" was mandatory.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/for-each-repo.c | 2 +-\n builtin/rev-list.c      | 2 +-\n builtin/verify-pack.c   | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex c6379b783c8..d45d873f579 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n+\tN_(\"git for-each-repo --config=<config> [--] <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex ada68a4af5e..3cc8aad52ed 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex db9ac5c4606..27d6f75fd8a 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463993","messageId":"patch-v3-20.36-98bdd0353cf-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 20/36] doc txt & -h consistency: make output order consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:43Z","receivedAt":"2022-09-30T18:11:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix cases where the SYNOPSIS and -h output was presented in a\ndifferent order.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/merge-base.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex a11f8c6e4bb..6f3941f2a49 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n static const char * const merge_base_usage[] = {\n \tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n \tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n+\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463994","messageId":"patch-v3-22.36-702eb747c0f-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:45Z","receivedAt":"2022-09-30T18:11:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\nthe order that they're discussed in the \"COMMANDS\" section of the\ndocumentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rerere.txt | 2 +-\n builtin/rerere.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 9d0e6f53e7e..992b469270c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 12570537d37..8b7392d5b44 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n \tNULL,\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463995","messageId":"patch-v3-23.36-01e20b8e452-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 23/36] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:46Z","receivedAt":"2022-09-30T18:11:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The C version was right to use \"()\" in place of \"[]\", let's update\nthe *.txt version accordingly, and furthermore list the *.c options in\nthe same order as the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-read-tree.txt | 2 +-\n builtin/read-tree.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex b9bfdc0a319..7567955bad8 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n SYNOPSIS\n --------\n [verse]\n-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex b3a389e1b1f..f4cbe460b97 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n \n static const char * const read_tree_usage[] = {\n \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n-\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463996","messageId":"patch-v3-21.36-1713227d497-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 21/36] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:44Z","receivedAt":"2022-09-30T18:11:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various issues of SYNOPSIS and -h output syntax where:\n\n * Options such as --force were missing entirely\n * ...or the short option, such as -f\n\n * We said \"opts\" or \"options\", but could instead enumerate\n   the (small) set of supported options\n\n * argument labels were missing entirely (ls-remote)\n\n * How we referred to an argument was inconsistent between the two,\n   e.g. <pack> v.s. <pack>.idx.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-send-pack.txt          |  3 ++-\n Documentation/git-sparse-checkout.txt    |  2 +-\n Documentation/git-update-server-info.txt |  8 +++++++-\n Documentation/git-verify-commit.txt      |  2 +-\n Documentation/git-verify-tag.txt         |  2 +-\n builtin/credential-cache--daemon.c       |  2 +-\n builtin/describe.c                       |  5 +++--\n builtin/diff-index.c                     |  2 +-\n builtin/ls-remote.c                      |  2 +-\n builtin/pack-refs.c                      |  2 +-\n builtin/revert.c                         |  9 +++++----\n builtin/send-pack.c                      |  1 +\n builtin/symbolic-ref.c                   |  5 +++--\n builtin/tag.c                            | 10 ++++++----\n builtin/update-server-info.c             |  2 +-\n builtin/upload-pack.c                    |  3 ++-\n help.c                                   |  2 +-\n 17 files changed, 38 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex e0c71623432..595b002152f 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n+'git send-pack' [--mirror] [--dry-run] [--force]\n+\t\t[--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n \t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 872436d7426..68392d2a56e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout' <subcommand> [<options>]\n+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\nindex 969bb2e15f1..4e6bf44427f 100644\n--- a/Documentation/git-update-server-info.txt\n+++ b/Documentation/git-update-server-info.txt\n@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n SYNOPSIS\n --------\n [verse]\n-'git update-server-info'\n+'git update-server-info' [-f | --force]\n \n DESCRIPTION\n -----------\n@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n what references and packs the server has.  This command\n generates such auxiliary files.\n \n+OPTIONS\n+-------\n+-f::\n+--force::\n+\tAllow adding otherwise ignored files.\n+\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\nindex 92097f6673d..96d10cfdffe 100644\n--- a/Documentation/git-verify-commit.txt\n+++ b/Documentation/git-verify-commit.txt\n@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n SYNOPSIS\n --------\n [verse]\n-'git verify-commit' <commit>...\n+'git verify-commit' [-v | --verbose] <commit>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\nindex 0b8075dad96..a454df2711e 100644\n--- a/Documentation/git-verify-tag.txt\n+++ b/Documentation/git-verify-tag.txt\n@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n SYNOPSIS\n --------\n [verse]\n-'git verify-tag' [--format=<format>] <tag>...\n+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex ca672a6a619..d4eb0097d24 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n+\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex e17c4b4c69b..23e3f05fb10 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -23,8 +23,9 @@\n define_commit_slab(commit_names, struct commit_name *);\n \n static const char * const describe_usage[] = {\n-\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n-\tN_(\"git describe [<options>] --dirty\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n+\tN_(\"git describe <blob>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex e667cf52e7d..aea139b9d8f 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -9,7 +9,7 @@\n #include \"submodule.h\"\n \n static const char diff_cache_usage[] =\n-\"git diff-index [-m] [--cached] \"\n+\"git diff-index [-m] [--cached] [--merge-base] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n \"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex df44e5cc0d1..5d5ac038716 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -7,7 +7,7 @@\n \n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n-\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n+\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n \t   \"              [--symref] [<repository> [<refs>...]]\"),\n \tNULL\n };\ndiff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\nindex cfbd5c36c76..27c2ca06acb 100644\n--- a/builtin/pack-refs.c\n+++ b/builtin/pack-refs.c\n@@ -5,7 +5,7 @@\n #include \"repository.h\"\n \n static char const * const pack_refs_usage[] = {\n-\tN_(\"git pack-refs [<options>]\"),\n+\tN_(\"git pack-refs [--all] [--no-prune]\"),\n \tNULL\n };\n \ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex ee2a0807f01..ee32c714a76 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -21,14 +21,15 @@\n  */\n \n static const char * const revert_usage[] = {\n-\tN_(\"git revert [<options>] <commit-ish>...\"),\n-\tN_(\"git revert <subcommand>\"),\n+\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n-\tN_(\"git cherry-pick <subcommand>\"),\n+\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n+\t   \"                [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \ndiff --git a/builtin/send-pack.c b/builtin/send-pack.c\nindex 64962be0168..4c5d125fa0a 100644\n--- a/builtin/send-pack.c\n+++ b/builtin/send-pack.c\n@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n+\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n \tNULL,\n };\ndiff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\nindex 1b0f10225f0..50b6df78df0 100644\n--- a/builtin/symbolic-ref.c\n+++ b/builtin/symbolic-ref.c\n@@ -5,8 +5,9 @@\n #include \"parse-options.h\"\n \n static const char * const git_symbolic_ref_usage[] = {\n-\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n-\tN_(\"git symbolic-ref -d [-q] <name>\"),\n+\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n+\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n+\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n \tNULL\n };\n \ndiff --git a/builtin/tag.c b/builtin/tag.c\nindex 75dece0e4f1..d428c45dc8d 100644\n--- a/builtin/tag.c\n+++ b/builtin/tag.c\n@@ -23,11 +23,13 @@\n #include \"date.h\"\n \n static const char * const git_tag_usage[] = {\n-\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n-\t   \"        <tagname> [<head>]\"),\n+\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n+\t   \"        <tagname> [<commit> | <object>]\"),\n \tN_(\"git tag -d <tagname>...\"),\n-\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n-\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n+\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n+\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n+\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n+\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n \tNULL\n };\ndiff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\nindex 880fffec587..d2239c9ef4d 100644\n--- a/builtin/update-server-info.c\n+++ b/builtin/update-server-info.c\n@@ -4,7 +4,7 @@\n #include \"parse-options.h\"\n \n static const char * const update_server_info_usage[] = {\n-\t\"git update-server-info [--force]\",\n+\t\"git update-server-info [-f | --force]\",\n \tNULL\n };\n \ndiff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\nindex 125af53885f..25b69da2bf2 100644\n--- a/builtin/upload-pack.c\n+++ b/builtin/upload-pack.c\n@@ -8,7 +8,8 @@\n #include \"serve.h\"\n \n static const char * const upload_pack_usage[] = {\n-\tN_(\"git upload-pack [<options>] <dir>\"),\n+\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n+\t   \"                [--advertise-refs] <directory>\"),\n \tNULL\n };\n \ndiff --git a/help.c b/help.c\nindex d04542d8261..f1e090a4428 100644\n--- a/help.c\n+++ b/help.c\n@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \tstruct strbuf buf = STRBUF_INIT;\n \tint build_options = 0;\n \tconst char * const usage[] = {\n-\t\tN_(\"git version [<options>]\"),\n+\t\tN_(\"git version [--build-options]\"),\n \t\tNULL\n \t};\n \tstruct option options[] = {\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463997","messageId":"patch-v3-25.36-ab109f73264-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 25/36] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:48Z","receivedAt":"2022-09-30T18:11:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\nreceive-pack\" and \"git credential-cache--daemon\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-receive-pack.txt | 2 +-\n builtin/credential-cache--daemon.c | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex eec1268b10f..92452334ac4 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <git-dir>\n+'git receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex d4eb0097d24..f3c89831d4a 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\n@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n {\n \tconst char * const usage[] = {\n-\t\t\"git credential-cache--daemon [options] <action>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\t\"\",\n \t\t\"credential-cache--daemon is disabled in this build of Git\",\n \t\tNULL\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463998","messageId":"patch-v3-24.36-7f93da79fee-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 24/36] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:47Z","receivedAt":"2022-09-30T18:11:35Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend the -h output to match that of the *.txt output, the differences\nwere fairly small. In the case of \"[<options>]\" we only have a few of\nthem, so let's exhaustively list them as in the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 1b08700bf9e..544c78a5f3a 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,13 +12,14 @@\n  */\n \n #define BUILTIN_BUNDLE_CREATE_USAGE \\\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n+\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n-\tN_(\"git bundle verify [<options>] <file>\")\n+\tN_(\"git bundle verify [-q | --quiet] <file>\")\n #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n \tN_(\"git bundle list-heads <file> [<refname>...]\")\n #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n-\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n \n static char const * const builtin_bundle_usage[] = {\n \tBUILTIN_BUNDLE_CREATE_USAGE,\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"463999","messageId":"patch-v3-26.36-d57635b2707-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 26/36] doc txt & -h consistency: add missing options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:49Z","receivedAt":"2022-09-30T18:11:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change those built-in commands that were attempting to exhaustively\nlist the options in the \"-h\" output to actually do so, and always\nhave *.txt documentation know about the exhaustive list of options.\n\nLet's also fix the documentation and -h output for those built-in\ncommands where the *.txt and -h output was a mismatch of missing\noptions on both sides.\n\nIn the case of \"interpret-trailers\" fixing the missing options reveals\nthat the *.txt version was implicitly claiming that the command had\ntwo operating modes, which a look at the -h version (and studying the\ndocumentation) will show is not the case.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-commit-graph.txt       | 5 ++++-\n Documentation/git-interpret-trailers.txt | 5 +++--\n builtin/commit-tree.c                    | 1 +\n builtin/fsck.c                           | 5 ++++-\n builtin/hash-object.c                    | 4 ++--\n builtin/init-db.c                        | 2 ++\n builtin/interpret-trailers.c             | 2 +-\n builtin/rm.c                             | 4 +++-\n 8 files changed, 20 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 36fe56c2c71..c8dbceba014 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -10,7 +10,10 @@ SYNOPSIS\n --------\n [verse]\n 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n+'git commit-graph write' [--object-dir <dir>] [--append]\n+\t\t\t[--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n+\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n+\t\t\t<split options>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 6d6197cd0a4..22ff3a603e0 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [<options>] [--parse] [<file>...]\n+'git interpret-trailers' [--in-place] [--trim-empty]\n+\t\t\t[(--trailer <token>[(=|:)<value>])...]\n+\t\t\t[--parse] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex e4b85d29d56..cc8d584be2f 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,6 +15,7 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n+\tN_(\"git commit-tree <tree> [(-p <parent>)...]\"),\n \tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n \t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\ndiff --git a/builtin/fsck.c b/builtin/fsck.c\nindex f7916f06ed5..ef273321d0b 100644\n--- a/builtin/fsck.c\n+++ b/builtin/fsck.c\n@@ -821,7 +821,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,\n }\n \n static char const * const fsck_usage[] = {\n-\tN_(\"git fsck [<options>] [<object>...]\"),\n+\tN_(\"git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\\n\"\n+\t   \"         [--[no-]full] [--strict] [--verbose] [--lost-found]\\n\"\n+\t   \"         [--[no-]dangling] [--[no-]progress] [--connectivity-only]\\n\"\n+\t   \"         [--[no-]name-objects] [<object>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex f7c16802f0c..b5063815020 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n \t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n-\t\t   \"                [--stdin] [--] <file>...\"),\n-\t\t\"git hash-object  --stdin-paths\",\n+\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n \t\tNULL\n \t};\n \tconst char *type = blob_type;\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 08ba006d55e..dcaaf102eaf 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n \n static const char *const init_db_usage[] = {\n \tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--separate-git-dir <git-dir>] [--object-format=<format>]\\n\"\n+\t   \"         [-b <branch-name> | --initial-branch=<branch-name>]\\n\"\n \t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 4cf0cf265dc..e58627c72a9 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -15,7 +15,7 @@\n static const char * const git_interpret_trailers_usage[] = {\n \tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n \t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n-\t   \"                       [<file>...]\"),\n+\t   \"                       [--parse] [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex b6ba859fe42..f0d025a4e23 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -17,7 +17,9 @@\n #include \"pathspec.h\"\n \n static const char * const builtin_rm_usage[] = {\n-\tN_(\"git rm [<options>] [--] <file>...\"),\n+\tN_(\"git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\\n\"\n+\t   \"       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"       [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464000","messageId":"patch-v3-27.36-ac959d0cfc1-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 27/36] doc txt & -h consistency: make \"stash\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:50Z","receivedAt":"2022-09-30T18:11:54Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend both the -h output and *.txt to match one another. In this case\nthe *.txt didn't list the \"save\" subcommand, and the \"-h\" was\nsimilarly missing some commands.\n\nLet's also convert the *.c code to use a macro definition, similar to\nthat used in preceding commits. This avoids duplication.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt |  5 ++-\n builtin/stash.c             | 73 ++++++++++++++++++++++++-------------\n 2 files changed, 52 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex ea16d2eae7c..f4bb6114d91 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,12 +11,15 @@ SYNOPSIS\n 'git stash' list [<log-options>]\n 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n 'git stash' drop [-q | --quiet] [<stash>]\n-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n+'git stash' pop [--index] [-q | --quiet] [<stash>]\n+'git stash' apply [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [<message>]\n 'git stash' clear\n 'git stash' create [<message>]\n 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 83c9591ea6d..bb5485b4095 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -21,72 +21,95 @@\n \n #define INCLUDE_ALL_FILES 2\n \n+#define BUILTIN_STASH_LIST_USAGE \\\n+\tN_(\"git stash list [<log-options>]\")\n+#define BUILTIN_STASH_SHOW_USAGE \\\n+\tN_(\"git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\")\n+#define BUILTIN_STASH_DROP_USAGE \\\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_POP_USAGE \\\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_APPLY_USAGE \\\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_BRANCH_USAGE \\\n+\tN_(\"git stash branch <branchname> [<stash>]\")\n+#define BUILTIN_STASH_STORE_USAGE \\\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\")\n+#define BUILTIN_STASH_PUSH_USAGE \\\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\" \\\n+\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\" \\\n+\t   \"          [--] [<pathspec>...]]\")\n+#define BUILTIN_STASH_SAVE_USAGE \\\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\")\n+#define BUILTIN_STASH_CREATE_USAGE \\\n+\tN_(\"git stash create [<message>]\")\n+#define BUILTIN_STASH_CLEAR_USAGE \\\n+\t\"git stash clear\"\n+\n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<log-options>]\"),\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n-\t\"git stash clear\",\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n+\tBUILTIN_STASH_SHOW_USAGE,\n+\tBUILTIN_STASH_DROP_USAGE,\n+\tBUILTIN_STASH_POP_USAGE,\n+\tBUILTIN_STASH_APPLY_USAGE,\n+\tBUILTIN_STASH_BRANCH_USAGE,\n+\tBUILTIN_STASH_PUSH_USAGE,\n+\tBUILTIN_STASH_SAVE_USAGE,\n+\tBUILTIN_STASH_CLEAR_USAGE,\n+\tBUILTIN_STASH_CREATE_USAGE,\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_list_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_show_usage[] = {\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n+\tBUILTIN_STASH_SHOW_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_DROP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_POP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_APPLY_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_branch_usage[] = {\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_clear_usage[] = {\n-\t\"git stash clear\",\n+\tBUILTIN_STASH_CLEAR_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n+\tBUILTIN_STASH_PUSH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_SAVE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464001","messageId":"patch-v3-28.36-f617375ea9e-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 28/36] doc txt & -h consistency: make \"annotate\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:51Z","receivedAt":"2022-09-30T18:11:57Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cmd_blame() already detected whether it was processing \"blame\" or\n\"annotate\", but it didn't adjust its usage output accordingly. Let's\ndo that.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-annotate.txt |  2 +-\n builtin/blame.c                | 21 +++++++++++++++------\n 2 files changed, 16 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex e44a831339d..5ae8aabe0f8 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [<options>] <file> [<revision>]\n+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex 8ec59fa2096..be9e091a86b 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -30,6 +30,7 @@\n #include \"tag.h\"\n \n static char blame_usage[] = N_(\"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n+static char annotate_usage[] = N_(\"git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n \n static const char *blame_opt_usage[] = {\n \tblame_usage,\n@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {\n \tNULL\n };\n \n+static const char *annotate_opt_usage[] = {\n+\tannotate_usage,\n+\t\"\",\n+\tN_(\"<rev-opts> are documented in git-rev-list(1)\"),\n+\tNULL\n+};\n+\n static int longest_file;\n static int longest_author;\n static int max_orig_digits;\n@@ -899,6 +907,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tlong anchor;\n \tconst int hexsz = the_hash_algo->hexsz;\n \tlong num_lines = 0;\n+\tconst char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n \n \tsetup_default_color_by_age();\n \tgit_config(git_blame_config, &output_option);\n@@ -914,7 +923,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tparse_options_start(&ctx, argc, argv, prefix, options,\n \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n \tfor (;;) {\n-\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n+\t\tswitch (parse_options_step(&ctx, options, usage)) {\n \t\tcase PARSE_OPT_NON_OPTION:\n \t\tcase PARSE_OPT_UNKNOWN:\n \t\t\tbreak;\n@@ -934,7 +943,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\tctx.argv[0] = \"--children\";\n \t\t\treverse = 1;\n \t\t}\n-\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n+\t\tparse_revision_opt(&revs, &ctx, options, usage);\n \t}\n parse_done:\n \trevision_opts_finish(&revs);\n@@ -1040,7 +1049,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\tswitch (argc - dashdash_pos - 1) {\n \t\tcase 2: /* (1b) */\n \t\t\tif (argc != 4)\n-\t\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\t\tusage_with_options(usage, options);\n \t\t\t/* reorder for the new way: <rev> -- <path> */\n \t\t\targv[1] = argv[3];\n \t\t\targv[3] = argv[2];\n@@ -1051,11 +1060,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\targv[argc] = NULL;\n \t\t\tbreak;\n \t\tdefault:\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\t}\n \t} else {\n \t\tif (argc < 2)\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(usage, options);\n \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n \t\t\tpath = add_prefix(prefix, argv[1]);\n \t\t\targv[1] = argv[2];\n@@ -1114,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n \t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n-\t\t\t\t       blame_opt_usage, options, arg);\n+\t\t\t\t       usage, options, arg);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464002","messageId":"patch-v3-29.36-c96c3fc6d8d-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 29/36] doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:52Z","receivedAt":"2022-09-30T18:12:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Correct uses of \"<label>...\" where we really meant to say\n\"[<label>...]\", i.e. the command in question taken an optional set of\n\"<label>\". As the CodingGuidelines notes \"[o]ptional parts [should be]\nenclosed in square brackets\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt | 2 +-\n builtin/clean.c             | 2 +-\n builtin/commit.c            | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 3f16f200d9a..db996a15e23 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\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>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 6f039f555b2..40ff2c578de 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex fcf9c85947e..21ad4ccbf87 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {\n };\n \n static const char * const builtin_status_usage[] = {\n-\tN_(\"git status [<options>] [--] <pathspec>...\"),\n+\tN_(\"git status [<options>] [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464003","messageId":"patch-v3-30.36-34b778dd176-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 30/36] doc txt & -h consistency: make \"diff-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:53Z","receivedAt":"2022-09-30T18:12:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"diff-tree -h\" output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-tree.c | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 23f58702fa0..85e8c81e594 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)\n }\n \n static const char diff_tree_usage[] =\n-\"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\\n\"\n+\"              [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\\n\"\n+\"              [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n \"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464004","messageId":"patch-v3-31.36-336fc749f1c-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 31/36] doc txt & -h consistency: make \"commit\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:54Z","receivedAt":"2022-09-30T18:12:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"-h\" output of \"git commit\" consistent with the *.txt version\nby exhaustively listing the options that it takes.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/commit.c | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex 21ad4ccbf87..64f420bcbf6 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -40,7 +40,14 @@\n #include \"pretty.h\"\n \n static const char * const builtin_commit_usage[] = {\n-\tN_(\"git commit [<options>] [--] <pathspec>...\"),\n+\tN_(\"git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\\n\"\n+\t   \"           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\\n\"\n+\t   \"           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\\n\"\n+\t   \"           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\\n\"\n+\t   \"           [--date=<date>] [--cleanup=<mode>] [--[no-]status]\\n\"\n+\t   \"           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\\n\"\n+\t   \"           [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464005","messageId":"patch-v3-32.36-81024d1c3cd-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 32/36] reflog doc: list real subcommands up-front","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:55Z","receivedAt":"2022-09-30T18:12:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"git reflog\" documentation to exhaustively list the\nsubcommands it accepts in the SYNOPSIS, as opposed to leaving that for\na \"[verse]\" in the DESCRIPTION section. This documentation style was\nadded in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how\nother commands which take subcommands are documented.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 15 ++++++---------\n 1 file changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 0537d4645be..ec64cbff4c6 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -8,14 +8,6 @@ git-reflog - Manage reflog information\n \n SYNOPSIS\n --------\n-[verse]\n-'git reflog' <subcommand> <options>\n-\n-DESCRIPTION\n------------\n-The command takes various subcommands, and different options\n-depending on the subcommand:\n-\n [verse]\n 'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n@@ -25,6 +17,10 @@ depending on the subcommand:\n \t[--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n 'git reflog exists' <ref>\n \n+DESCRIPTION\n+-----------\n+This command manages the information recorded in the reflogs.\n+\n Reference logs, or \"reflogs\", record when the tips of branches and\n other references were updated in the local repository. Reflogs are\n useful in various Git commands, to specify the old value of a\n@@ -33,7 +29,8 @@ moves ago\", `master@{one.week.ago}` means \"where master used to point\n to one week ago in this local repository\", and so on. See\n linkgit:gitrevisions[7] for more details.\n \n-This command manages the information recorded in the reflogs.\n+The command takes various subcommands, and different options\n+depending on the subcommand:\n \n The \"show\" subcommand (which is also the default, in the absence of\n any subcommands) shows the log of the reference provided in the\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464006","messageId":"patch-v3-33.36-76e6b7d296a-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 33/36] worktree: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:56Z","receivedAt":"2022-09-30T18:12:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git worktree\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------\n 1 file changed, 84 insertions(+), 25 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 5bfc18e5a24..ba6846c3788 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -15,15 +15,72 @@\n #include \"worktree.h\"\n #include \"quote.h\"\n \n-static const char * const worktree_usage[] = {\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\"),\n-\tN_(\"git worktree list [<options>]\"),\n-\tN_(\"git worktree lock [<options>] <path>\"),\n-\tN_(\"git worktree move <worktree> <new-path>\"),\n-\tN_(\"git worktree prune [<options>]\"),\n-\tN_(\"git worktree remove [<options>] <worktree>\"),\n-\tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <worktree>\"),\n+#define BUILTIN_WORKTREE_ADD_USAGE \\\n+\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+#define BUILTIN_WORKTREE_LIST_USAGE \\\n+\tN_(\"git worktree list [<options>]\")\n+#define BUILTIN_WORKTREE_LOCK_USAGE \\\n+\tN_(\"git worktree lock [<options>] <path>\")\n+#define BUILTIN_WORKTREE_MOVE_USAGE \\\n+\tN_(\"git worktree move <worktree> <new-path>\")\n+#define BUILTIN_WORKTREE_PRUNE_USAGE \\\n+\tN_(\"git worktree prune [<options>]\")\n+#define BUILTIN_WORKTREE_REMOVE_USAGE \\\n+\tN_(\"git worktree remove [<options>] <worktree>\")\n+#define BUILTIN_WORKTREE_REPAIR_USAGE \\\n+\tN_(\"git worktree repair [<path>...]\")\n+#define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n+\tN_(\"git worktree unlock <worktree>\")\n+\n+static const char * const git_worktree_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_add_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tNULL,\n+};\n+\n+static const char * const git_worktree_list_usage[] = {\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_lock_usage[] = {\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_move_usage[] = {\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_prune_usage[] = {\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_remove_usage[] = {\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_repair_usage[] = {\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_unlock_usage[] = {\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n \tNULL\n };\n \n@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,\n+\t\t\t   0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_prune_usage, options);\n \tprune_worktrees();\n \treturn 0;\n }\n@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)\n \n \tmemset(&opts, 0, sizeof(opts));\n \topts.checkout = 1;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);\n \tif (!!opts.detach + !!new_branch + !!new_branch_force > 1)\n \t\tdie(_(\"options '%s', '%s', and '%s' cannot be used together\"), \"-b\", \"-B\", \"--detach\");\n \tif (lock_reason && !keep_locked)\n@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\topts.keep_locked = _(\"added with --lock\");\n \n \tif (ac < 1 || ac > 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_add_usage, options);\n \n \tpath = prefix_filename(prefix, av[0]);\n \tbranch = ac < 2 ? \"HEAD\" : av[1];\n@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_list_usage, options);\n \telse if (verbose && porcelain)\n \t\tdie(_(\"options '%s' and '%s' cannot be used together\"), \"--verbose\", \"--porcelain\");\n \telse if (!line_terminator && !porcelain)\n@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)\n \t};\n \tstruct worktree **worktrees, *wt;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_lock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)\n \tstruct worktree **worktrees, *wt;\n \tint ret;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_unlock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tchar *path;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_move_usage,\n+\t\t\t   0);\n \tif (ac != 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_move_usage, options);\n \n \tpath = prefix_filename(prefix, av[1]);\n \tstrbuf_addstr(&dst, path);\n@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tint ret = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_remove_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)\n \t};\n \tint rc = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);\n \tp = ac > 0 ? av : self;\n \tfor (; *p; p++)\n \t\trepair_worktree_at_path(*p, report_repair, &rc);\n@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)\n \tif (!prefix)\n \t\tprefix = \"\";\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);\n \treturn fn(ac, av, prefix);\n }\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464007","messageId":"patch-v3-34.36-efd0c2c634d-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 34/36] doc txt & -h consistency: make \"worktree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:57Z","receivedAt":"2022-09-30T18:12:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"worktree\" -h output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex ba6846c3788..4a24d53be15 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -16,17 +16,18 @@\n #include \"quote.h\"\n \n #define BUILTIN_WORKTREE_ADD_USAGE \\\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+\tN_(\"git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\\n\" \\\n+\t   \"                 [-b <new-branch>] <path> [<commit-ish>]\")\n #define BUILTIN_WORKTREE_LIST_USAGE \\\n-\tN_(\"git worktree list [<options>]\")\n+\tN_(\"git worktree list [-v | --porcelain [-z]]\")\n #define BUILTIN_WORKTREE_LOCK_USAGE \\\n-\tN_(\"git worktree lock [<options>] <path>\")\n+\tN_(\"git worktree lock [--reason <string>] <worktree>\")\n #define BUILTIN_WORKTREE_MOVE_USAGE \\\n \tN_(\"git worktree move <worktree> <new-path>\")\n #define BUILTIN_WORKTREE_PRUNE_USAGE \\\n-\tN_(\"git worktree prune [<options>]\")\n+\tN_(\"git worktree prune [-n] [-v] [--expire <expire>]\")\n #define BUILTIN_WORKTREE_REMOVE_USAGE \\\n-\tN_(\"git worktree remove [<options>] <worktree>\")\n+\tN_(\"git worktree remove [-f] <worktree>\")\n #define BUILTIN_WORKTREE_REPAIR_USAGE \\\n \tN_(\"git worktree repair [<path>...]\")\n #define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464008","messageId":"patch-v3-35.36-22da68abce3-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:58Z","receivedAt":"2022-09-30T18:12:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's been a lot of incremental effort to make the SYNOPSIS output\nin our documentation consistent with the -h output,\ne.g. cbe485298bf (git reflog [expire|delete]: make -h output\nconsistent with SYNOPSIS, 2022-03-17) is one recent example, but that\neffort has been an uphill battle due to the lack of regression\ntesting.\n\nThis adds such regression testing, we can parse out the SYNOPSIS\noutput with \"sed\", and is turns out it's relatively easy to normalize\nit and the \"-h\" output to match on another.\n\nWe now ensure that we won't have regressions when it comes to the list\nof commands in \"expect_help_to_match_txt\" below, and in subsequent\ncommits we'll make more of them consistent.\n\nThe naïve parser here gets quite a few things wrong, but it doesn't\nneed to be perfect, just good enough that we can compare /some/ of\nthis help output. There's no cases where the output would match except\nfor the parser's stupidity, it's all cases of e.g. comparing the *.txt\nto non-parse_options() output.\n\nSince that output is wildly different than the *.txt anyway let's\nleave this for now, we can fix the parser some other time, or it won't\nbecome necessary as we'll e.g. convert more things to using\nparse_options().\n\nHaving a special-case for \"merge-tree\"'s 1f0c3a29da3 (merge-tree:\nimplement real merges, 2022-06-18) is a bit ugly, but preferred to\nblessing that \" (deprecated)\" pattern for other commands. We'd\nprobably want to add some other way of marking deprecated commands in\nthe SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is\nindistinguishable from the command taking an optional literal\n\"deprecated\" string as an argument.\n\nSome of the issues that are left:\n\n * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n   all showing \"git log\" and \"git show\" usage output. I.e. the\n   \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n   command we're running.\n\n * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n   of what command it's running. The same for \"annotate\" and \"blame\".\n\n * Commands which implement subcommands such as like\n   \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n   in a very different order in the *.txt and *.c. Fixing it would\n   require some verbose diffs, so it's been left alone for onw.\n\n * Commands such as \"format-patch\" have a very long argument list in\n   the *.txt, but just \"[<options>]\" in the *.c.\n\n   What to do about these has been left out of this series, except to\n   the extent that preceding commits changed \"[<options>]\" (or\n   equivalent) to the list of options in cases where that list of\n   options was tiny, or we clearly meant to exhaustively list the\n   options in both *.txt and *.c.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh  | 121 ++++++++++++++++++++++++++++++++++++\n t/t0450/txt-help-mismatches |  58 +++++++++++++++++\n 2 files changed, 179 insertions(+)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n create mode 100644 t/t0450/txt-help-mismatches\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..6a710b07408\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,121 @@\n+#!/bin/sh\n+\n+test_description='compare (unbuilt) Documentation/*.txt to -h output\n+\n+Run this with --debug to see a summary of where we still fail to make\n+the two versions consistent with one another.'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+test_expect_success 'list of txt and help mismatches is sorted' '\n+\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n+\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tBUG \"please keep the list of txt and help mismatches sorted\"\n+\tfi\n+'\n+\n+builtin_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\ttest_when_finished \"rm -f out\" &&\n+\ttest_expect_code 129 git $builtin -h >out 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp;\n+\t\t}' <out\n+}\n+\n+builtin_to_txt () {\n+\techo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n+}\n+\n+txt_synopsis () {\n+\tsed -n \\\n+\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\t/^\\[verse\\]$/d;\n+\t\t\ts/{litdd}/--/g;\n+\n+\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\tp;\n+\t\t}' \\\n+\t\t<\"$1\"\n+}\n+\n+HT=\"\t\"\n+align_after_nl () {\n+\tbuiltin=\"$1\" &&\n+\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n+\tpad=$(printf \"%${len}s\" \"\") &&\n+\n+\tsed \"s/^[ $HT][ $HT]*/$pad/\"\n+}\n+\n+test_debug '>failing'\n+while read builtin\n+do\n+\ttest_expect_success \"$builtin -h output has no \\t\" '\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\t\t! grep \"$HT\" help.raw\n+\t'\n+\n+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n+\n+\tif test -f \"$txt\"\n+\tthen\n+\t\ttest_set_prereq \"$preq\"\n+\tfi &&\n+\n+\tresult=\n+\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tresult=failure\n+\telse\n+\t\tresult=success\n+\tfi &&\n+\n+\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n+\t\ttxt_synopsis \"$txt\" >txt.raw &&\n+\t\tif test \"$builtin\" = \"merge-tree\"\n+\t\tthen\n+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <txt.raw >txt.raw.new &&\n+\t\t\tmv txt.raw.new txt.raw\n+\t\tfi &&\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\n+\t\t# The *.txt and -h use different spacing for the\n+\t\t# alignment of continued usage output, normalize it.\n+\t\talign_after_nl \"$builtin\" <txt.raw >txt &&\n+\t\talign_after_nl \"$builtin\" <help.raw >help &&\n+\t\ttest_cmp txt help\n+\t'\n+\n+\tif test_have_prereq \"$preq\" && test -e txt && test -e help\n+\tthen\n+\t\ttest_debug '\n+\t\t\tif test_cmp txt help >cmp 2>/dev/null\n+\t\t\tthen\n+\t\t\t\techo \"=== DONE: $builtin ===\"\n+\t\t\telse\n+\t\t\t\techo \"=== TODO: $builtin ===\" &&\n+\t\t\t\tcat cmp\n+\t\t\tfi >>failing\n+\t\t'\n+\n+\t\t# Not in test_expect_success in case --run is being\n+\t\t# used with --debug\n+\t\trm -f txt help tmp 2>/dev/null\n+\tfi\n+done <builtins\n+\n+test_debug 'say \"$(cat failing)\"'\n+\n+test_done\ndiff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches\nnew file mode 100644\nindex 00000000000..a0777acd667\n--- /dev/null\n+++ b/t/t0450/txt-help-mismatches\n@@ -0,0 +1,58 @@\n+add\n+am\n+apply\n+archive\n+bisect\n+blame\n+branch\n+check-ref-format\n+checkout\n+checkout-index\n+clone\n+column\n+config\n+credential\n+credential-cache\n+credential-store\n+fast-export\n+fast-import\n+fetch-pack\n+fmt-merge-msg\n+for-each-ref\n+format-patch\n+fsck-objects\n+fsmonitor--daemon\n+gc\n+grep\n+index-pack\n+init-db\n+log\n+ls-files\n+ls-tree\n+mailinfo\n+mailsplit\n+maintenance\n+merge\n+merge-file\n+merge-index\n+merge-one-file\n+multi-pack-index\n+name-rev\n+notes\n+pack-objects\n+push\n+range-diff\n+rebase\n+remote\n+remote-ext\n+remote-fd\n+repack\n+reset\n+restore\n+rev-parse\n+show\n+stage\n+switch\n+update-index\n+update-ref\n+whatchanged\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464009","messageId":"patch-v3-36.36-b56113dd620-20220930T180415Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 36/36] tests: assert consistent whitespace in -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-30T18:07:59Z","receivedAt":"2022-09-30T18:12:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test for the *.txt and *.c output assertions which asserts that\nfor \"-h\" lines that aren't the \"usage: \" or \" or: \" lines they start\nwith the same amount of whitespace. This ensures that we won't have\nbuggy output like:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n       [--create-reflog] [...]\n\nWhich should instead be like this instead, i.e. the options lines\nshould be aligned:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n               [--create-reflog] [...]\n\nIt would be better to be able to use \"test_cmp\" here, i.e. to\nconstruct the output we expect, and compare it against the actual\noutput.\n\nFor most built-in commands this would be rather straightforward. In\n\"t0450-txt-doc-vs-help.sh\" we already compute the whitespace that a\n\"git-$builtin\" needs, and strip away \"usage: \" or \" or: \" from the\nstart of lines. The problem is:\n\n * For commands that implement subcommands, such as \"git bundle\", we\n   don't know whether e.g. \"git bundle create\" is the subcommand\n   \"create\", or the argument \"create\" to \"bundle\" for the purposes of\n   alignment.\n\n   We *do* have that information from the *.txt version, since the\n   part within the ''-quotes should be the command & subcommand, but\n   that isn't consistent (e.g. see \"git bundle\" and \"git\n   commit-graph\", only the latter is correct), and parsing that out\n   would be non-trivial.\n\n * If we were to make this stricter we have various\n   non-parse_options() users (e.g. \"git diff-tree\") that don't have the\n   nicely aligned output which we've had since\n   4631cfc20bd (parse-options: properly align continued usage output,\n   2021-09-21).\n\nSo rather than make perfect the enemy of the good let's assert that\nfor those lines that are indented they should all use the same\nindentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 6a710b07408..adc81ec590b 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -66,6 +66,21 @@ do\n \t\t! grep \"$HT\" help.raw\n \t'\n \n+\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n+\t\tsed -n \\\n+\t\t\t-e \"/^ / {\n+\t\t\t\ts/[^ ].*//;\n+\t\t\t\tp;\n+\t\t\t}\" \\\n+\t\t\t<help.raw >help &&\n+\t\tsort -u help >help.ws &&\n+\t\tif test -s help.ws\n+\t\tthen\n+\t\t\ttest_line_count = 1 help.ws\n+\t\tfi\n+\t'\n+\n \ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n \tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464014","messageId":"xmqqv8p4a871.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-04.36-a8312c50f01-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:00:50Z","receivedAt":"2022-09-30T21:01:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Improve the error message emitted when there's a bad -L argument, and\n> do so using the parse-options.c flavor of \"usage()\", instead of using\n> the non-parse-options.c usage() function. This was the last user of\n> usage() in this file.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  builtin/blame.c | 7 ++++---\n>  1 file changed, 4 insertions(+), 3 deletions(-)\n\nThis may not be incorrect (I didn't spend time to see if this \"while\nat it\" is truly an improvement) but clearly outside the scome of\n\"output from the -h option should match synopsis\" theme.\n\n> diff --git a/builtin/blame.c b/builtin/blame.c\n> index a9fe8cf7a68..8ec59fa2096 100644\n> --- a/builtin/blame.c\n> +++ b/builtin/blame.c\n> @@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n>  \tanchor = 1;\n>  \trange_set_init(&ranges, range_list.nr);\n>  \tfor (range_i = 0; range_i < range_list.nr; ++range_i) {\n> +\t\tconst char *arg = range_list.items[range_i].string;\n>  \t\tlong bottom, top;\n> -\t\tif (parse_range_arg(range_list.items[range_i].string,\n> -\t\t\t\t    nth_line_cb, &sb, lno, anchor,\n> +\t\tif (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,\n>  \t\t\t\t    &bottom, &top, sb.path,\n>  \t\t\t\t    the_repository->index))\n> -\t\t\tusage(blame_usage);\n> +\t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n> +\t\t\t\t       blame_opt_usage, options, arg);\n\nSo, it used to be that it emitted only blame_usage which is a rough\nmatch to the synopsis, \n\n    \"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\"\n\nbut now we use blame_opt_usage + options, which means that the same\nblame_usage, a blank line, and \"<rev-opts> are documented in\ngit-rev-list(1)\" is given, followed by the list of full options. \n\nI do think saying \"failed to parse -L\" is an improvement, but it is\ndubious it is a good idea to follow it with a wall of text that\ncomes from options[].  After all, if the user chose to use \"-L 2,8\"\nand a typo replaced the comma with a full stop, which caused\nparse_range_arg() to fail, does it make sense to scroll away the\nmessage that helpfully points out that \"-L argument '2.8'\" was the\nproblem with other option descriptions?\n\nThis is why we shouldn't distract a series with \"while at it\"\nchanges that are outside the scope of the theme.  Letting the patch\nauthors and reviewers concentrate on doing one thing well would\navoid mistakes, but mixing unrelated changes distracts them.  Having\nto think about the differences between usage() and usage_msg_optf()\nwith this change already distracted me and stopped my review on this\nseries in this sitting.  The topic will need to wait for the next\ntime I decide to sit with it and start reading it from the next step.\n\nAnd of course, a series like this, which is supposed to do the same\nthing to many files for consistency, is better written and reviewed\nin one sitting, because that will make it easier in reviewers' mind\nto keep and apply the same review criteria consistently.\n\n>  \t\tif ((!lno && (top || bottom)) || lno < bottom)\n>  \t\t\tdie(Q_(\"file %s has only %lu line\",\n>  \t\t\t       \"file %s has only %lu lines\",\n"},{"id":"464015","messageId":"xmqqo7uwa86d.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-03.36-953a72abee1-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 03/36] bundle: define subcommand -h in terms of command -h","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:01:14Z","receivedAt":"2022-09-30T21:01:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Avoid repeating the \"-h\" output for the \"git bundle\" command, and\n> instead define the usage of each subcommand with macros, so that the\n> \"-h\" output for the command itself can re-use those definitions. See\n> [1], [2] and [3] for prior art using the same pattern.\n>\n> 1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n>    macro, 2021-03-30)\n> 2. 8757b35d443 (commit-graph: define common usage with a macro,\n>    2021-08-23)\n> 3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n>    2022-03-17)\n\nThis of course is an improvement, but makes me wonder if we need to\ndevice even more concise ways to simplify all these commands with\nsubcommands.  \n\nUnlike the simplest case like this one, where no subcommand take any\noption, a more general mechanism needs to allow some subcommands to\ntake their own options, so it will probably not an easy thing to do,\nand a more general one that allows us to write each string only once\nwould probably need its own \"mark-up\" language, so it would probably\nnot be a good direction to go.  So let's declare that the pattern\nused in the result of applying this patch is the optimal one and\nstop there.\n\nThanks.\n\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  builtin/bundle.c | 29 +++++++++++++++++++----------\n>  1 file changed, 19 insertions(+), 10 deletions(-)\n>\n> diff --git a/builtin/bundle.c b/builtin/bundle.c\n> index 5c78894afd5..1b08700bf9e 100644\n> --- a/builtin/bundle.c\n> +++ b/builtin/bundle.c\n> @@ -11,31 +11,40 @@\n>   * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n>   */\n>  \n> -static const char * const builtin_bundle_usage[] = {\n> -\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> -\tN_(\"git bundle verify [<options>] <file>\"),\n> -\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n> -\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n> -\tNULL\n> +#define BUILTIN_BUNDLE_CREATE_USAGE \\\n> +\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n> +#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n> +\tN_(\"git bundle verify [<options>] <file>\")\n> +#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n> +\tN_(\"git bundle list-heads <file> [<refname>...]\")\n> +#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n> +\tN_(\"git bundle unbundle <file> [<refname>...]\")\n> +\n> +static char const * const builtin_bundle_usage[] = {\n> +\tBUILTIN_BUNDLE_CREATE_USAGE,\n> +\tBUILTIN_BUNDLE_VERIFY_USAGE,\n> +\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n> +\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n> +\tNULL,\n>  };\n>  \n>  static const char * const builtin_bundle_create_usage[] = {\n> -\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> +\tBUILTIN_BUNDLE_CREATE_USAGE,\n>  \tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_verify_usage[] = {\n> -\tN_(\"git bundle verify [<options>] <file>\"),\n> +\tBUILTIN_BUNDLE_VERIFY_USAGE,\n>  \tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_list_heads_usage[] = {\n> -\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n> +\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n>  \tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_unbundle_usage[] = {\n> -\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n> +\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n>  \tNULL\n>  };\n"},{"id":"464016","messageId":"xmqqh70oa865.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-02.36-b2d76494a34-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 02/36] builtin/bundle.c: indent with tabs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:01:22Z","receivedAt":"2022-09-30T21:01:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Fix indentation issues introduced with 73c3253d75e (bundle: framework\n> for options before bundle file, 2019-11-10), and carried forward in\n> some subsequent commits.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  builtin/bundle.c | 26 +++++++++++++-------------\n>  1 file changed, 13 insertions(+), 13 deletions(-)\n\nMakes sense.  \"git show -w\" allows us to see that the indentation is\nthe only change made with this step, too.\n\n>\n> diff --git a/builtin/bundle.c b/builtin/bundle.c\n> index e80efce3a42..5c78894afd5 100644\n> --- a/builtin/bundle.c\n> +++ b/builtin/bundle.c\n> @@ -12,31 +12,31 @@\n>   */\n>  \n>  static const char * const builtin_bundle_usage[] = {\n> -  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> -  N_(\"git bundle verify [<options>] <file>\"),\n> -  N_(\"git bundle list-heads <file> [<refname>...]\"),\n> -  N_(\"git bundle unbundle <file> [<refname>...]\"),\n> -  NULL\n> +\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> +\tN_(\"git bundle verify [<options>] <file>\"),\n> +\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n> +\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n> +\tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_create_usage[] = {\n> -  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> -  NULL\n> +\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n> +\tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_verify_usage[] = {\n> -  N_(\"git bundle verify [<options>] <file>\"),\n> -  NULL\n> +\tN_(\"git bundle verify [<options>] <file>\"),\n> +\tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_list_heads_usage[] = {\n> -  N_(\"git bundle list-heads <file> [<refname>...]\"),\n> -  NULL\n> +\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n> +\tNULL\n>  };\n>  \n>  static const char * const builtin_bundle_unbundle_usage[] = {\n> -  N_(\"git bundle unbundle <file> [<refname>...]\"),\n> -  NULL\n> +\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n> +\tNULL\n>  };\n>  \n>  static int parse_options_cmd_bundle(int argc,\n"},{"id":"464017","messageId":"xmqqa66ga85w.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-01.36-1611913e321-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 01/36] CodingGuidelines: update and clarify command-line conventions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:01:31Z","receivedAt":"2022-09-30T21:01:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Having a space around \" | \" for flags, but not for flag values is\n> inconsistent, but this style guide codifies existing\n> patterns. Grepping shows that we don't have any instance matching the\n> second \"Don't\" example:\n>\n> \tgit grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n\nMakes sense.  Thanks.\n"},{"id":"464018","messageId":"xmqq5yh4a75s.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-05.36-ec977f7c8fe-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 05/36] doc SYNOPSIS: don't use ' for subcommands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:23:11Z","receivedAt":"2022-09-30T21:23:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Almost all of our documentation doesn't use \"'\" syntax for\n> subcommands, but these did, let's make them consistent with the\n> rest.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  Documentation/git-reflog.txt | 2 +-\n>  Documentation/git-rerere.txt | 2 +-\n>  2 files changed, 2 insertions(+), 2 deletions(-)\n\nGood.\n\n> diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\n> index db9d46edfa9..0537d4645be 100644\n> --- a/Documentation/git-reflog.txt\n> +++ b/Documentation/git-reflog.txt\n> @@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n>  depending on the subcommand:\n>  \n>  [verse]\n> -'git reflog' ['show'] [<log-options>] [<ref>]\n> +'git reflog' [show] [<log-options>] [<ref>]\n>  'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n>  \t[--rewrite] [--updateref] [--stale-fix]\n>  \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\n> index 4cfc8833780..4b613d4140c 100644\n> --- a/Documentation/git-rerere.txt\n> +++ b/Documentation/git-rerere.txt\n> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n> +'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n>  \n>  DESCRIPTION\n>  -----------\n"},{"id":"464019","messageId":"xmqq1qrsa6wm.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-07.36-829bdf58499-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:28:41Z","receivedAt":"2022-09-30T21:29:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n> \"[(-o | --option) <argument>]\", we were previously claiming that only\n> the long option accepted the \"<argument>\", which isn't what we meant.\n\nIt depends on which way you look at it ;-) namely, if vertical bar\nbinds tighter than option and its argument, then \"-m|--message\n<message>\" and \"(-m|--message) <message>\" would mean the same thing.\n\nLater in the series, we start insisting that the vertical bar must\nhave SP on both of its sides, which makes the vertical bar less\ntightly binding visually, and at that point, adding parentheses\naround the choices does become needed.\n\nAs long as these become consistent, the end result is happier than\nthe status quo.\n\n> -\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n> +\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n> -'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n> +'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n\nThanks.\n"},{"id":"464020","messageId":"xmqqwn9k8s6v.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-08.36-e9924890620-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 08/36] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:31:52Z","receivedAt":"2022-09-30T21:32:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Change commands in the \"diff\" family and \"rev-list\" to separate the\n> usage information and option listing with an empty line.\n\nThis makes the result more in line with what parse-options API gives\nvia the usage_with_options() call, I would presume.\n\nThat's a welcome change.\n\n"},{"id":"464021","messageId":"xmqqo7uw8rsm.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-14.36-a29af2dcc4f-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 14/36] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:40:25Z","receivedAt":"2022-09-30T21:40:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> The whitespace padding of alternatives should be of the form \"[-f |\n> --force]\" not \"[-f|--force]\". Likewise we should not have padding\n> before the first option, so \"(--all | <pack-filename>...)\" is correct,\n> not \"( --all | <pack-filename>... )\".\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  Documentation/git-diff-files.txt     | 2 +-\n>  Documentation/git-hash-object.txt    | 2 +-\n>  Documentation/git-merge-base.txt     | 4 ++--\n>  Documentation/git-pack-redundant.txt | 2 +-\n>  Documentation/git-prune-packed.txt   | 2 +-\n>  Documentation/git-rerere.txt         | 2 +-\n>  Documentation/git-send-pack.txt      | 2 +-\n>  Documentation/git-show-branch.txt    | 4 ++--\n>  Documentation/git-show-ref.txt       | 4 ++--\n>  Documentation/git-var.txt            | 2 +-\n>  Documentation/git-verify-pack.txt    | 2 +-\n>  builtin/bugreport.c                  | 2 +-\n>  builtin/commit-graph.c               | 2 +-\n>  builtin/diagnose.c                   | 2 +-\n>  builtin/sparse-checkout.c            | 2 +-\n>  15 files changed, 18 insertions(+), 18 deletions(-)\n\nConsistency is good.\n\nAnd ...\n\n>  [verse]\n> -'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n> +'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n>  \n>  DESCRIPTION\n>  -----------\n> diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\n> index 9fed59a3172..844d6f808a0 100644\n> --- a/Documentation/git-prune-packed.txt\n> +++ b/Documentation/git-prune-packed.txt\n> @@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git prune-packed' [-n|--dry-run] [-q|--quiet]\n> +'git prune-packed' [-n | --dry-run] [-q | --quiet]\n\n... these show that they are easier to read with the proposed spacing.\n"},{"id":"464022","messageId":"xmqqill48rob.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-16.36-db850539d2a-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 16/36] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:43:00Z","receivedAt":"2022-09-30T21:43:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> It's arguably more correct to say \"[<option>...]\" than either of these\n> forms, but the vast majority of our documentation uses the\n> \"[<options>]\" form to indicate an arbitrary number of options, let's\n> do the same in these cases, which were the odd ones out.\n\nYeah, I agree these should say [<option>...] to mean zero-or-more of\nthem.  It may be fine, as long as it is clear that we use\n[<options>] as a short-hand for it, though.\n"},{"id":"464023","messageId":"xmqqedvs8riv.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-17.36-041aa64f3c7-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 17/36] t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T21:46:16Z","receivedAt":"2022-09-30T21:46:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> As in a preceding commit use \"<options>\", not \"<options>...\", in this\n> case there is no *.txt version, but let's fix this one too while we're\n> at it.\n\nI do not quite understand why these need to be separate steps.  Some\nmay be supposed to have the same description in the code (help text)\nand in the text (doc source), and among them, some may have both\ncode and text wrong, and some others may have only code wrong, and\neven some others only text wrong.  It appears to me that you are\nthrowing the first one (both wrong) into a single category, and the\nlatter two (only one wrong) into a separate \"not consistent\"\ncategory, which does not make much sense to me.\n\nThe end result of this step is good.  It is just seeing the split is\nsomewhat distracting while reviewing.\n\nThanks.\n\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  t/helper/test-proc-receive.c | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\n> index cc08506cf0b..a4b305f4947 100644\n> --- a/t/helper/test-proc-receive.c\n> +++ b/t/helper/test-proc-receive.c\n> @@ -6,7 +6,7 @@\n>  #include \"test-tool.h\"\n>  \n>  static const char *proc_receive_usage[] = {\n> -\t\"test-tool proc-receive [<options>...]\",\n> +\t\"test-tool proc-receive [<options>]\",\n>  \tNULL\n>  };\n"},{"id":"464026","messageId":"xmqqzgeg7c4k.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-18.36-3a439c4401d-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 18/36] doc txt & -h consistency: fix mismatching labels","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T22:04:11Z","receivedAt":"2022-09-30T22:04:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n> +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n>  option is specified, ignored files are also removed. This can, for\n>  example, be useful to remove all build products.\n>  \n> -If any optional `<path>...` arguments are given, only those paths\n> +If any optional `<pathspec>...` arguments are given, only those paths\n>  are affected.\n\nIf you replace <path> with <pathspec>, then \"only those paths are\"\nmust be replaced with \"only those paths that match the pathspec\nare\", because you are losing \"those paths\" from the sentence.\n\n> diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\n> index 01e1c214dd8..74832d06806 100644\n> --- a/Documentation/git-credential-cache--daemon.txt\n> +++ b/Documentation/git-credential-cache--daemon.txt\n> @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git credential-cache{litdd}daemon' [--debug] <socket>\n> +'git credential-cache{litdd}daemon' [--debug] <socket-path>\n>  \n>  DESCRIPTION\n>  -----------\n\nThe description text (outside the context of this hunk) still refers\nto <socket>.\n\n> diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\n> index 972a055fbd8..c612a5fd5b9 100644\n> --- a/Documentation/git-mv.txt\n> +++ b/Documentation/git-mv.txt\n> @@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git mv' [<options>] <args>...\n> +'git mv' [<options>] <source>... <destination>\n\nThis one is good, as the rest of the document is written in terms of\nthe source and the destination.  The description of --force may need\nto rephrase \"target\" -> \"destination\", though.\n\n\n> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\n> index 014a78409b9..eec1268b10f 100644\n> --- a/Documentation/git-receive-pack.txt\n> +++ b/Documentation/git-receive-pack.txt\n> @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git-receive-pack' <directory>\n> +'git-receive-pack' <git-dir>\n\n`upload-archive` below is updated to call this <repository>, and\nthat might be a better update, but the goal of this step is to use\nthe same word in both code and text, so changing to <git-dir> is OK.\n\nBut \"OPTIONS\" part of the document (outside the context of this\nhunk) still says <directory>, which should be corrected.\n\n> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\n> index 31a97a1b6c5..c15ec895720 100644\n> --- a/Documentation/git-tag.txt\n> +++ b/Documentation/git-tag.txt\n> @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n> +'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n>  \t<tagname> [<commit> | <object>]\n>  'git tag' -d <tagname>...\n>  'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n\nIf you want to do \"keyid\" -> \"key-id\", then you'd need to update the\none in the DESCRIPTION part.\n\n> diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\n> index fba0f1c1b27..e8eb10baad7 100644\n> --- a/Documentation/git-upload-archive.txt\n> +++ b/Documentation/git-upload-archive.txt\n> @@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git upload-archive' <directory>\n> +'git upload-archive' <repository>\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -54,7 +54,7 @@ access via non-smart-http.\n>  \n>  OPTIONS\n>  -------\n> -<directory>::\n> +<repository>::\n>  \tThe repository to get a tar archive from.\n\nThis is good.\n\n> diff --git a/builtin/bugreport.c b/builtin/bugreport.c\n> index 61d93383f51..96052541cbf 100644\n> --- a/builtin/bugreport.c\n> +++ b/builtin/bugreport.c\n> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n>  }\n>  \n>  static const char * const bugreport_usage[] = {\n> -\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n> +\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n>  \t   \"              [--diagnose[=<mode>]]\"),\n>  \tNULL\n>  };\n> diff --git a/builtin/clean.c b/builtin/clean.c\n> index 5466636e666..6f039f555b2 100644\n> --- a/builtin/clean.c\n> +++ b/builtin/clean.c\n> @@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n>  static unsigned int colopts;\n>  \n>  static const char *const builtin_clean_usage[] = {\n> -\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n> +\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n>  \tNULL\n>  };\n>  \n> diff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\n> index 13cbb75ca28..e8f77f535f3 100644\n> --- a/builtin/commit-graph.c\n> +++ b/builtin/commit-graph.c\n> @@ -10,10 +10,10 @@\n>  #include \"tag.h\"\n>  \n>  #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n> -\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n> +\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n>  \n>  #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n> -\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n> +\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n>  \t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n>  \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n>  \t   \"                       <split options>\")\n> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\n> index 4c6c89ab0de..ca672a6a619 100644\n> --- a/builtin/credential-cache--daemon.c\n> +++ b/builtin/credential-cache--daemon.c\n> @@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n>  \tconst char *socket_path;\n>  \tint ignore_sighup = 0;\n>  \tstatic const char *usage[] = {\n> -\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n> +\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n>  \t\tNULL\n>  \t};\n>  \tint debug = 0;\n\nHeh, so we are allowed to change _BOTH_ code and text to make them\nconsistent.  We are not limited to pick the existing word used in\none or the other.  If that is the case, using <repository> instead\nof <git-dir> for receive-pack may be a good change to make here as\nwell.\n\nIn any case, reviewing code part of this step is far easier than the\ndocumentation part, as the latter must be done more carefully to\nspot the mention of the earlier word in the entire document.\n\n"},{"id":"464027","messageId":"xmqqtu4o7bux.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-19.36-3bfdd3fb79e-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 19/36] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-30T22:09:58Z","receivedAt":"2022-09-30T22:10:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> diff --git a/builtin/rev-list.c b/builtin/rev-list.c\n> index ada68a4af5e..3cc8aad52ed 100644\n> --- a/builtin/rev-list.c\n> +++ b/builtin/rev-list.c\n> @@ -20,7 +20,7 @@\n>  #include \"packfile.h\"\n>  \n>  static const char rev_list_usage[] =\n> -\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n> +\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n\nAs rev-list requires at least one commit, so <commit>... means one\nor more of <commit>.  Now rev-list does not have to have pathspec,\nbut it is OK to have the double-dash, so\n\n    git rev-list [<options>] <commit>... [--] [<path>...]\n\nwould be more correct, no?  <path>... may mean one or more pathspec\nelements, but having it inside [] makes it zero or more.  But it is\nnot a crime to have \"--\" without any pathspec, yet [[--] <path>...]\nrequires one or more paths if you want to write \"--\".\n\n"},{"id":"464033","messageId":"xmqqy1u05p01.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-11.36-7794c3d6ef5-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T01:09:02Z","receivedAt":"2022-10-01T01:13:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n> \"[(-o | --option) <argument>]\", we were previously claiming that only\n> the long option accepted the \"<argument>\", which isn't what we meant.\n>\n> This syntax issue for \"bugreport\" originated in\n> 238b439d698 (bugreport: add tool to generate debugging info,\n> 2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\n> create 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n> \"bugreport\" documentation and code.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  builtin/bugreport.c | 2 +-\n>  builtin/diagnose.c  | 2 +-\n>  2 files changed, 2 insertions(+), 2 deletions(-)\n\nI think we saw exactly the same pattern in an earlier step.  If the\npatches in this series are split along the type of fix, then these\ntwo and the other patch fall into the same category.  Another way to\norganize is to split per file boundary, but I think these two paths\nare fixed up for different problem in later steps.  I think split\nalong the type of fix makes much more sense, if we can, than split\nper file, so I am almost OK with the current organization (probably\nwith this squashed into that earlier step).\n\n> diff --git a/builtin/bugreport.c b/builtin/bugreport.c\n> index faa268f3cfb..23170113cc8 100644\n> --- a/builtin/bugreport.c\n> +++ b/builtin/bugreport.c\n> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n>  }\n>  \n>  static const char * const bugreport_usage[] = {\n> -\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n> +\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n>  \t   \"              [--diagnose[=<mode>]\"),\n>  \tNULL\n>  };\n> diff --git a/builtin/diagnose.c b/builtin/diagnose.c\n> index 28c394a62a5..474de9ec647 100644\n> --- a/builtin/diagnose.c\n> +++ b/builtin/diagnose.c\n> @@ -3,7 +3,7 @@\n>  #include \"diagnose.h\"\n>  \n>  static const char * const diagnose_usage[] = {\n> -\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n> +\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n>  \t   \"             [--mode=<mode>]\"),\n>  \tNULL\n>  };\n"},{"id":"464043","messageId":"xmqqwn9j2xmu.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-21.36-1713227d497-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T18:43:05Z","receivedAt":"2022-10-01T18:43:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Fix various issues of SYNOPSIS and -h output syntax where:\n>\n>  * Options such as --force were missing entirely\n>  * ...or the short option, such as -f\n\nIn the full option listing (e.g. what usage_with_options() gives for\noptions with both short and long form, such as \"git commit -h\"), it\nindeed is good to show both, i.e.\n\n\t-q, --quiet    run quietly\n\t-v, --verbose  run verbosely\n\nis good and we have enough room to do so.\n\nBut for commands with so small number of options that we cram the\noptions on the summary line without hiding them behind a single\n\"[<options>]\" placeholder, I am not sure if it is a good idea to\nshow both and do\n\n\tusage: git cmd [-f|--force] [-q|--quiet] [-v|--verbose] <pathspec>\n\nin the first place.  It would be easier to understand without\ndistracting choice, i.e.\n\n\tusage: git cmd [--force] [--quiet] [--verbose] <pathspec>\n\nor even with only the short-form (but that risks to become\nunfriendly to new people who haven't learned what a single letter\noption \"-x\" means, so I would not recommend it).\n\nEspecially with the mandatory space around vertical bar, it would\nlook horrible,\n\n\tusage: git cmd [-f | --force] [-q | --quiet] [-v | --verbose] <pathspec>\n\nas the visual binding between the short and long form of the same\noption becomes weaker.\n\nSo, I dunno. \n\n\n>  * We said \"opts\" or \"options\", but could instead enumerate\n>    the (small) set of supported options\n\nYes, see above.\n\n>  * argument labels were missing entirely (ls-remote)\n\nI do not know what an \"argument label\" is, but I can see that\nls-remote.c lacked the description for the --sort option.\n\n>  * How we referred to an argument was inconsistent between the two,\n>    e.g. <pack> v.s. <pack>.idx.\n\nI didn't see anything in this category in this patch.\n\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n\n> -'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n> +'git send-pack' [--mirror] [--dry-run] [--force]\n> +\t\t[--receive-pack=<git-receive-pack>]\n\nIt may not matter what order the options are given, but having\nanything before \"--dry-run\" looks somewhat strange.  It is not like\nthis list is given in the same order as they appear in the options[]\narray.\n\nI wonder if \"--mirror\" is the most closely related to (read: easier\nto understand if it is listed close to) \"--all\" and <ref>,\ni.e. immediately before the destination repository?\n\nWe do not really care about these commands that end-users will never\ninvoke themselves, so I'll let it pass, even though this one looks a\nbit questionable.\n\n> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\n> index 872436d7426..68392d2a56e 100644\n> --- a/Documentation/git-sparse-checkout.txt\n> +++ b/Documentation/git-sparse-checkout.txt\n> @@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git sparse-checkout' <subcommand> [<options>]\n> +'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n\nOK.  We have only limited number that fits on a line; otherwise\n\"<subcommand>\" -> \"<command>\" which refers reders to the COMMANDS\nsection of the documentation.\n\n> diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\n> index 969bb2e15f1..4e6bf44427f 100644\n> --- a/Documentation/git-update-server-info.txt\n> +++ b/Documentation/git-update-server-info.txt\n> @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git update-server-info'\n> +'git update-server-info' [-f | --force]\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n>  what references and packs the server has.  This command\n>  generates such auxiliary files.\n>  \n> +OPTIONS\n> +-------\n> +-f::\n> +--force::\n> +\tAllow adding otherwise ignored files.\n\nThe option help text says this:\n\n    N_(\"update the info files from scratch\"), 0),\n\n> diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\n> index 92097f6673d..96d10cfdffe 100644\n> --- a/Documentation/git-verify-commit.txt\n> +++ b/Documentation/git-verify-commit.txt\n> @@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git verify-commit' <commit>...\n> +'git verify-commit' [-v | --verbose] <commit>...\n>  \n>  DESCRIPTION\n>  -----------\n\nThe DESCRIPTION section also mentions \"--raw\".\n\n> diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\n> index 0b8075dad96..a454df2711e 100644\n> --- a/Documentation/git-verify-tag.txt\n> +++ b/Documentation/git-verify-tag.txt\n> @@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git verify-tag' [--format=<format>] <tag>...\n> +'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n>  \n>  DESCRIPTION\n>  -----------\n\nThe DESCRIPTION section also mentions \"--raw\".\n\n> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\n> index ca672a6a619..d4eb0097d24 100644\n> --- a/builtin/credential-cache--daemon.c\n> +++ b/builtin/credential-cache--daemon.c\n> @@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n>  \tconst char *socket_path;\n>  \tint ignore_sighup = 0;\n>  \tstatic const char *usage[] = {\n> -\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n> +\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n>  \t\tNULL\n>  \t};\n>  \tint debug = 0;\n\nOK.\n\n> diff --git a/builtin/describe.c b/builtin/describe.c\n> index e17c4b4c69b..23e3f05fb10 100644\n> --- a/builtin/describe.c\n> +++ b/builtin/describe.c\n> @@ -23,8 +23,9 @@\n>  define_commit_slab(commit_names, struct commit_name *);\n>  \n>  static const char * const describe_usage[] = {\n> -\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n> -\tN_(\"git describe [<options>] --dirty\"),\n> +\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n> +\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n> +\tN_(\"git describe <blob>\"),\n>  \tNULL\n>  };\n\nOK.\n\n> diff --git a/builtin/diff-index.c b/builtin/diff-index.c\n> index e667cf52e7d..aea139b9d8f 100644\n> --- a/builtin/diff-index.c\n> +++ b/builtin/diff-index.c\n> @@ -9,7 +9,7 @@\n>  #include \"submodule.h\"\n>  \n>  static const char diff_cache_usage[] =\n> -\"git diff-index [-m] [--cached] \"\n> +\"git diff-index [-m] [--cached] [--merge-base] \"\n>  \"[<common-diff-options>] <tree-ish> [<path>...]\"\n>  \"\\n\"\n>  COMMON_DIFF_OPTIONS_HELP;\n\nOK.\n\n> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n> index df44e5cc0d1..5d5ac038716 100644\n> --- a/builtin/ls-remote.c\n> +++ b/builtin/ls-remote.c\n> @@ -7,7 +7,7 @@\n>  \n>  static const char * const ls_remote_usage[] = {\n>  \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n> -\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n> +\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n>  \t   \"              [--symref] [<repository> [<refs>...]]\"),\n>  \tNULL\n>  };\n\nOK.\n\nWe do not need to express that --sort=<key0> --sort=<key1>... can be\ngiven multiple times without triggering the usual last-one-wins?  In\nthe documentation, the option description can say \"this option can\nbe given multiple times\", but here we cannot, so the best we could\ndo would be [--sort=<key>...] and I wonder if that is worth it.\n\n> diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\n> index cfbd5c36c76..27c2ca06acb 100644\n> --- a/builtin/pack-refs.c\n> +++ b/builtin/pack-refs.c\n> @@ -5,7 +5,7 @@\n>  #include \"repository.h\"\n>  \n>  static char const * const pack_refs_usage[] = {\n> -\tN_(\"git pack-refs [<options>]\"),\n> +\tN_(\"git pack-refs [--all] [--no-prune]\"),\n>  \tNULL\n>  };\n\nEven though \"[--[no-]all] [--[no-]prune\" would be more complete, I\ndo not mind listing only the side that makes it behave differently\nfrom the default.  But if you reroll with a more complete version\nwith documentation updates, I wouldn't complain at all.\n\n> diff --git a/builtin/revert.c b/builtin/revert.c\n> index ee2a0807f01..ee32c714a76 100644\n> --- a/builtin/revert.c\n> +++ b/builtin/revert.c\n> @@ -21,14 +21,15 @@\n>   */\n>  \n>  static const char * const revert_usage[] = {\n> -\tN_(\"git revert [<options>] <commit-ish>...\"),\n> -\tN_(\"git revert <subcommand>\"),\n> +\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n> +\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n>  \tNULL\n>  };\n\nThis one uses \"[--[no-]edit]\", which is OK.  Also <keyid> unlike the\nother ones I saw in my yesterdays review is not <key-id>, which is\nsomewhat curious.\n\n>  static const char * const cherry_pick_usage[] = {\n> -\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n> -\tN_(\"git cherry-pick <subcommand>\"),\n> +\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n> +\t   \"                [-S[<keyid>]] <commit>...\"),\n> +\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n>  \tNULL\n>  };\n\nAnd here we see \"[--edit]\", which is not exactly consistent.\n\n> diff --git a/builtin/send-pack.c b/builtin/send-pack.c\n> index 64962be0168..4c5d125fa0a 100644\n> --- a/builtin/send-pack.c\n> +++ b/builtin/send-pack.c\n> @@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n>  \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n>  \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n>  \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n> +\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n>  \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n>  \tNULL,\n>  };\n\nExcellent.\n\n> diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\n> index 1b0f10225f0..50b6df78df0 100644\n> --- a/builtin/symbolic-ref.c\n> +++ b/builtin/symbolic-ref.c\n> @@ -5,8 +5,9 @@\n>  #include \"parse-options.h\"\n>  \n>  static const char * const git_symbolic_ref_usage[] = {\n> -\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n> -\tN_(\"git symbolic-ref -d [-q] <name>\"),\n> +\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n> +\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n> +\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n>  \tNULL\n>  };\n\nWhy spell out --delete without allowing -d?  Especially when listing\nonly -q for OPT__QUIET()?\n\n    git symbolic-ref (-d|--delete) [-q|--quiet] <name>\n\nwould be more complete but I think the original (i.e. \"-d [-q]\") is\nmore consistent.\n\n> diff --git a/builtin/tag.c b/builtin/tag.c\n> index 75dece0e4f1..d428c45dc8d 100644\n> --- a/builtin/tag.c\n> +++ b/builtin/tag.c\n> @@ -23,11 +23,13 @@\n>  #include \"date.h\"\n>  \n>  static const char * const git_tag_usage[] = {\n> -\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n> -\t   \"        <tagname> [<head>]\"),\n> +\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n> +\t   \"        <tagname> [<commit> | <object>]\"),\n\nOK.\n\n>  \tN_(\"git tag -d <tagname>...\"),\n\n\n> -\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n> -\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n> +\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n> +\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n> +\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n> +\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n\nOK.\n\n>  \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n>  \tNULL\n>  };\n\n\n> diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\n> index 880fffec587..d2239c9ef4d 100644\n> --- a/builtin/update-server-info.c\n> +++ b/builtin/update-server-info.c\n> @@ -4,7 +4,7 @@\n>  #include \"parse-options.h\"\n>  \n>  static const char * const update_server_info_usage[] = {\n> -\t\"git update-server-info [--force]\",\n> +\t\"git update-server-info [-f | --force]\",\n>  \tNULL\n>  };\n>  \n> diff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\n> index 125af53885f..25b69da2bf2 100644\n> --- a/builtin/upload-pack.c\n> +++ b/builtin/upload-pack.c\n> @@ -8,7 +8,8 @@\n>  #include \"serve.h\"\n>  \n>  static const char * const upload_pack_usage[] = {\n> -\tN_(\"git upload-pack [<options>] <dir>\"),\n> +\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n> +\t   \"                [--advertise-refs] <directory>\"),\n>  \tNULL\n>  };\n\nOK.  We do not really care about these commands that end-users will\nnever invoke themselves, but these look good.\n\n> diff --git a/help.c b/help.c\n> index d04542d8261..f1e090a4428 100644\n> --- a/help.c\n> +++ b/help.c\n> @@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n>  \tstruct strbuf buf = STRBUF_INIT;\n>  \tint build_options = 0;\n>  \tconst char * const usage[] = {\n> -\t\tN_(\"git version [<options>]\"),\n> +\t\tN_(\"git version [--build-options]\"),\n>  \t\tNULL\n>  \t};\n>  \tstruct option options[] = {\n\nOK.\n"},{"id":"464044","messageId":"xmqqmtaf2xig.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-22.36-702eb747c0f-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T18:45:43Z","receivedAt":"2022-10-01T18:45:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\n> the order that they're discussed in the \"COMMANDS\" section of the\n> documentation.\n\npathspec refers to the entire set of patterns, which consists of one\nor more \"pathspec element\"s, so there is no need for \"...\" there.\n\nListing the commands in the order they are described does make\nsense.\n\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  Documentation/git-rerere.txt | 2 +-\n>  builtin/rerere.c             | 2 +-\n>  2 files changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\n> index 9d0e6f53e7e..992b469270c 100644\n> --- a/Documentation/git-rerere.txt\n> +++ b/Documentation/git-rerere.txt\n> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n> +'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n>  \n>  DESCRIPTION\n>  -----------\n> diff --git a/builtin/rerere.c b/builtin/rerere.c\n> index 12570537d37..8b7392d5b44 100644\n> --- a/builtin/rerere.c\n> +++ b/builtin/rerere.c\n> @@ -10,7 +10,7 @@\n>  #include \"pathspec.h\"\n>  \n>  static const char * const rerere_usage[] = {\n> -\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n> +\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n>  \tNULL,\n>  };\n"},{"id":"464045","messageId":"xmqqh70n2xe4.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-23.36-01e20b8e452-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 23/36] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T18:48:19Z","receivedAt":"2022-10-01T18:48:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> The C version was right to use \"()\" in place of \"[]\", let's update\n\nIncomplete description: use () in place of [] around what?\n\n> the *.txt version accordingly, and furthermore list the *.c options in\n> the same order as the *.txt.\n\nGood.\n\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  Documentation/git-read-tree.txt | 2 +-\n>  builtin/read-tree.c             | 2 +-\n>  2 files changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\n> index b9bfdc0a319..7567955bad8 100644\n> --- a/Documentation/git-read-tree.txt\n> +++ b/Documentation/git-read-tree.txt\n> @@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n> +'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n>  \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n>  \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n>  \n> diff --git a/builtin/read-tree.c b/builtin/read-tree.c\n> index b3a389e1b1f..f4cbe460b97 100644\n> --- a/builtin/read-tree.c\n> +++ b/builtin/read-tree.c\n> @@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n>  \n>  static const char * const read_tree_usage[] = {\n>  \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n> -\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n> +\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n>  \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n>  \tNULL\n>  };\n"},{"id":"464046","messageId":"xmqqbkqv2x80.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-24.36-7f93da79fee-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 24/36] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T18:51:59Z","receivedAt":"2022-10-01T18:52:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Amend the -h output to match that of the *.txt output, the differences\n> were fairly small. In the case of \"[<options>]\" we only have a few of\n> them, so let's exhaustively list them as in the *.txt.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  builtin/bundle.c | 7 ++++---\n>  1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/builtin/bundle.c b/builtin/bundle.c\n> index 1b08700bf9e..544c78a5f3a 100644\n> --- a/builtin/bundle.c\n> +++ b/builtin/bundle.c\n> @@ -12,13 +12,14 @@\n>   */\n>  \n>  #define BUILTIN_BUNDLE_CREATE_USAGE \\\n> -\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n> +\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n> +\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n\nThis looks like getting a bit on the longer side.  I think keeping\nthe original would be a far better option IF we can give the list of\noptions and their explanations like usage_with_options() does, and I\nalso think it would be the right thing in the longer term.  As an\nintermediate state before getting there, I do not think the\npostimage of this patch hurts, but is one more thing we need to\nmaintain and get distracted.  So, I dunno.\n\n>  #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n> -\tN_(\"git bundle verify [<options>] <file>\")\n> +\tN_(\"git bundle verify [-q | --quiet] <file>\")\n>  #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n>  \tN_(\"git bundle list-heads <file> [<refname>...]\")\n>  #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n> -\tN_(\"git bundle unbundle <file> [<refname>...]\")\n> +\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n>  \n>  static char const * const builtin_bundle_usage[] = {\n>  \tBUILTIN_BUNDLE_CREATE_USAGE,\n"},{"id":"464047","messageId":"xmqq7d1j2wv0.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v3-25.36-ab109f73264-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 25/36] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T18:59:47Z","receivedAt":"2022-10-01T18:59:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\n> receive-pack\" and \"git credential-cache--daemon\".\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n> ---\n>  Documentation/git-receive-pack.txt | 2 +-\n>  builtin/credential-cache--daemon.c | 4 ++--\n>  2 files changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\n> index eec1268b10f..92452334ac4 100644\n> --- a/Documentation/git-receive-pack.txt\n> +++ b/Documentation/git-receive-pack.txt\n> @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git-receive-pack' <git-dir>\n> +'git receive-pack' <git-dir>\n\nI think this, together with git-upload-pack, was very much\nintentional, at least when it was written, because it is the way we\ninvoked the command on the other side of the connection that goes\nover the wire.  I suspect git-upload-archive falls into the same\ncategory, even though it seems to lack the dash there.\n\n> diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\n\nThis one is reasonable, on the other hand.  That is how\ncredential-cache.c::spawn_daemon() runs it.\n"},{"id":"464049","messageId":"xmqqczbbyuqj.fsf@gitster.g","threadId":"58397","inReplyTo":"xmqqwn9j2xmu.fsf@gitster.g","subject":"Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-01T23:44:36Z","receivedAt":"2022-10-01T23:44:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Instead of going over the patches in the rest of the series, I think\nwe'd probably need to step back a bit and give ourselves a general\nguideline.  \n\nThis list is a draft of things I have learned from reading the\nseries, many of them from this step 21/36 alone, but some are from\nearlier steps.  I think the ones with '*' in front of them are not\ncontroversial, but others are merely my suggestions at this point:\n\n * Use of spaces in optional [] and choose-from-one, both for\n   freestanding token and for a value (i.e. what immediately follows\n   an equal sign '='), are as specified in [PATCH 1/36].\n\n * For a command \"git cmd\", the documentation in the SYNOPSIS\n   section and the usage string from \"git cmd -h\" ought to match.\n   Let's call them simply a \"usage string\".\n\n * The usage string for a command that has majorly different\n   operating modes can and should enumerate the different forms\n   separately (cf. how \"git diff -h\" lists different modes).\n\n * The usage string for a command with a large number of options can\n   and should use \"[<options>]\" placeholder in the SYNOPSIS and\n   \"usage:\" lines, i.e. \"git cmd [<options>]\", and let the\n   DESCRIPTION section (in documentation) and the option listing (in\n   the output from usage_with_options() function).\n\n + The usage string for a command with a small number of options can\n   enumerate individual options as long as the result (for each\n   operating modes) can fit on a single line.\n\n + When a usage string shows options individually (instead of using\n   [<options>] placeholder and leaving the listing to the latter\n   half of usage_with_options()):\n\n   - if an option has both long and short forms, only long form can\n     and should be shown if the resulting line would become overly\n     long with both listed as choices.\n\n     do   : \"git cmd [--quiet] [--verbose] [--dry-run] <pathspec>\"\n     don't: \"git cmd [--quiet | -q] [--verbose | -v] [--dry-run | -n] <pathspec>\"\n\n   - when showing a Boolean option, show only the form that\n     countermands the default, unless the command can take a\n     different default depending on the context.  When use of other\n     options or configuration can change the default value, show the\n     option as \"--[no-]option\".\n\n     do   : \"git pack-refs [--all] [--no-prune]\"\n     don't: \"git pack-refs [--[no-]all] [--[no-]prune]\"\n\n   - when showing an option that can be given multiple times that\n     causes cumulative effect (as opposed to the \"last one wins\"),\n     signal that by saying \"--option...\" to signal that it is\n     meaningful to have one or more of them.\n\n"},{"id":"464051","messageId":"CAPig+cRq_qdg_o9wgWszmagYNi+s=wkczng9+vHz31DiAhKE+A@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v3-35.36-22da68abce3-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-10-02T01:25:40Z","receivedAt":"2022-10-02T01:26:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> There's been a lot of incremental effort to make the SYNOPSIS output\n> in our documentation consistent with the -h output,\n> e.g. cbe485298bf (git reflog [expire|delete]: make -h output\n> consistent with SYNOPSIS, 2022-03-17) is one recent example, but that\n> effort has been an uphill battle due to the lack of regression\n> testing.\n>\n> This adds such regression testing, we can parse out the SYNOPSIS\n> output with \"sed\", and is turns out it's relatively easy to normalize\n\ns/is/it/\n\n> it and the \"-h\" output to match on another.\n>\n> Some of the issues that are left:\n>\n>  * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n>    all showing \"git log\" and \"git show\" usage output. I.e. the\n>    \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n>    command we're running.\n>\n>  * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n>    of what command it's running. The same for \"annotate\" and \"blame\".\n\nIs this mention of annotate/blame out of date? Doesn't [28/36] make\nthese commands emit the correct usage text? Or am I misunderstanding\nwhat this is saying?\n\n>  * Commands which implement subcommands such as like\n>    \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n>    in a very different order in the *.txt and *.c. Fixing it would\n>    require some verbose diffs, so it's been left alone for onw.\n\ns/onw/now/\n\n>  * Commands such as \"format-patch\" have a very long argument list in\n>    the *.txt, but just \"[<options>]\" in the *.c.\n>\n>    What to do about these has been left out of this series, except to\n>    the extent that preceding commits changed \"[<options>]\" (or\n>    equivalent) to the list of options in cases where that list of\n>    options was tiny, or we clearly meant to exhaustively list the\n>    options in both *.txt and *.c.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n"},{"id":"464052","messageId":"CAPig+cThkXgkfgeBe5g3f4Mw2HFXeX0M5W4p9NbF7-G_cGB40Q@mail.gmail.com","threadId":"58397","inReplyTo":"patch-v3-36.36-b56113dd620-20220930T180415Z-avarab@gmail.com","subject":"Re: [PATCH v3 36/36] tests: assert consistent whitespace in -h output","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-10-02T01:29:43Z","receivedAt":"2022-10-02T01:30:02Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> Add a test for the *.txt and *.c output assertions which asserts that\n> for \"-h\" lines that aren't the \"usage: \" or \" or: \" lines they start\n> with the same amount of whitespace. This ensures that we won't have\n> buggy output like:\n>\n>    [...]\n>    or: git tag [-n[<num>]]\n>                [...]\n>        [--create-reflog] [...]\n>\n> Which should instead be like this instead, i.e. the options lines\n> should be aligned:\n\nToo many \"instead\"s.\n\n>    [...]\n>    or: git tag [-n[<num>]]\n>                [...]\n>                [--create-reflog] [...]\n>\n> It would be better to be able to use \"test_cmp\" here, i.e. to\n> construct the output we expect, and compare it against the actual\n> output.\n>\n> For most built-in commands this would be rather straightforward. In\n> \"t0450-txt-doc-vs-help.sh\" we already compute the whitespace that a\n> \"git-$builtin\" needs, and strip away \"usage: \" or \" or: \" from the\n> start of lines. The problem is:\n>\n>  * For commands that implement subcommands, such as \"git bundle\", we\n>    don't know whether e.g. \"git bundle create\" is the subcommand\n>    \"create\", or the argument \"create\" to \"bundle\" for the purposes of\n>    alignment.\n>\n>    We *do* have that information from the *.txt version, since the\n>    part within the ''-quotes should be the command & subcommand, but\n>    that isn't consistent (e.g. see \"git bundle\" and \"git\n>    commit-graph\", only the latter is correct), and parsing that out\n>    would be non-trivial.\n>\n>  * If we were to make this stricter we have various\n>    non-parse_options() users (e.g. \"git diff-tree\") that don't have the\n>    nicely aligned output which we've had since\n>    4631cfc20bd (parse-options: properly align continued usage output,\n>    2021-09-21).\n>\n> So rather than make perfect the enemy of the good let's assert that\n> for those lines that are indented they should all use the same\n> indentation.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n"},{"id":"464053","messageId":"xmqq35c6zv2j.fsf@gitster.g","threadId":"58397","inReplyTo":"xmqqczbbyuqj.fsf@gitster.g","subject":"Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-02T04:52:04Z","receivedAt":"2022-10-02T04:56:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Instead of going over the patches in the rest of the series, I think\n> we'd probably need to step back a bit and give ourselves a general\n> guideline.  \n\nHaving said that, I am a bit torn on the next step.\n\nThe updates done in this series stops way short to make the usage\nstrings conform to the proposed guideline.  We could include such\nchanges to make them conform, but that would make the series that is\nalready long even longer, which is not what I want to see.\n\nMy preference is to go in the other direction, i.e. make NO attempt\nto improve usage strings in this series, the only change we will\nmake would be, except for documenting the coding guideline and\nadding tests that ensure usage strings in the code and in the\ndocument match for majority of commands, are to make sure the code\nand the doc match (IOW, if an existing option is not described in\neither, we leave it to a later round to add it, as long as the code\nand the doc consistently fail to describe it).  That may allow us to\nmake this series shorter than it currently is, hopefully?  I dunno.\n\nAnd a fix to the proposed guideline.\n\n>  * The usage string for a command with a large number of options can\n>    and should use \"[<options>]\" placeholder in the SYNOPSIS and\n>    \"usage:\" lines, i.e. \"git cmd [<options>]\", and let the\n>    DESCRIPTION section (in documentation) and the option listing (in\n>    the output from usage_with_options() function).\n\n\"... list and explain them\" is missing from the end.\n"},{"id":"464060","messageId":"221003.86wn9hti15.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqv8p4a871.fsf@gitster.g","subject":"Re: [PATCH v3 04/36] blame: use a more detailed usage_msg_optf() error on bad -L","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-03T08:36:02Z","receivedAt":"2022-10-03T08:58:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Sep 30 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>> Improve the error message emitted when there's a bad -L argument, and\n>> do so using the parse-options.c flavor of \"usage()\", instead of using\n>> the non-parse-options.c usage() function. This was the last user of\n>> usage() in this file.\n>>\n>> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n>> ---\n>>  builtin/blame.c | 7 ++++---\n>>  1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> This may not be incorrect (I didn't spend time to see if this \"while\n> at it\" is truly an improvement) but clearly outside the scome of\n> \"output from the -h option should match synopsis\" theme.\n\nI'll eject this & rewrite a subsequent commit, as a re-roll will make\nclear the choice was between \"convert this last user of the API\" early\non, or in a later commit have the \"-h\" output be correct for both\nusage() and usage_with_options()>\n\n>> diff --git a/builtin/blame.c b/builtin/blame.c\n>> index a9fe8cf7a68..8ec59fa2096 100644\n>> --- a/builtin/blame.c\n>> +++ b/builtin/blame.c\n>> @@ -1108,12 +1108,13 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n>>  \tanchor = 1;\n>>  \trange_set_init(&ranges, range_list.nr);\n>>  \tfor (range_i = 0; range_i < range_list.nr; ++range_i) {\n>> +\t\tconst char *arg = range_list.items[range_i].string;\n>>  \t\tlong bottom, top;\n>> -\t\tif (parse_range_arg(range_list.items[range_i].string,\n>> -\t\t\t\t    nth_line_cb, &sb, lno, anchor,\n>> +\t\tif (parse_range_arg(arg, nth_line_cb, &sb, lno, anchor,\n>>  \t\t\t\t    &bottom, &top, sb.path,\n>>  \t\t\t\t    the_repository->index))\n>> -\t\t\tusage(blame_usage);\n>> +\t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n>> +\t\t\t\t       blame_opt_usage, options, arg);\n>\n> So, it used to be that it emitted only blame_usage which is a rough\n> match to the synopsis, \n>\n>     \"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\"\n>\n> but now we use blame_opt_usage + options, which means that the same\n> blame_usage, a blank line, and \"<rev-opts> are documented in\n> git-rev-list(1)\" is given, followed by the list of full options. \n>\n> I do think saying \"failed to parse -L\" is an improvement, but it is\n> dubious it is a good idea to follow it with a wall of text that\n> comes from options[].  After all, if the user chose to use \"-L 2,8\"\n> and a typo replaced the comma with a full stop, which caused\n> parse_range_arg() to fail, does it make sense to scroll away the\n> message that helpfully points out that \"-L argument '2.8'\" was the\n> problem with other option descriptions?\n\nAs an aside: This is a good general observation about\nusage_with_options(), and usage_msg_opt*() in particular. I.e. it would\nbe helpful to have a version of it that took a \"-L\" argument, so we\ncould know what option we're complaining about.\n\nThen we could either show the usage message just for that option, or\nhighlight it in the full \"-h\" output we're showing.\n\nBut obviously all for some later date.\n\n> This is why we shouldn't distract a series with \"while at it\"\n> changes that are outside the scope of the theme.  Letting the patch\n> authors and reviewers concentrate on doing one thing well would\n> avoid mistakes, but mixing unrelated changes distracts them.  Having\n> to think about the differences between usage() and usage_msg_optf()\n> with this change already distracted me and stopped my review on this\n> series in this sitting.  The topic will need to wait for the next\n> time I decide to sit with it and start reading it from the next step.\n>\n> And of course, a series like this, which is supposed to do the same\n> thing to many files for consistency, is better written and reviewed\n> in one sitting, because that will make it easier in reviewers' mind\n> to keep and apply the same review criteria consistently.\n\nNoted, FWIW I was assuming that as other commands make wide use of\nusage_msg_opt*() for this sort of thing that the usage here & output\nchange didn't need too much rationalizing, but live & learn etc. Thanks.\n"},{"id":"464064","messageId":"221003.86sfk5tgrs.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqmtaf2xig.fsf@gitster.g","subject":"Re: [PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-03T09:00:28Z","receivedAt":"2022-10-03T09:12:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sat, Oct 01 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>> For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\n>> the order that they're discussed in the \"COMMANDS\" section of the\n>> documentation.\n>\n> pathspec refers to the entire set of patterns, which consists of one\n> or more \"pathspec element\"s, so there is no need for \"...\" there.\n\nMaybe I'm misreading this, but are you suggesting that whenever\n\"<pathspec>\" appears in the text the user should understand it as\n\"<pathspec>...\", i.e. as is the case with the special-case that is\n\"<options>\".\n\nI'm not opposet do that, but I really wish we could avoid further\nspecial-cases, there's no current user of \"<pathspecs>\" (with an \"s\" for\nplural.\n\nIf you're saying that \"<pathspec>\" now should be interpretet like that\nthen surely e.g.:\n\n\tDocumentation/git-clone.txt:--recurse-submodules[=<pathspec>]::\n\nShould be read as supporting:\n\n\t--recurse-submodules some/path some-other-path\n\nWe could say that using it in that option context is a further\nspecial-case, but I think this way lies madness, it would mean that\ne.g.:\n\n\tgit some-cmd [--option=<pathspec>] [-- <pathspec>]\n\nwould have \"<pathspec>\" mean different things in those two contexts.\n\nWe also have various examples of \"<pathspec>...\" meaning what it means\nin the post-image here (including in one of the version of the \"rerere\"\ndocs):\n\n\tDocumentation/git-add.txt:        [--] [<pathspec>...]\n\tDocumentation/git-commit.txt:      [--] [<pathspec>...]\n\tDocumentation/git-reset.txt:'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]\n\nFWIW it should arguably be [<pathspec>...] here, but per 5d2c3b01604\n(rerere forget: deprecate invocation without pathspec, 2011-03-01) it\nlooks as though we want to advertise the other usage.\n\n\n"},{"id":"464079","messageId":"xmqqczb8yk8h.fsf@gitster.g","threadId":"58397","inReplyTo":"221003.86sfk5tgrs.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-03T15:55:58Z","receivedAt":"2022-10-03T15:56:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> On Sat, Oct 01 2022, Junio C Hamano wrote:\n>\n>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>>\n>>> For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\n>>> the order that they're discussed in the \"COMMANDS\" section of the\n>>> documentation.\n>>\n>> pathspec refers to the entire set of patterns, which consists of one\n>> or more \"pathspec element\"s, so there is no need for \"...\" there.\n>\n> Maybe I'm misreading this, but are you suggesting that whenever\n> \"<pathspec>\" appears in the text the user should understand it as\n> \"<pathspec>...\", i.e. as is the case with the special-case that is\n> \"<options>\".\n\nNot really.  A <pathspec> is a set of <pathspec element>s, so\nwriting \"<pathspec-element>...\" and \"<pathspec>\" are equivalent.\n\n> I'm not opposet do that, but I really wish we could avoid further\n> special-cases, there's no current user of \"<pathspecs>\" (with an \"s\" for\n> plural.\n\nPresumably just like range-diff compares two ranges (which in the\nnormal command line syntax we would not have), some future commands\nmay need to take two pathspecs (that is two sets of patterns to\nmatch paths) to do something interesting, but I do not think of\nanything that does so in the current command set, so it is very good\nthat nobody claims to take <pathspecs> with an \"s\"for plural.\n\n> \tDocumentation/git-clone.txt:--recurse-submodules[=<pathspec>]::\n>\n> Should be read as supporting:\n>\n> \t--recurse-submodules some/path some-other-path\n\nYup, the option should support it, alternatively it could take\n<path>.  Or it could take multiple of these options in which case\neach of them is taking a pathspec element.\n"},{"id":"464112","messageId":"221004.86fsg4t3x2.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqczb8yk8h.fsf@gitster.g","subject":"Re: [PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T07:50:48Z","receivedAt":"2022-10-04T07:59:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Oct 03 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n>\n>> On Sat, Oct 01 2022, Junio C Hamano wrote:\n>>\n>>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>>>\n>>>> For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\n>>>> the order that they're discussed in the \"COMMANDS\" section of the\n>>>> documentation.\n>>>\n>>> pathspec refers to the entire set of patterns, which consists of one\n>>> or more \"pathspec element\"s, so there is no need for \"...\" there.\n>>\n>> Maybe I'm misreading this, but are you suggesting that whenever\n>> \"<pathspec>\" appears in the text the user should understand it as\n>> \"<pathspec>...\", i.e. as is the case with the special-case that is\n>> \"<options>\".\n>\n> Not really.  A <pathspec> is a set of <pathspec element>s, so\n> writing \"<pathspec-element>...\" and \"<pathspec>\" are equivalent.\n\nSo, \"yes\"? I.e. leaving aside \"pathspec\" or \"pathspec-element\"\n\"<pathspecs>\" is redundant to \"<pathspecs>...\" in this intpreretation?\nBut for any given \"<x>\" the \"<x>\" is not the same as \"<x>...\"?\n\n>> I'm not opposet do that, but I really wish we could avoid further\n>> special-cases, there's no current user of \"<pathspecs>\" (with an \"s\" for\n>> plural.\n>\n> Presumably just like range-diff compares two ranges (which in the\n> normal command line syntax we would not have), some future commands\n> may need to take two pathspecs (that is two sets of patterns to\n> match paths) to do something interesting, but I do not think of\n> anything that does so in the current command set, so it is very good\n> that nobody claims to take <pathspecs> with an \"s\"for plural.\n>\n>> \tDocumentation/git-clone.txt:--recurse-submodules[=<pathspec>]::\n>>\n>> Should be read as supporting:\n>>\n>> \t--recurse-submodules some/path some-other-path\n>\n> Yup, the option should support it, alternatively it could take\n> <path>.  Or it could take multiple of these options in which case\n> each of them is taking a pathspec element.\n\nIn bourne shell syntax we're talking about the distinction between:\n\n\t$ echo --opt {a,b}\n\t--opt a b\n\nAnd:\n\n\t$ echo --opt={a,b}\n\t--opt=a --opt=b\n\nWhich in the SYNOPSIS syntax are (asuming \"a\", and \"b\" are <byte>), respectively:\n\n\t--opt <byte>...\n\nAnd:\n\n\t[--opt <byte>]...\n\nIf we maintain that for a given \"<label>\" that it has an implicit \"...\"\nafter it I don't see how you can distingish these two by way of\nexplaining how the command works via the syntax. I.e. it's possible (and\nwe even have some obscure code in-tree that does this) to support e.g.:\n\n\t--opt a b c --opt d e f g h --opt i --opt j\n\nWhich, if (in my wordview) would be explained with this syntax:\n\n\t[--opt <byte>...]...\n\nBut that's really not what we mean most of the time, we *don't* want\nthat \"...\" on the argument to \"--opt\", because it only takes one\nargument.\n"},{"id":"464118","messageId":"221004.86bkqruc2i.gmgdl@evledraar.gmail.com","threadId":"58397","inReplyTo":"xmqqwn9j2xmu.fsf@gitster.g","subject":"Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T10:13:29Z","receivedAt":"2022-10-04T10:18:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sat, Oct 01 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n> [...]\n>> diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\n>> index 969bb2e15f1..4e6bf44427f 100644\n>> --- a/Documentation/git-update-server-info.txt\n>> +++ b/Documentation/git-update-server-info.txt\n>> @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git update-server-info'\n>> +'git update-server-info' [-f | --force]\n>>  \n>>  DESCRIPTION\n>>  -----------\n>> @@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n>>  what references and packs the server has.  This command\n>>  generates such auxiliary files.\n>>  \n>> +OPTIONS\n>> +-------\n>> +-f::\n>> +--force::\n>> +\tAllow adding otherwise ignored files.\n>\n> The option help text says this:\n>\n>     N_(\"update the info files from scratch\"), 0),\n\nThat was a copy/paste error, thanks!\n\n> [...]\n>> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n>> index df44e5cc0d1..5d5ac038716 100644\n>> --- a/builtin/ls-remote.c\n>> +++ b/builtin/ls-remote.c\n>> @@ -7,7 +7,7 @@\n>>  \n>>  static const char * const ls_remote_usage[] = {\n>>  \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n>> -\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n>> +\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n>>  \t   \"              [--symref] [<repository> [<refs>...]]\"),\n>>  \tNULL\n>>  };\n>\n> OK.\n\nI've triped to fix all the issues you noted above (including what I elided).\n\n> We do not need to express that --sort=<key0> --sort=<key1>... can be\n> given multiple times without triggering the usual last-one-wins?  In\n> the documentation, the option description can say \"this option can\n> be given multiple times\", but here we cannot, so the best we could\n> do would be [--sort=<key>...] and I wonder if that is worth it.\n\nYes, FWIW I've left this at an explanation in the commit message. It\nshould be [(--sort=<key>)...], but also far git-branch.txt etc., but\nfixing everything everywhere is a much bigger change.\n\n>> diff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\n>> index cfbd5c36c76..27c2ca06acb 100644\n>> --- a/builtin/pack-refs.c\n>> +++ b/builtin/pack-refs.c\n>> @@ -5,7 +5,7 @@\n>>  #include \"repository.h\"\n>>  \n>>  static char const * const pack_refs_usage[] = {\n>> -\tN_(\"git pack-refs [<options>]\"),\n>> +\tN_(\"git pack-refs [--all] [--no-prune]\"),\n>>  \tNULL\n>>  };\n>\n> Even though \"[--[no-]all] [--[no-]prune\" would be more complete, I\n> do not mind listing only the side that makes it behave differently\n> from the default.  But if you reroll with a more complete version\n> with documentation updates, I wouldn't complain at all.\n\nFor now I'm just trying to make commands consistent with their \"other\nside\", but not all things consistent with all other things.\n\nHaving said that I really prefer when we have an \"--all\" as opposed to\n\"[--no-all | --all]\", or the briefer \"[--[no-]all]\", it makes it clearer\nthat \"--no-all\" is the default, and that your \"--all\" is turning on the\nnon-default.\n\nLikewise \"--no-prune\".\n\n>>  static const char * const cherry_pick_usage[] = {\n>> -\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n>> -\tN_(\"git cherry-pick <subcommand>\"),\n>> +\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n>> +\t   \"                [-S[<keyid>]] <commit>...\"),\n>> +\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n>>  \tNULL\n>>  };\n>\n> And here we see \"[--edit]\", which is not exactly consistent.\n\n*Nod*, but I'll leave this, per the \"not trying to make all things\nconsistent with everything else\", it's now consistent with its own\nother side.\n\n>> diff --git a/builtin/send-pack.c b/builtin/send-pack.c\n>> index 64962be0168..4c5d125fa0a 100644\n>> --- a/builtin/send-pack.c\n>> +++ b/builtin/send-pack.c\n>> @@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n>>  \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n>>  \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n>>  \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n>> +\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n>>  \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n>>  \tNULL,\n>>  };\n>\n> Excellent.\n>\n>> diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\n>> index 1b0f10225f0..50b6df78df0 100644\n>> --- a/builtin/symbolic-ref.c\n>> +++ b/builtin/symbolic-ref.c\n>> @@ -5,8 +5,9 @@\n>>  #include \"parse-options.h\"\n>>  \n>>  static const char * const git_symbolic_ref_usage[] = {\n>> -\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n>> -\tN_(\"git symbolic-ref -d [-q] <name>\"),\n>> +\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n>> +\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n>> +\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n>>  \tNULL\n>>  };\n>\n> Why spell out --delete without allowing -d?  Especially when listing\n> only -q for OPT__QUIET()?\n>\n>     git symbolic-ref (-d|--delete) [-q|--quiet] <name>\n>\n> would be more complete but I think the original (i.e. \"-d [-q]\") is\n> more consistent.\n\nI can do this if you'd like, but didn't per the above, i.e. the *.txt\nuses just \"symbolic-ref --delete\".\n"},{"id":"464131","messageId":"patch-v3-01.34-f76804fe9ae-20221004T131009Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com","subject":"[PATCH v3 01/34] tests: assert *.txt SYNOPSIS and -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:20:46Z","receivedAt":"2022-10-04T13:21:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test to assert basic compliance with the CodingGuidelines in the\nSYNOPSIS and builtin -h output. For now we only assert that the \"-h\"\noutput doesn't have \"\\t\" characters, as a very basic syntax check.\n\nSubsequent commits will expand on the checks here as various issues\nare fixed, but let's first add the test scaffolding.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++\n 1 file changed, 44 insertions(+)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..c8820bdd38f\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,44 @@\n+#!/bin/sh\n+\n+test_description='assert (unbuilt) Documentation/*.txt and -h output'\n+\n+TEST_PASSES_SANITIZE_LEAK=true\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+help_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\tout_dir=\"out/$builtin\" &&\n+\tout=\"$out_dir/help.synopsis\" &&\n+\tif test -f \"$out\"\n+\tthen\n+\t\techo \"$out\" &&\n+\t\treturn 0\n+\tfi &&\n+\tmkdir -p \"$out_dir\" &&\n+\ttest_expect_code 129 git $builtin -h >\"$out.raw\" 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp;\n+\t\t}' <\"$out.raw\" >\"$out\" &&\n+\techo \"$out\"\n+}\n+\n+HT=\"\t\"\n+\n+while read builtin\n+do\n+\t# -h output assertions\n+\ttest_expect_success \"$builtin -h output has no \\t\" '\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\t\t! grep \"$HT\" \"$h2s\"\n+\t'\n+done <builtins\n+\n+test_done\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464132","messageId":"patch-v3-02.34-c95d3b9ad42-20221004T131009Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com","subject":"[PATCH v3 02/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:20:47Z","receivedAt":"2022-10-04T13:21:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nHaving a space around \" | \" for flags, but not for flag values is\ninconsistent, but this style guide codifies existing\npatterns. Grepping shows that we don't have any instance matching the\nsecond \"Don't\" example:\n\n\tgit grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 9fca21cc5f9..3d3bdeba9e4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -650,8 +650,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -665,6 +665,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not immediately after opening or\n+ before closing a [] or () pair:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464133","messageId":"cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v3 00/34] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:20:45Z","receivedAt":"2022-10-04T13:21:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"We are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nFor the rest of the general overview (the first paragraphs are\ncopy/pasted) see the v1 at:\nhttps://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/ [1];\nFor v3 see:\nhttp://lore.kernel.org/git/cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com\n\nChanges since v3:\n\n * Added a commit to put a small portion of the the new tests first,\n   we then add a bit to it as we go along.\n\n * Squashed some changes as requested, now some of the \"doc txt & -h\n   consistency\" commits have changes that were previously split up,\n   but that's noted in the commit message.\n\n * Ejected the \"blame\" usage_msg_optf() change, instead the relevant\n   later commit just supports both usage() and usage_with_options().\n\n * Consistently use [<options>], not \"[<options...]\"\n\n * Various squshes/fix-ups suggested by Eric & Junio, thanks both!\n\n * The new test now runs much faster, since we cache the \"sed\"\n   commands that extract the \"-h\" and \"*.txt\" output\n\nÆvar Arnfjörð Bjarmason (34):\n  tests: assert *.txt SYNOPSIS and -h output\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: indent with tabs\n  bundle: define subcommand -h in terms of command -h\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n  tests: assert consistent whitespace in -h output\n\n Documentation/CodingGuidelines                |  14 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |   8 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   4 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   4 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   4 +-\n Documentation/git-reflog.txt                  |  17 +-\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-rev-list.txt                |   2 +-\n Documentation/git-send-pack.txt               |   5 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 +-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |  18 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  22 ++-\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 ++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 +++++---\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-commit.c                       |   2 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/verify-tag.c                          |   2 +-\n builtin/worktree.c                            | 110 ++++++++---\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 172 ++++++++++++++++++\n t/t0450/txt-help-mismatches                   |  58 ++++++\n 82 files changed, 593 insertions(+), 198 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n create mode 100644 t/t0450/txt-help-mismatches\n\nRange-diff against v2:\n -:  ----------- >  1:  f76804fe9ae tests: assert *.txt SYNOPSIS and -h output\n 1:  1611913e321 =  2:  c95d3b9ad42 CodingGuidelines: update and clarify command-line conventions\n 2:  b2d76494a34 =  3:  b7c98a40393 builtin/bundle.c: indent with tabs\n 3:  953a72abee1 =  4:  522d7fbb0a3 bundle: define subcommand -h in terms of command -h\n 4:  a8312c50f01 <  -:  ----------- blame: use a more detailed usage_msg_optf() error on bad -L\n 5:  ec977f7c8fe =  5:  ac437d4eee5 doc SYNOPSIS: don't use ' for subcommands\n 6:  b0ae035500c =  6:  f20cbb661c6 doc SYNOPSIS: consistently use ' for commands\n 8:  e9924890620 =  7:  ecdc14f6dfe built-ins: consistently add \"\\n\" between \"usage\" and options\n10:  1a02f7c76cd !  8:  1b9b6a91916 doc txt & -h consistency: word-wrap\n    @@ Commit message\n         doc txt & -h consistency: word-wrap\n     \n         Change the documentation and -h output for those built-in commands\n    -    where the *.txt and -h output didn't match as far as word-wrapping was\n    -    concerned.\n    +    where both the -h output and *.txt were lacking in word-wrapping.\n    +\n    +    There are many more built-ins that could use this treatment, this\n    +    change is narrowed to those where this whitespace change is needed to\n    +    make the -h and *.txt consistent in the end.\n    +\n    +    In the case of \"Documentation/git-hash-object.txt\" and\n    +    \"builtin/hash-object.c\" this is not a \"doc txt & -h consistency\"\n    +    change, as we're changing both versions, doing so here makes a\n    +    subsequent change smaller.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    + ## Documentation/git-hash-object.txt ##\n    +@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file\n    + SYNOPSIS\n    + --------\n    + [verse]\n    +-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n    ++'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n    ++\t\t[--stdin [--literally]] [--] <file>...\n    + 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n    + \n    + DESCRIPTION\n    +\n      ## Documentation/git-worktree.txt ##\n     @@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees\n      SYNOPSIS\n    @@ builtin/diagnose.c\n      };\n      \n     \n    + ## builtin/hash-object.c ##\n    +@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n    + int cmd_hash_object(int argc, const char **argv, const char *prefix)\n    + {\n    + \tstatic const char * const hash_object_usage[] = {\n    +-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n    ++\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n    ++\t\t   \"                [--stdin] [--] <file>...\"),\n    + \t\t\"git hash-object  --stdin-paths\",\n    + \t\tNULL\n    + \t};\n    +\n      ## builtin/init-db.c ##\n     @@ builtin/init-db.c: static int shared_callback(const struct option *opt, const char *arg, int unset)\n      }\n 7:  829bdf58499 !  9:  f4598ca1899 doc SYNOPSIS & -h: fix incorrect alternates syntax\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    doc SYNOPSIS & -h: fix incorrect alternates syntax\n    +    doc txt & -h consistency: fix incorrect alternates syntax\n     \n         Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n         \"[(-o | --option) <argument>]\", we were previously claiming that only\n         the long option accepted the \"<argument>\", which isn't what we meant.\n     \n    -    This issue has been with us in both the \"-h\" and *.txt versions since\n    -    bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n    +    This syntax issue for \"bugreport\" originated in\n    +    238b439d698 (bugreport: add tool to generate debugging info,\n    +    2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\n    +    create 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n    +    \"bugreport\" documentation and code.\n     \n    -    There are also issues with the alternates syntax for \"bugreport\" and\n    -    \"diagnose\", but in those cases only for one of *.c or *.txt, not\n    -    both. Those issues will be fixed in a subsequent \"consistency\" commit.\n    +    In the case of \"Documentation/git-stash.txt\" and \"builtin/stash.c\"\n    +    this is not a \"doc txt & -h consistency\" change, as we're changing\n    +    both versions, doing so here makes a subsequent change smaller.\n    +\n    +    In that case fix the incorrect \"[-o | --option <argument>]\" syntax,\n    +    which should be \"[(-o | --option) <argument>]\", we were previously\n    +    claiming that only the long option accepted the \"<argument>\", which\n    +    isn't what we meant.\n    +\n    +    The \"stash\" issue has been with us in both the \"-h\" and *.txt versions\n    +    since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n    +\n    +    We could claim that this isn't a syntax issue if a \"vertical bar binds\n    +    tighter than option and its argument\", but such a rule would change\n    +    e.g. this \"cat-file\" SYNOPSIS example to mean something we don't:\n    +\n    +            ... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\n    +\n    +    We have various other examples where the post-image here is already\n    +    used, e.g. for \"format-patch\" (\"-o\"), \"grep\" (\"-m\"),\n    +    \"submodule\" (\"set-branch -b\") etc.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    @@ Documentation/git-stash.txt: stash index (e.g. the integer `n` is equivalent to\n      \tSave your local modifications to a new 'stash entry' and roll them\n      \tback to HEAD (in the working tree and in the index).\n     \n    + ## builtin/bugreport.c ##\n    +@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n    + }\n    + \n    + static const char * const bugreport_usage[] = {\n    +-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n    ++\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n    + \t   \"              [--diagnose[=<mode>]\"),\n    + \tNULL\n    + };\n    +\n    + ## builtin/diagnose.c ##\n    +@@\n    + #include \"diagnose.h\"\n    + \n    + static const char * const diagnose_usage[] = {\n    +-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n    ++\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n    + \t   \"             [--mode=<mode>]\"),\n    + \tNULL\n    + };\n    +\n      ## builtin/stash.c ##\n     @@ builtin/stash.c: static const char * const git_stash_usage[] = {\n      \tN_(\"git stash branch <branchname> [<stash>]\"),\n 9:  516af07e8a8 <  -:  ----------- doc SYNOPSIS & -h: word-wrap\n11:  7794c3d6ef5 <  -:  ----------- doc txt & -h consistency: fix incorrect alternates syntax\n12:  357a228000c = 10:  0e955f294cd doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n13:  57cbaee9826 = 11:  aa2f9325839 doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n14:  a29af2dcc4f = 12:  009a0e586e9 doc txt & -h consistency: correct padding around \"[]()\"\n15:  589705cf6fa = 13:  b568189532f stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n16:  db850539d2a ! 14:  e5cb5c91b82 doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n    @@ Commit message\n         In the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\n         to indicate that these are optional.\n     \n    +    In the case of \"t/helper/test-proc-receive.c\" there is no *.txt\n    +    version, making it the only hunk in this commit that's not a \"doc txt\n    +    & -h consistency\" change.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-mv.txt ##\n    @@ builtin/sparse-checkout.c\n      \tNULL\n      };\n      \n    +\n    + ## t/helper/test-proc-receive.c ##\n    +@@\n    + #include \"test-tool.h\"\n    + \n    + static const char *proc_receive_usage[] = {\n    +-\t\"test-tool proc-receive [<options>...]\",\n    ++\t\"test-tool proc-receive [<options>]\",\n    + \tNULL\n    + };\n    + \n17:  041aa64f3c7 ! 15:  403e7ceb449 t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n    +    doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n     \n    -    As in a preceding commit use \"<options>\", not \"<options>...\", in this\n    -    case there is no *.txt version, but let's fix this one too while we're\n    -    at it.\n    +    Change \"builtin/credential-cache--daemon.c\" to use \"<socket-path>\" not\n    +    \"<socket_path>\" in a placeholder label, almost all of our\n    +    documentation uses this form.\n    +\n    +    This is now consistent with the \"If a placeholder has multiple words,\n    +    they are separated by dashes\" guideline added in\n    +    9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's\n    +    add a now-passing test to assert that that's the case.\n    +\n    +    To do this we need to introduce a very sed-powered parser to extract\n    +    the SYNOPSIS from the *.txt, and handle not all commands with \"-h\"\n    +    having a corresponding *.txt (e.g. \"bisect--helper\"). We'll still want\n    +    to handle syntax edge cases in the *.txt in subsequent commits for\n    +    other checks, but let's do that then.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## t/helper/test-proc-receive.c ##\n    -@@\n    - #include \"test-tool.h\"\n    + ## builtin/credential-cache--daemon.c ##\n    +@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n    + \tconst char *socket_path;\n    + \tint ignore_sighup = 0;\n    + \tstatic const char *usage[] = {\n    +-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n    ++\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n    + \t\tNULL\n    + \t};\n    + \tint debug = 0;\n    +\n    + ## t/t0450-txt-doc-vs-help.sh ##\n    +@@ t/t0450-txt-doc-vs-help.sh: help_to_synopsis () {\n    + \techo \"$out\"\n    + }\n    + \n    ++builtin_to_txt () {\n    ++       echo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n    ++}\n    ++\n    ++txt_to_synopsis () {\n    ++\tbuiltin=\"$1\" &&\n    ++\tout_dir=\"out/$builtin\" &&\n    ++\tout=\"$out_dir/txt.synopsis\" &&\n    ++\tif test -f \"$out\"\n    ++\tthen\n    ++\t\techo \"$out\" &&\n    ++\t\treturn 0\n    ++\tfi &&\n    ++\tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n    ++\tsed -n \\\n    ++\t\t-e '/^\\[verse\\]$/,/^$/ {\n    ++\t\t\t/^$/d;\n    ++\t\t\t/^\\[verse\\]$/d;\n    ++\n    ++\t\t\tp;\n    ++\t\t}' \\\n    ++\t\t<\"$b2t\" >\"$out\" &&\n    ++\techo \"$out\"\n    ++}\n    ++\n    ++check_dashed_labels () {\n    ++\t! grep -E \"<[^>_-]+_\" \"$1\"\n    ++}\n    ++\n    + HT=\"\t\"\n      \n    - static const char *proc_receive_usage[] = {\n    --\t\"test-tool proc-receive [<options>...]\",\n    -+\t\"test-tool proc-receive [<options>]\",\n    - \tNULL\n    - };\n    + while read builtin\n    +@@ t/t0450-txt-doc-vs-help.sh: do\n    + \t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n    + \t\t! grep \"$HT\" \"$h2s\"\n    + \t'\n    ++\n    ++\ttest_expect_success \"$builtin -h output has dashed labels\" '\n    ++\t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n    ++\t'\n    ++\n    ++\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n    ++\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n    ++\n    ++\tif test -f \"$txt\"\n    ++\tthen\n    ++\t\ttest_set_prereq \"$preq\"\n    ++\tfi &&\n    ++\n    ++\t# *.txt output assertions\n    ++\ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n    ++\t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n    ++\t'\n    + done <builtins\n      \n    + test_done\n18:  3a439c4401d ! 16:  563ccaab6a9 doc txt & -h consistency: fix mismatching labels\n    @@ Commit message\n         corresponding -h output where our translatable labels didn't match\n         up.\n     \n    +    In some cases we need to adjust the prose that follows the SYNOPSIS\n    +    accordingly, as it refers back to the changed label.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-clean.txt ##\n    @@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu\n      example, be useful to remove all build products.\n      \n     -If any optional `<path>...` arguments are given, only those paths\n    +-are affected.\n     +If any optional `<pathspec>...` arguments are given, only those paths\n    - are affected.\n    ++that match the pathspec are affected.\n      \n      OPTIONS\n      -------\n    @@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - T\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-credential-cache--daemon.txt: DESCRIPTION\n    + NOTE: You probably don't want to invoke this command yourself; it is\n    + started automatically when you use linkgit:git-credential-cache[1].\n    + \n    +-This command listens on the Unix domain socket specified by `<socket>`\n    ++This command listens on the Unix domain socket specified by `<socket-path>`\n    + for `git-credential-cache` clients. Clients may store and retrieve\n    + credentials. Each credential is held for a timeout specified by the\n    + client; once no credentials are held, the daemon exits.\n     \n      ## Documentation/git-mv.txt ##\n     @@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a symlink\n    @@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a syml\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-mv.txt: OPTIONS\n    + -------\n    + -f::\n    + --force::\n    +-\tForce renaming or moving of a file even if the target exists\n    ++\tForce renaming or moving of a file even if the <destination> exists.\n    + -k::\n    + \tSkip move or rename actions which would lead to an error\n    + \tcondition. An error happens when a source is neither existing nor\n     \n      ## Documentation/git-receive-pack.txt ##\n     @@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed into the repository\n    @@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed in\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-receive-pack.txt: its behavior, see linkgit:git-config[1].\n    + \n    + OPTIONS\n    + -------\n    +-<directory>::\n    ++<git-dir>::\n    + \tThe repository to sync into.\n    + \n    + --http-backend-info-refs::\n     \n      ## Documentation/git-tag.txt ##\n     @@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object signed with GPG\n    @@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object\n      \t<tagname> [<commit> | <object>]\n      'git tag' -d <tagname>...\n      'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n    +@@ Documentation/git-tag.txt: to delete, list or verify tags.\n    + \n    + Unless `-f` is given, the named tag must not yet exist.\n    + \n    +-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command\n    ++If one of `-a`, `-s`, or `-u <key-id>` is passed, the command\n    + creates a 'tag' object, and requires a tag message.  Unless\n    + `-m <msg>` or `-F <file>` is given, an editor is started for the user to type\n    + in the tag message.\n    + \n    +-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`\n    ++If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`\n    + are absent, `-a` is implied.\n    + \n    + Otherwise, a tag reference that points directly at the given object\n    + (i.e., a lightweight tag) is created.\n    + \n    + A GnuPG signed tag object will be created when `-s` or `-u\n    +-<keyid>` is used.  When `-u <keyid>` is not used, the\n    ++<key-id>` is used.  When `-u <key-id>` is not used, the\n    + committer identity for the current user is used to find the\n    + GnuPG key for signing. \tThe configuration variable `gpg.program`\n    + is used to specify custom GnuPG binary.\n    +@@ Documentation/git-tag.txt: OPTIONS\n    + \tOverride `tag.gpgSign` configuration variable that is\n    + \tset to force each and every tag to be signed.\n    + \n    +--u <keyid>::\n    +---local-user=<keyid>::\n    ++-u <key-id>::\n    ++--local-user=<key-id>::\n    + \tMake a GPG-signed tag, using the given key.\n    + \n    + -f::\n    +@@ Documentation/git-tag.txt: This option is only applicable when listing tags without annotation lines.\n    + \tUse the given tag message (instead of prompting).\n    + \tIf multiple `-m` options are given, their values are\n    + \tconcatenated as separate paragraphs.\n    +-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n    ++\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n    + \tis given.\n    + \n    + -F <file>::\n    + --file=<file>::\n    + \tTake the tag message from the given file.  Use '-' to\n    + \tread the message from the standard input.\n    +-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n    ++\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n    + \tis given.\n    + \n    + -e::\n    +@@ Documentation/git-tag.txt: it in the repository configuration as follows:\n    + \n    + -------------------------------------\n    + [user]\n    +-    signingKey = <gpg-keyid>\n    ++    signingKey = <gpg-key_id>\n    + -------------------------------------\n    + \n    + `pager.tag` is only respected when listing tags, i.e., when `-l` is\n     \n      ## Documentation/git-upload-archive.txt ##\n     @@ Documentation/git-upload-archive.txt: git-upload-archive - Send archive back to git-archive\n    @@ builtin/commit-graph.c\n      \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n      \t   \"                       <split options>\")\n     \n    - ## builtin/credential-cache--daemon.c ##\n    -@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n    - \tconst char *socket_path;\n    - \tint ignore_sighup = 0;\n    - \tstatic const char *usage[] = {\n    --\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n    -+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n    - \t\tNULL\n    - \t};\n    - \tint debug = 0;\n    -\n      ## builtin/for-each-repo.c ##\n     @@\n      #include \"string-list.h\"\n19:  3bfdd3fb79e ! 17:  e6ef67f1c4f doc txt & -h consistency: add or fix optional \"--\" syntax\n    @@ Commit message\n         inconsistent, or where we incorrectly stated in one but not the other\n         that the \"--\" was mandatory.\n     \n    +    In the case of \"rev-list\" both sides were wrong, as we we don't\n    +    require one or more paths if \"--\" is used, e.g. this is OK:\n    +\n    +            git rev-list HEAD --\n    +\n    +    That part of this change is not a \"doc txt & -h consistency\" change,\n    +    as we're changing both versions, doing so here makes both sides\n    +    consistent.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    + ## Documentation/git-rev-list.txt ##\n    +@@ Documentation/git-rev-list.txt: git-rev-list - Lists commit objects in reverse chronological order\n    + SYNOPSIS\n    + --------\n    + [verse]\n    +-'git rev-list' [<options>] <commit>... [[--] <path>...]\n    ++'git rev-list' [<options>] <commit>... [--] [<path>...]\n    + \n    + DESCRIPTION\n    + -----------\n    +\n      ## builtin/for-each-repo.c ##\n     @@\n      #include \"string-list.h\"\n    @@ builtin/rev-list.c\n      \n      static const char rev_list_usage[] =\n     -\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n    -+\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n    ++\"git rev-list [<options>] <commit>... [--] [<path>...]\\n\"\n      \"\\n\"\n      \"  limiting output:\\n\"\n      \"    --max-count=<n>\\n\"\n20:  98bdd0353cf = 18:  766bafcde05 doc txt & -h consistency: make output order consistent\n21:  1713227d497 ! 19:  fb95d7a9f86 doc txt & -h consistency: add missing options and labels\n    @@ Commit message\n          * We said \"opts\" or \"options\", but could instead enumerate\n            the (small) set of supported options\n     \n    -     * argument labels were missing entirely (ls-remote)\n    +     * Options that were missing entirely (ls-remote's --sort=<key>)\n     \n    -     * How we referred to an argument was inconsistent between the two,\n    -       e.g. <pack> v.s. <pack>.idx.\n    +       As we can specify \"--sort\" multiple times (it's backed by a\n    +       string-list\" it should really be \"[(--sort=<key>)...]\", which is\n    +       what \"git for-each-ref\" lists it as, but let's leave that issue for\n    +       a subsequent cleanup, and stop at making these consistent. Other\n    +       \"ref-filter.h\" users share the same issue, e.g. \"git-branch.txt\".\n    +\n    +     * For \"verify-tag\" and \"verify-commit\" we were missing the \"--raw\"\n    +       option.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    @@ Documentation/git-update-server-info.txt: $GIT_OBJECT_DIRECTORY/info directories\n     +-------\n     +-f::\n     +--force::\n    -+\tAllow adding otherwise ignored files.\n    ++\tupdate the info files from scratch.\n     +\n      OUTPUT\n      ------\n    @@ Documentation/git-verify-commit.txt: git-verify-commit - Check the GPG signature\n      --------\n      [verse]\n     -'git verify-commit' <commit>...\n    -+'git verify-commit' [-v | --verbose] <commit>...\n    ++'git verify-commit' [-v | --verbose] [--raw] <commit>...\n      \n      DESCRIPTION\n      -----------\n    @@ Documentation/git-verify-tag.txt: git-verify-tag - Check the GPG signature of ta\n      --------\n      [verse]\n     -'git verify-tag' [--format=<format>] <tag>...\n    -+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n    ++'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...\n      \n      DESCRIPTION\n      -----------\n    @@ builtin/upload-pack.c\n      };\n      \n     \n    + ## builtin/verify-commit.c ##\n    +@@\n    + #include \"gpg-interface.h\"\n    + \n    + static const char * const verify_commit_usage[] = {\n    +-\t\tN_(\"git verify-commit [-v | --verbose] <commit>...\"),\n    ++\t\tN_(\"git verify-commit [-v | --verbose] [--raw] <commit>...\"),\n    + \t\tNULL\n    + };\n    + \n    +\n    + ## builtin/verify-tag.c ##\n    +@@\n    + #include \"ref-filter.h\"\n    + \n    + static const char * const verify_tag_usage[] = {\n    +-\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] <tag>...\"),\n    ++\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...\"),\n    + \t\tNULL\n    + };\n    + \n    +\n      ## help.c ##\n     @@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)\n      \tstruct strbuf buf = STRBUF_INIT;\n22:  702eb747c0f = 20:  729029f49c3 doc txt & -h consistency: make \"rerere\" consistent\n23:  01e20b8e452 ! 21:  2d4fdbd1aa1 doc txt & -h consistency: make \"read-tree\" consistent\n    @@ Metadata\n      ## Commit message ##\n         doc txt & -h consistency: make \"read-tree\" consistent\n     \n    -    The C version was right to use \"()\" in place of \"[]\", let's update\n    -    the *.txt version accordingly, and furthermore list the *.c options in\n    -    the same order as the *.txt.\n    +    The C version was right to use \"()\" in place of \"[]\" around the option\n    +    listing, let's update the *.txt version accordingly, and furthermore\n    +    list the *.c options in the same order as the *.txt.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n24:  7f93da79fee = 22:  c3d227c17c6 doc txt & -h consistency: make \"bundle\" consistent\n25:  ab109f73264 ! 23:  02e450ea39b doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n    @@ Commit message\n         Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\n         receive-pack\" and \"git credential-cache--daemon\".\n     \n    +    For \"git-receive-pack\" we do have a binary with that name, even when\n    +    installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes\n    +    of the SYNOPSIS let's use the \"git cmd\" form like everywhere else. It\n    +    can be invoked like that (and our tests do so), the parts of our\n    +    documentation that explain when you need to use the dashed form do so,\n    +    and use it.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-receive-pack.txt ##\n26:  d57635b2707 = 24:  430d40d3083 doc txt & -h consistency: add missing options\n27:  ac959d0cfc1 = 25:  acd6e1f2632 doc txt & -h consistency: make \"stash\" consistent\n28:  f617375ea9e ! 26:  c02fc626542 doc txt & -h consistency: make \"annotate\" consistent\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \tlong anchor;\n      \tconst int hexsz = the_hash_algo->hexsz;\n      \tlong num_lines = 0;\n    -+\tconst char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n    ++\tconst char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;\n    ++\tconst char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n      \n      \tsetup_default_color_by_age();\n      \tgit_config(git_blame_config, &output_option);\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n      \tfor (;;) {\n     -\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n    -+\t\tswitch (parse_options_step(&ctx, options, usage)) {\n    ++\t\tswitch (parse_options_step(&ctx, options, opt_usage)) {\n      \t\tcase PARSE_OPT_NON_OPTION:\n      \t\tcase PARSE_OPT_UNKNOWN:\n      \t\t\tbreak;\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\treverse = 1;\n      \t\t}\n     -\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n    -+\t\tparse_revision_opt(&revs, &ctx, options, usage);\n    ++\t\tparse_revision_opt(&revs, &ctx, options, opt_usage);\n      \t}\n      parse_done:\n      \trevision_opts_finish(&revs);\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\tcase 2: /* (1b) */\n      \t\t\tif (argc != 4)\n     -\t\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\t\tusage_with_options(usage, options);\n    ++\t\t\t\tusage_with_options(opt_usage, options);\n      \t\t\t/* reorder for the new way: <rev> -- <path> */\n      \t\t\targv[1] = argv[3];\n      \t\t\targv[3] = argv[2];\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\tbreak;\n      \t\tdefault:\n     -\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\tusage_with_options(usage, options);\n    ++\t\t\tusage_with_options(opt_usage, options);\n      \t\t}\n      \t} else {\n      \t\tif (argc < 2)\n     -\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\tusage_with_options(usage, options);\n    ++\t\t\tusage_with_options(opt_usage, options);\n      \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n      \t\t\tpath = add_prefix(prefix, argv[1]);\n      \t\t\targv[1] = argv[2];\n     @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n    + \t\t\t\t    nth_line_cb, &sb, lno, anchor,\n      \t\t\t\t    &bottom, &top, sb.path,\n      \t\t\t\t    the_repository->index))\n    - \t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n    --\t\t\t\t       blame_opt_usage, options, arg);\n    -+\t\t\t\t       usage, options, arg);\n    +-\t\t\tusage(blame_usage);\n    ++\t\t\tusage(str_usage);\n      \t\tif ((!lno && (top || bottom)) || lno < bottom)\n      \t\t\tdie(Q_(\"file %s has only %lu line\",\n      \t\t\t       \"file %s has only %lu lines\",\n29:  c96c3fc6d8d = 27:  d991b9ef611 doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n30:  34b778dd176 = 28:  dd7d2f0b167 doc txt & -h consistency: make \"diff-tree\" consistent\n31:  336fc749f1c = 29:  3c8154151f3 doc txt & -h consistency: make \"commit\" consistent\n32:  81024d1c3cd = 30:  2452157548b reflog doc: list real subcommands up-front\n33:  76e6b7d296a = 31:  dbcabff3421 worktree: define subcommand -h in terms of command -h\n34:  efd0c2c634d = 32:  ea82721b057 doc txt & -h consistency: make \"worktree\" consistent\n35:  22da68abce3 ! 33:  a2abf7a1161 tests: start asserting that *.txt SYNOPSIS matches -h output\n    @@ Commit message\n         testing.\n     \n         This adds such regression testing, we can parse out the SYNOPSIS\n    -    output with \"sed\", and is turns out it's relatively easy to normalize\n    +    output with \"sed\", and it turns out it's relatively easy to normalize\n         it and the \"-h\" output to match on another.\n     \n         We now ensure that we won't have regressions when it comes to the list\n    @@ Commit message\n            \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n            command we're running.\n     \n    -     * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n    -       of what command it's running. The same for \"annotate\" and \"blame\".\n    -\n          * Commands which implement subcommands such as like\n            \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n            in a very different order in the *.txt and *.c. Fixing it would\n    -       require some verbose diffs, so it's been left alone for onw.\n    +       require some verbose diffs, so it's been left alone for now.\n     \n          * Commands such as \"format-patch\" have a very long argument list in\n            the *.txt, but just \"[<options>]\" in the *.c.\n    @@ Commit message\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## t/t0450-txt-doc-vs-help.sh (new) ##\n    + ## t/t0450-txt-doc-vs-help.sh ##\n     @@\n    -+#!/bin/sh\n    -+\n    -+test_description='compare (unbuilt) Documentation/*.txt to -h output\n    + #!/bin/sh\n    + \n    +-test_description='assert (unbuilt) Documentation/*.txt and -h output'\n    ++test_description='assert (unbuilt) Documentation/*.txt and -h output\n     +\n     +Run this with --debug to see a summary of where we still fail to make\n     +the two versions consistent with one another.'\n    -+\n    -+. ./test-lib.sh\n    -+\n    -+test_expect_success 'setup: list of builtins' '\n    -+\tgit --list-cmds=builtins >builtins\n    -+'\n    -+\n    + \n    + TEST_PASSES_SANITIZE_LEAK=true\n    + . ./test-lib.sh\n    +@@ t/t0450-txt-doc-vs-help.sh: test_expect_success 'setup: list of builtins' '\n    + \tgit --list-cmds=builtins >builtins\n    + '\n    + \n     +test_expect_success 'list of txt and help mismatches is sorted' '\n     +\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n     +\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\tfi\n     +'\n     +\n    -+builtin_to_synopsis () {\n    -+\tbuiltin=\"$1\" &&\n    -+\ttest_when_finished \"rm -f out\" &&\n    -+\ttest_expect_code 129 git $builtin -h >out 2>&1 &&\n    -+\tsed -n \\\n    -+\t\t-e '1,/^$/ {\n    -+\t\t\t/^$/d;\n    -+\t\t\ts/^usage: //;\n    -+\t\t\ts/^ *or: //;\n    -+\t\t\tp;\n    -+\t\t}' <out\n    -+}\n    -+\n    -+builtin_to_txt () {\n    -+\techo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n    -+}\n    -+\n    -+txt_synopsis () {\n    -+\tsed -n \\\n    -+\t\t-e '/^\\[verse\\]$/,/^$/ {\n    -+\t\t\t/^$/d;\n    -+\t\t\t/^\\[verse\\]$/d;\n    + help_to_synopsis () {\n    + \tbuiltin=\"$1\" &&\n    + \tout_dir=\"out/$builtin\" &&\n    +@@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {\n    + \t\t\t/^$/d;\n    + \t\t\t/^\\[verse\\]$/d;\n    + \n     +\t\t\ts/{litdd}/--/g;\n    -+\n     +\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n    -+\t\t\tp;\n    -+\t\t}' \\\n    -+\t\t<\"$1\"\n    -+}\n     +\n    -+HT=\"\t\"\n    + \t\t\tp;\n    + \t\t}' \\\n    + \t\t<\"$b2t\" >\"$out\" &&\n    +@@ t/t0450-txt-doc-vs-help.sh: check_dashed_labels () {\n    + \n    + HT=\"\t\"\n    + \n     +align_after_nl () {\n     +\tbuiltin=\"$1\" &&\n     +\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +}\n     +\n     +test_debug '>failing'\n    -+while read builtin\n    -+do\n    -+\ttest_expect_success \"$builtin -h output has no \\t\" '\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    -+\t\t! grep \"$HT\" help.raw\n    -+\t'\n    -+\n    -+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n    -+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n    -+\n    -+\tif test -f \"$txt\"\n    -+\tthen\n    -+\t\ttest_set_prereq \"$preq\"\n    -+\tfi &&\n    -+\n    + while read builtin\n    + do\n    + \t# -h output assertions\n    +@@ t/t0450-txt-doc-vs-help.sh: do\n    + \ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n    + \t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n    + \t'\n    ++\n    ++\t# *.txt output consistency assertions\n     +\tresult=\n     +\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n     +\tthen\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\telse\n     +\t\tresult=success\n     +\tfi &&\n    -+\n     +\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n    -+\t\ttxt_synopsis \"$txt\" >txt.raw &&\n    ++\t\tt2s=\"$(txt_to_synopsis \"$builtin\")\" &&\n     +\t\tif test \"$builtin\" = \"merge-tree\"\n     +\t\tthen\n    -+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <txt.raw >txt.raw.new &&\n    -+\t\t\tmv txt.raw.new txt.raw\n    ++\t\t\ttest_when_finished \"rm -f t2s.new\" &&\n    ++\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <\"$t2s\" >t2s.new\n    ++\t\t\tt2s=t2s.new\n     +\t\tfi &&\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    ++\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n     +\n     +\t\t# The *.txt and -h use different spacing for the\n     +\t\t# alignment of continued usage output, normalize it.\n    -+\t\talign_after_nl \"$builtin\" <txt.raw >txt &&\n    -+\t\talign_after_nl \"$builtin\" <help.raw >help &&\n    ++\t\talign_after_nl \"$builtin\" <\"$t2s\" >txt &&\n    ++\t\talign_after_nl \"$builtin\" <\"$h2s\" >help &&\n     +\t\ttest_cmp txt help\n     +\t'\n     +\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\t\t# used with --debug\n     +\t\trm -f txt help tmp 2>/dev/null\n     +\tfi\n    -+done <builtins\n    -+\n    + done <builtins\n    + \n     +test_debug 'say \"$(cat failing)\"'\n     +\n    -+test_done\n    + test_done\n     \n      ## t/t0450/txt-help-mismatches (new) ##\n     @@\n36:  b56113dd620 ! 34:  3443ae7ee6b tests: assert consistent whitespace in -h output\n    @@ Commit message\n                        [...]\n                [--create-reflog] [...]\n     \n    -    Which should instead be like this instead, i.e. the options lines\n    -    should be aligned:\n    +    Which should instead be like this, i.e. the options lines should be\n    +    aligned:\n     \n            [...]\n            or: git tag [-n[<num>]]\n    @@ Commit message\n     \n      ## t/t0450-txt-doc-vs-help.sh ##\n     @@ t/t0450-txt-doc-vs-help.sh: do\n    - \t\t! grep \"$HT\" help.raw\n    + \t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n      \t'\n      \n     +\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    ++\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n     +\t\tsed -n \\\n     +\t\t\t-e \"/^ / {\n     +\t\t\t\ts/[^ ].*//;\n     +\t\t\t\tp;\n     +\t\t\t}\" \\\n    -+\t\t\t<help.raw >help &&\n    ++\t\t\t<\"$h2s\" >help &&\n     +\t\tsort -u help >help.ws &&\n     +\t\tif test -s help.ws\n     +\t\tthen\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464134","messageId":"patch-v3-03.34-b7c98a40393-20221004T131009Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com","subject":"[PATCH v3 03/34] builtin/bundle.c: indent with tabs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:20:48Z","receivedAt":"2022-10-04T13:21:47Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464135","messageId":"patch-v4-01.34-f76804fe9ae-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 01/34] tests: assert *.txt SYNOPSIS and -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:15Z","receivedAt":"2022-10-04T13:23:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test to assert basic compliance with the CodingGuidelines in the\nSYNOPSIS and builtin -h output. For now we only assert that the \"-h\"\noutput doesn't have \"\\t\" characters, as a very basic syntax check.\n\nSubsequent commits will expand on the checks here as various issues\nare fixed, but let's first add the test scaffolding.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++\n 1 file changed, 44 insertions(+)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..c8820bdd38f\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,44 @@\n+#!/bin/sh\n+\n+test_description='assert (unbuilt) Documentation/*.txt and -h output'\n+\n+TEST_PASSES_SANITIZE_LEAK=true\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+help_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\tout_dir=\"out/$builtin\" &&\n+\tout=\"$out_dir/help.synopsis\" &&\n+\tif test -f \"$out\"\n+\tthen\n+\t\techo \"$out\" &&\n+\t\treturn 0\n+\tfi &&\n+\tmkdir -p \"$out_dir\" &&\n+\ttest_expect_code 129 git $builtin -h >\"$out.raw\" 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp;\n+\t\t}' <\"$out.raw\" >\"$out\" &&\n+\techo \"$out\"\n+}\n+\n+HT=\"\t\"\n+\n+while read builtin\n+do\n+\t# -h output assertions\n+\ttest_expect_success \"$builtin -h output has no \\t\" '\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\t\t! grep \"$HT\" \"$h2s\"\n+\t'\n+done <builtins\n+\n+test_done\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464136","messageId":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com","subject":"[PATCH v4 00/34] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:14Z","receivedAt":"2022-10-04T13:24:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"[I sent the first 3 patches & CL of this v4 as a \"v3\" in\nhttps://lore.kernel.org/git/cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com/;\nsorry. Here's the whole series, correctly labeled as v4]\n\nWe are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nFor the rest of the general overview (the first paragraphs are\ncopy/pasted) see the v1 at:\nhttps://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/ [1];\nFor v3 see:\nhttp://lore.kernel.org/git/cover-v3-00.36-00000000000-20220930T180414Z-avarab@gmail.com\n\nChanges since v3:\n\n * Added a commit to put a small portion of the the new tests first,\n   we then add a bit to it as we go along.\n\n * Squashed some changes as requested, now some of the \"doc txt & -h\n   consistency\" commits have changes that were previously split up,\n   but that's noted in the commit message.\n\n * Ejected the \"blame\" usage_msg_optf() change, instead the relevant\n   later commit just supports both usage() and usage_with_options().\n\n * Consistently use [<options>], not \"[<options...]\"\n\n * Various squshes/fix-ups suggested by Eric & Junio, thanks both!\n\n * The new test now runs much faster, since we cache the \"sed\"\n   commands that extract the \"-h\" and \"*.txt\" output\n\nÆvar Arnfjörð Bjarmason (34):\n  tests: assert *.txt SYNOPSIS and -h output\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: indent with tabs\n  bundle: define subcommand -h in terms of command -h\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n  tests: assert consistent whitespace in -h output\n\n Documentation/CodingGuidelines                |  14 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |   8 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   4 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   4 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   4 +-\n Documentation/git-reflog.txt                  |  17 +-\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-rev-list.txt                |   2 +-\n Documentation/git-send-pack.txt               |   5 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 +-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |  18 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  22 ++-\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 ++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 +++++---\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-commit.c                       |   2 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/verify-tag.c                          |   2 +-\n builtin/worktree.c                            | 110 ++++++++---\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 172 ++++++++++++++++++\n t/t0450/txt-help-mismatches                   |  58 ++++++\n 82 files changed, 593 insertions(+), 198 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n create mode 100644 t/t0450/txt-help-mismatches\n\nRange-diff against v3:\n -:  ----------- >  1:  f76804fe9ae tests: assert *.txt SYNOPSIS and -h output\n 1:  1611913e321 =  2:  c95d3b9ad42 CodingGuidelines: update and clarify command-line conventions\n 2:  b2d76494a34 =  3:  b7c98a40393 builtin/bundle.c: indent with tabs\n 3:  953a72abee1 =  4:  522d7fbb0a3 bundle: define subcommand -h in terms of command -h\n 4:  a8312c50f01 <  -:  ----------- blame: use a more detailed usage_msg_optf() error on bad -L\n 5:  ec977f7c8fe =  5:  ac437d4eee5 doc SYNOPSIS: don't use ' for subcommands\n 6:  b0ae035500c =  6:  f20cbb661c6 doc SYNOPSIS: consistently use ' for commands\n 8:  e9924890620 =  7:  ecdc14f6dfe built-ins: consistently add \"\\n\" between \"usage\" and options\n10:  1a02f7c76cd !  8:  1b9b6a91916 doc txt & -h consistency: word-wrap\n    @@ Commit message\n         doc txt & -h consistency: word-wrap\n     \n         Change the documentation and -h output for those built-in commands\n    -    where the *.txt and -h output didn't match as far as word-wrapping was\n    -    concerned.\n    +    where both the -h output and *.txt were lacking in word-wrapping.\n    +\n    +    There are many more built-ins that could use this treatment, this\n    +    change is narrowed to those where this whitespace change is needed to\n    +    make the -h and *.txt consistent in the end.\n    +\n    +    In the case of \"Documentation/git-hash-object.txt\" and\n    +    \"builtin/hash-object.c\" this is not a \"doc txt & -h consistency\"\n    +    change, as we're changing both versions, doing so here makes a\n    +    subsequent change smaller.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    + ## Documentation/git-hash-object.txt ##\n    +@@ Documentation/git-hash-object.txt: git-hash-object - Compute object ID and optionally creates a blob from a file\n    + SYNOPSIS\n    + --------\n    + [verse]\n    +-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n    ++'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n    ++\t\t[--stdin [--literally]] [--] <file>...\n    + 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n    + \n    + DESCRIPTION\n    +\n      ## Documentation/git-worktree.txt ##\n     @@ Documentation/git-worktree.txt: git-worktree - Manage multiple working trees\n      SYNOPSIS\n    @@ builtin/diagnose.c\n      };\n      \n     \n    + ## builtin/hash-object.c ##\n    +@@ builtin/hash-object.c: static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n    + int cmd_hash_object(int argc, const char **argv, const char *prefix)\n    + {\n    + \tstatic const char * const hash_object_usage[] = {\n    +-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n    ++\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n    ++\t\t   \"                [--stdin] [--] <file>...\"),\n    + \t\t\"git hash-object  --stdin-paths\",\n    + \t\tNULL\n    + \t};\n    +\n      ## builtin/init-db.c ##\n     @@ builtin/init-db.c: static int shared_callback(const struct option *opt, const char *arg, int unset)\n      }\n 7:  829bdf58499 !  9:  f4598ca1899 doc SYNOPSIS & -h: fix incorrect alternates syntax\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    doc SYNOPSIS & -h: fix incorrect alternates syntax\n    +    doc txt & -h consistency: fix incorrect alternates syntax\n     \n         Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n         \"[(-o | --option) <argument>]\", we were previously claiming that only\n         the long option accepted the \"<argument>\", which isn't what we meant.\n     \n    -    This issue has been with us in both the \"-h\" and *.txt versions since\n    -    bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n    +    This syntax issue for \"bugreport\" originated in\n    +    238b439d698 (bugreport: add tool to generate debugging info,\n    +    2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\n    +    create 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n    +    \"bugreport\" documentation and code.\n     \n    -    There are also issues with the alternates syntax for \"bugreport\" and\n    -    \"diagnose\", but in those cases only for one of *.c or *.txt, not\n    -    both. Those issues will be fixed in a subsequent \"consistency\" commit.\n    +    In the case of \"Documentation/git-stash.txt\" and \"builtin/stash.c\"\n    +    this is not a \"doc txt & -h consistency\" change, as we're changing\n    +    both versions, doing so here makes a subsequent change smaller.\n    +\n    +    In that case fix the incorrect \"[-o | --option <argument>]\" syntax,\n    +    which should be \"[(-o | --option) <argument>]\", we were previously\n    +    claiming that only the long option accepted the \"<argument>\", which\n    +    isn't what we meant.\n    +\n    +    The \"stash\" issue has been with us in both the \"-h\" and *.txt versions\n    +    since bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n    +\n    +    We could claim that this isn't a syntax issue if a \"vertical bar binds\n    +    tighter than option and its argument\", but such a rule would change\n    +    e.g. this \"cat-file\" SYNOPSIS example to mean something we don't:\n    +\n    +            ... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\n    +\n    +    We have various other examples where the post-image here is already\n    +    used, e.g. for \"format-patch\" (\"-o\"), \"grep\" (\"-m\"),\n    +    \"submodule\" (\"set-branch -b\") etc.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    @@ Documentation/git-stash.txt: stash index (e.g. the integer `n` is equivalent to\n      \tSave your local modifications to a new 'stash entry' and roll them\n      \tback to HEAD (in the working tree and in the index).\n     \n    + ## builtin/bugreport.c ##\n    +@@ builtin/bugreport.c: static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n    + }\n    + \n    + static const char * const bugreport_usage[] = {\n    +-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n    ++\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n    + \t   \"              [--diagnose[=<mode>]\"),\n    + \tNULL\n    + };\n    +\n    + ## builtin/diagnose.c ##\n    +@@\n    + #include \"diagnose.h\"\n    + \n    + static const char * const diagnose_usage[] = {\n    +-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n    ++\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n    + \t   \"             [--mode=<mode>]\"),\n    + \tNULL\n    + };\n    +\n      ## builtin/stash.c ##\n     @@ builtin/stash.c: static const char * const git_stash_usage[] = {\n      \tN_(\"git stash branch <branchname> [<stash>]\"),\n 9:  516af07e8a8 <  -:  ----------- doc SYNOPSIS & -h: word-wrap\n11:  7794c3d6ef5 <  -:  ----------- doc txt & -h consistency: fix incorrect alternates syntax\n12:  357a228000c = 10:  0e955f294cd doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n13:  57cbaee9826 = 11:  aa2f9325839 doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n14:  a29af2dcc4f = 12:  009a0e586e9 doc txt & -h consistency: correct padding around \"[]()\"\n15:  589705cf6fa = 13:  b568189532f stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n16:  db850539d2a ! 14:  e5cb5c91b82 doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n    @@ Commit message\n         In the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\n         to indicate that these are optional.\n     \n    +    In the case of \"t/helper/test-proc-receive.c\" there is no *.txt\n    +    version, making it the only hunk in this commit that's not a \"doc txt\n    +    & -h consistency\" change.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-mv.txt ##\n    @@ builtin/sparse-checkout.c\n      \tNULL\n      };\n      \n    +\n    + ## t/helper/test-proc-receive.c ##\n    +@@\n    + #include \"test-tool.h\"\n    + \n    + static const char *proc_receive_usage[] = {\n    +-\t\"test-tool proc-receive [<options>...]\",\n    ++\t\"test-tool proc-receive [<options>]\",\n    + \tNULL\n    + };\n    + \n17:  041aa64f3c7 ! 15:  403e7ceb449 t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n    @@ Metadata\n     Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Commit message ##\n    -    t/helper/test-proc-receive.c: use \"<options>\", not \"<options>...\"\n    +    doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n     \n    -    As in a preceding commit use \"<options>\", not \"<options>...\", in this\n    -    case there is no *.txt version, but let's fix this one too while we're\n    -    at it.\n    +    Change \"builtin/credential-cache--daemon.c\" to use \"<socket-path>\" not\n    +    \"<socket_path>\" in a placeholder label, almost all of our\n    +    documentation uses this form.\n    +\n    +    This is now consistent with the \"If a placeholder has multiple words,\n    +    they are separated by dashes\" guideline added in\n    +    9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's\n    +    add a now-passing test to assert that that's the case.\n    +\n    +    To do this we need to introduce a very sed-powered parser to extract\n    +    the SYNOPSIS from the *.txt, and handle not all commands with \"-h\"\n    +    having a corresponding *.txt (e.g. \"bisect--helper\"). We'll still want\n    +    to handle syntax edge cases in the *.txt in subsequent commits for\n    +    other checks, but let's do that then.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## t/helper/test-proc-receive.c ##\n    -@@\n    - #include \"test-tool.h\"\n    + ## builtin/credential-cache--daemon.c ##\n    +@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n    + \tconst char *socket_path;\n    + \tint ignore_sighup = 0;\n    + \tstatic const char *usage[] = {\n    +-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n    ++\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n    + \t\tNULL\n    + \t};\n    + \tint debug = 0;\n    +\n    + ## t/t0450-txt-doc-vs-help.sh ##\n    +@@ t/t0450-txt-doc-vs-help.sh: help_to_synopsis () {\n    + \techo \"$out\"\n    + }\n    + \n    ++builtin_to_txt () {\n    ++       echo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n    ++}\n    ++\n    ++txt_to_synopsis () {\n    ++\tbuiltin=\"$1\" &&\n    ++\tout_dir=\"out/$builtin\" &&\n    ++\tout=\"$out_dir/txt.synopsis\" &&\n    ++\tif test -f \"$out\"\n    ++\tthen\n    ++\t\techo \"$out\" &&\n    ++\t\treturn 0\n    ++\tfi &&\n    ++\tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n    ++\tsed -n \\\n    ++\t\t-e '/^\\[verse\\]$/,/^$/ {\n    ++\t\t\t/^$/d;\n    ++\t\t\t/^\\[verse\\]$/d;\n    ++\n    ++\t\t\tp;\n    ++\t\t}' \\\n    ++\t\t<\"$b2t\" >\"$out\" &&\n    ++\techo \"$out\"\n    ++}\n    ++\n    ++check_dashed_labels () {\n    ++\t! grep -E \"<[^>_-]+_\" \"$1\"\n    ++}\n    ++\n    + HT=\"\t\"\n      \n    - static const char *proc_receive_usage[] = {\n    --\t\"test-tool proc-receive [<options>...]\",\n    -+\t\"test-tool proc-receive [<options>]\",\n    - \tNULL\n    - };\n    + while read builtin\n    +@@ t/t0450-txt-doc-vs-help.sh: do\n    + \t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n    + \t\t! grep \"$HT\" \"$h2s\"\n    + \t'\n    ++\n    ++\ttest_expect_success \"$builtin -h output has dashed labels\" '\n    ++\t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n    ++\t'\n    ++\n    ++\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n    ++\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n    ++\n    ++\tif test -f \"$txt\"\n    ++\tthen\n    ++\t\ttest_set_prereq \"$preq\"\n    ++\tfi &&\n    ++\n    ++\t# *.txt output assertions\n    ++\ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n    ++\t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n    ++\t'\n    + done <builtins\n      \n    + test_done\n18:  3a439c4401d ! 16:  563ccaab6a9 doc txt & -h consistency: fix mismatching labels\n    @@ Commit message\n         corresponding -h output where our translatable labels didn't match\n         up.\n     \n    +    In some cases we need to adjust the prose that follows the SYNOPSIS\n    +    accordingly, as it refers back to the changed label.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-clean.txt ##\n    @@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu\n      example, be useful to remove all build products.\n      \n     -If any optional `<path>...` arguments are given, only those paths\n    +-are affected.\n     +If any optional `<pathspec>...` arguments are given, only those paths\n    - are affected.\n    ++that match the pathspec are affected.\n      \n      OPTIONS\n      -------\n    @@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - T\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-credential-cache--daemon.txt: DESCRIPTION\n    + NOTE: You probably don't want to invoke this command yourself; it is\n    + started automatically when you use linkgit:git-credential-cache[1].\n    + \n    +-This command listens on the Unix domain socket specified by `<socket>`\n    ++This command listens on the Unix domain socket specified by `<socket-path>`\n    + for `git-credential-cache` clients. Clients may store and retrieve\n    + credentials. Each credential is held for a timeout specified by the\n    + client; once no credentials are held, the daemon exits.\n     \n      ## Documentation/git-mv.txt ##\n     @@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a symlink\n    @@ Documentation/git-mv.txt: git-mv - Move or rename a file, a directory, or a syml\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-mv.txt: OPTIONS\n    + -------\n    + -f::\n    + --force::\n    +-\tForce renaming or moving of a file even if the target exists\n    ++\tForce renaming or moving of a file even if the <destination> exists.\n    + -k::\n    + \tSkip move or rename actions which would lead to an error\n    + \tcondition. An error happens when a source is neither existing nor\n     \n      ## Documentation/git-receive-pack.txt ##\n     @@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed into the repository\n    @@ Documentation/git-receive-pack.txt: git-receive-pack - Receive what is pushed in\n      \n      DESCRIPTION\n      -----------\n    +@@ Documentation/git-receive-pack.txt: its behavior, see linkgit:git-config[1].\n    + \n    + OPTIONS\n    + -------\n    +-<directory>::\n    ++<git-dir>::\n    + \tThe repository to sync into.\n    + \n    + --http-backend-info-refs::\n     \n      ## Documentation/git-tag.txt ##\n     @@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object signed with GPG\n    @@ Documentation/git-tag.txt: git-tag - Create, list, delete or verify a tag object\n      \t<tagname> [<commit> | <object>]\n      'git tag' -d <tagname>...\n      'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n    +@@ Documentation/git-tag.txt: to delete, list or verify tags.\n    + \n    + Unless `-f` is given, the named tag must not yet exist.\n    + \n    +-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command\n    ++If one of `-a`, `-s`, or `-u <key-id>` is passed, the command\n    + creates a 'tag' object, and requires a tag message.  Unless\n    + `-m <msg>` or `-F <file>` is given, an editor is started for the user to type\n    + in the tag message.\n    + \n    +-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`\n    ++If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`\n    + are absent, `-a` is implied.\n    + \n    + Otherwise, a tag reference that points directly at the given object\n    + (i.e., a lightweight tag) is created.\n    + \n    + A GnuPG signed tag object will be created when `-s` or `-u\n    +-<keyid>` is used.  When `-u <keyid>` is not used, the\n    ++<key-id>` is used.  When `-u <key-id>` is not used, the\n    + committer identity for the current user is used to find the\n    + GnuPG key for signing. \tThe configuration variable `gpg.program`\n    + is used to specify custom GnuPG binary.\n    +@@ Documentation/git-tag.txt: OPTIONS\n    + \tOverride `tag.gpgSign` configuration variable that is\n    + \tset to force each and every tag to be signed.\n    + \n    +--u <keyid>::\n    +---local-user=<keyid>::\n    ++-u <key-id>::\n    ++--local-user=<key-id>::\n    + \tMake a GPG-signed tag, using the given key.\n    + \n    + -f::\n    +@@ Documentation/git-tag.txt: This option is only applicable when listing tags without annotation lines.\n    + \tUse the given tag message (instead of prompting).\n    + \tIf multiple `-m` options are given, their values are\n    + \tconcatenated as separate paragraphs.\n    +-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n    ++\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n    + \tis given.\n    + \n    + -F <file>::\n    + --file=<file>::\n    + \tTake the tag message from the given file.  Use '-' to\n    + \tread the message from the standard input.\n    +-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n    ++\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n    + \tis given.\n    + \n    + -e::\n    +@@ Documentation/git-tag.txt: it in the repository configuration as follows:\n    + \n    + -------------------------------------\n    + [user]\n    +-    signingKey = <gpg-keyid>\n    ++    signingKey = <gpg-key_id>\n    + -------------------------------------\n    + \n    + `pager.tag` is only respected when listing tags, i.e., when `-l` is\n     \n      ## Documentation/git-upload-archive.txt ##\n     @@ Documentation/git-upload-archive.txt: git-upload-archive - Send archive back to git-archive\n    @@ builtin/commit-graph.c\n      \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n      \t   \"                       <split options>\")\n     \n    - ## builtin/credential-cache--daemon.c ##\n    -@@ builtin/credential-cache--daemon.c: int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n    - \tconst char *socket_path;\n    - \tint ignore_sighup = 0;\n    - \tstatic const char *usage[] = {\n    --\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n    -+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n    - \t\tNULL\n    - \t};\n    - \tint debug = 0;\n    -\n      ## builtin/for-each-repo.c ##\n     @@\n      #include \"string-list.h\"\n19:  3bfdd3fb79e ! 17:  e6ef67f1c4f doc txt & -h consistency: add or fix optional \"--\" syntax\n    @@ Commit message\n         inconsistent, or where we incorrectly stated in one but not the other\n         that the \"--\" was mandatory.\n     \n    +    In the case of \"rev-list\" both sides were wrong, as we we don't\n    +    require one or more paths if \"--\" is used, e.g. this is OK:\n    +\n    +            git rev-list HEAD --\n    +\n    +    That part of this change is not a \"doc txt & -h consistency\" change,\n    +    as we're changing both versions, doing so here makes both sides\n    +    consistent.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    + ## Documentation/git-rev-list.txt ##\n    +@@ Documentation/git-rev-list.txt: git-rev-list - Lists commit objects in reverse chronological order\n    + SYNOPSIS\n    + --------\n    + [verse]\n    +-'git rev-list' [<options>] <commit>... [[--] <path>...]\n    ++'git rev-list' [<options>] <commit>... [--] [<path>...]\n    + \n    + DESCRIPTION\n    + -----------\n    +\n      ## builtin/for-each-repo.c ##\n     @@\n      #include \"string-list.h\"\n    @@ builtin/rev-list.c\n      \n      static const char rev_list_usage[] =\n     -\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n    -+\"git rev-list [<options>] <commit>... [[--] <path>...]\\n\"\n    ++\"git rev-list [<options>] <commit>... [--] [<path>...]\\n\"\n      \"\\n\"\n      \"  limiting output:\\n\"\n      \"    --max-count=<n>\\n\"\n20:  98bdd0353cf = 18:  766bafcde05 doc txt & -h consistency: make output order consistent\n21:  1713227d497 ! 19:  fb95d7a9f86 doc txt & -h consistency: add missing options and labels\n    @@ Commit message\n          * We said \"opts\" or \"options\", but could instead enumerate\n            the (small) set of supported options\n     \n    -     * argument labels were missing entirely (ls-remote)\n    +     * Options that were missing entirely (ls-remote's --sort=<key>)\n     \n    -     * How we referred to an argument was inconsistent between the two,\n    -       e.g. <pack> v.s. <pack>.idx.\n    +       As we can specify \"--sort\" multiple times (it's backed by a\n    +       string-list\" it should really be \"[(--sort=<key>)...]\", which is\n    +       what \"git for-each-ref\" lists it as, but let's leave that issue for\n    +       a subsequent cleanup, and stop at making these consistent. Other\n    +       \"ref-filter.h\" users share the same issue, e.g. \"git-branch.txt\".\n    +\n    +     * For \"verify-tag\" and \"verify-commit\" we were missing the \"--raw\"\n    +       option.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    @@ Documentation/git-update-server-info.txt: $GIT_OBJECT_DIRECTORY/info directories\n     +-------\n     +-f::\n     +--force::\n    -+\tAllow adding otherwise ignored files.\n    ++\tupdate the info files from scratch.\n     +\n      OUTPUT\n      ------\n    @@ Documentation/git-verify-commit.txt: git-verify-commit - Check the GPG signature\n      --------\n      [verse]\n     -'git verify-commit' <commit>...\n    -+'git verify-commit' [-v | --verbose] <commit>...\n    ++'git verify-commit' [-v | --verbose] [--raw] <commit>...\n      \n      DESCRIPTION\n      -----------\n    @@ Documentation/git-verify-tag.txt: git-verify-tag - Check the GPG signature of ta\n      --------\n      [verse]\n     -'git verify-tag' [--format=<format>] <tag>...\n    -+'git verify-tag' [-v | --verbose] [--format=<format>] <tag>...\n    ++'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...\n      \n      DESCRIPTION\n      -----------\n    @@ builtin/upload-pack.c\n      };\n      \n     \n    + ## builtin/verify-commit.c ##\n    +@@\n    + #include \"gpg-interface.h\"\n    + \n    + static const char * const verify_commit_usage[] = {\n    +-\t\tN_(\"git verify-commit [-v | --verbose] <commit>...\"),\n    ++\t\tN_(\"git verify-commit [-v | --verbose] [--raw] <commit>...\"),\n    + \t\tNULL\n    + };\n    + \n    +\n    + ## builtin/verify-tag.c ##\n    +@@\n    + #include \"ref-filter.h\"\n    + \n    + static const char * const verify_tag_usage[] = {\n    +-\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] <tag>...\"),\n    ++\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...\"),\n    + \t\tNULL\n    + };\n    + \n    +\n      ## help.c ##\n     @@ help.c: int cmd_version(int argc, const char **argv, const char *prefix)\n      \tstruct strbuf buf = STRBUF_INIT;\n22:  702eb747c0f = 20:  729029f49c3 doc txt & -h consistency: make \"rerere\" consistent\n23:  01e20b8e452 ! 21:  2d4fdbd1aa1 doc txt & -h consistency: make \"read-tree\" consistent\n    @@ Metadata\n      ## Commit message ##\n         doc txt & -h consistency: make \"read-tree\" consistent\n     \n    -    The C version was right to use \"()\" in place of \"[]\", let's update\n    -    the *.txt version accordingly, and furthermore list the *.c options in\n    -    the same order as the *.txt.\n    +    The C version was right to use \"()\" in place of \"[]\" around the option\n    +    listing, let's update the *.txt version accordingly, and furthermore\n    +    list the *.c options in the same order as the *.txt.\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n24:  7f93da79fee = 22:  c3d227c17c6 doc txt & -h consistency: make \"bundle\" consistent\n25:  ab109f73264 ! 23:  02e450ea39b doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n    @@ Commit message\n         Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\n         receive-pack\" and \"git credential-cache--daemon\".\n     \n    +    For \"git-receive-pack\" we do have a binary with that name, even when\n    +    installed with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes\n    +    of the SYNOPSIS let's use the \"git cmd\" form like everywhere else. It\n    +    can be invoked like that (and our tests do so), the parts of our\n    +    documentation that explain when you need to use the dashed form do so,\n    +    and use it.\n    +\n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n      ## Documentation/git-receive-pack.txt ##\n26:  d57635b2707 = 24:  430d40d3083 doc txt & -h consistency: add missing options\n27:  ac959d0cfc1 = 25:  acd6e1f2632 doc txt & -h consistency: make \"stash\" consistent\n28:  f617375ea9e ! 26:  c02fc626542 doc txt & -h consistency: make \"annotate\" consistent\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \tlong anchor;\n      \tconst int hexsz = the_hash_algo->hexsz;\n      \tlong num_lines = 0;\n    -+\tconst char **usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n    ++\tconst char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;\n    ++\tconst char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n      \n      \tsetup_default_color_by_age();\n      \tgit_config(git_blame_config, &output_option);\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n      \tfor (;;) {\n     -\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n    -+\t\tswitch (parse_options_step(&ctx, options, usage)) {\n    ++\t\tswitch (parse_options_step(&ctx, options, opt_usage)) {\n      \t\tcase PARSE_OPT_NON_OPTION:\n      \t\tcase PARSE_OPT_UNKNOWN:\n      \t\t\tbreak;\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\treverse = 1;\n      \t\t}\n     -\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n    -+\t\tparse_revision_opt(&revs, &ctx, options, usage);\n    ++\t\tparse_revision_opt(&revs, &ctx, options, opt_usage);\n      \t}\n      parse_done:\n      \trevision_opts_finish(&revs);\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\tcase 2: /* (1b) */\n      \t\t\tif (argc != 4)\n     -\t\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\t\tusage_with_options(usage, options);\n    ++\t\t\t\tusage_with_options(opt_usage, options);\n      \t\t\t/* reorder for the new way: <rev> -- <path> */\n      \t\t\targv[1] = argv[3];\n      \t\t\targv[3] = argv[2];\n    @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n      \t\t\tbreak;\n      \t\tdefault:\n     -\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\tusage_with_options(usage, options);\n    ++\t\t\tusage_with_options(opt_usage, options);\n      \t\t}\n      \t} else {\n      \t\tif (argc < 2)\n     -\t\t\tusage_with_options(blame_opt_usage, options);\n    -+\t\t\tusage_with_options(usage, options);\n    ++\t\t\tusage_with_options(opt_usage, options);\n      \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n      \t\t\tpath = add_prefix(prefix, argv[1]);\n      \t\t\targv[1] = argv[2];\n     @@ builtin/blame.c: int cmd_blame(int argc, const char **argv, const char *prefix)\n    + \t\t\t\t    nth_line_cb, &sb, lno, anchor,\n      \t\t\t\t    &bottom, &top, sb.path,\n      \t\t\t\t    the_repository->index))\n    - \t\t\tusage_msg_optf(_(\"failed to parse -L argument '%s'\"),\n    --\t\t\t\t       blame_opt_usage, options, arg);\n    -+\t\t\t\t       usage, options, arg);\n    +-\t\t\tusage(blame_usage);\n    ++\t\t\tusage(str_usage);\n      \t\tif ((!lno && (top || bottom)) || lno < bottom)\n      \t\t\tdie(Q_(\"file %s has only %lu line\",\n      \t\t\t       \"file %s has only %lu lines\",\n29:  c96c3fc6d8d = 27:  d991b9ef611 doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n30:  34b778dd176 = 28:  dd7d2f0b167 doc txt & -h consistency: make \"diff-tree\" consistent\n31:  336fc749f1c = 29:  3c8154151f3 doc txt & -h consistency: make \"commit\" consistent\n32:  81024d1c3cd = 30:  2452157548b reflog doc: list real subcommands up-front\n33:  76e6b7d296a = 31:  dbcabff3421 worktree: define subcommand -h in terms of command -h\n34:  efd0c2c634d = 32:  ea82721b057 doc txt & -h consistency: make \"worktree\" consistent\n35:  22da68abce3 ! 33:  a2abf7a1161 tests: start asserting that *.txt SYNOPSIS matches -h output\n    @@ Commit message\n         testing.\n     \n         This adds such regression testing, we can parse out the SYNOPSIS\n    -    output with \"sed\", and is turns out it's relatively easy to normalize\n    +    output with \"sed\", and it turns out it's relatively easy to normalize\n         it and the \"-h\" output to match on another.\n     \n         We now ensure that we won't have regressions when it comes to the list\n    @@ Commit message\n            \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n            command we're running.\n     \n    -     * Likewise \"git stage -h\" shows \"git add\" usage, but should be aware\n    -       of what command it's running. The same for \"annotate\" and \"blame\".\n    -\n          * Commands which implement subcommands such as like\n            \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n            in a very different order in the *.txt and *.c. Fixing it would\n    -       require some verbose diffs, so it's been left alone for onw.\n    +       require some verbose diffs, so it's been left alone for now.\n     \n          * Commands such as \"format-patch\" have a very long argument list in\n            the *.txt, but just \"[<options>]\" in the *.c.\n    @@ Commit message\n     \n         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n     \n    - ## t/t0450-txt-doc-vs-help.sh (new) ##\n    + ## t/t0450-txt-doc-vs-help.sh ##\n     @@\n    -+#!/bin/sh\n    -+\n    -+test_description='compare (unbuilt) Documentation/*.txt to -h output\n    + #!/bin/sh\n    + \n    +-test_description='assert (unbuilt) Documentation/*.txt and -h output'\n    ++test_description='assert (unbuilt) Documentation/*.txt and -h output\n     +\n     +Run this with --debug to see a summary of where we still fail to make\n     +the two versions consistent with one another.'\n    -+\n    -+. ./test-lib.sh\n    -+\n    -+test_expect_success 'setup: list of builtins' '\n    -+\tgit --list-cmds=builtins >builtins\n    -+'\n    -+\n    + \n    + TEST_PASSES_SANITIZE_LEAK=true\n    + . ./test-lib.sh\n    +@@ t/t0450-txt-doc-vs-help.sh: test_expect_success 'setup: list of builtins' '\n    + \tgit --list-cmds=builtins >builtins\n    + '\n    + \n     +test_expect_success 'list of txt and help mismatches is sorted' '\n     +\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n     +\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\tfi\n     +'\n     +\n    -+builtin_to_synopsis () {\n    -+\tbuiltin=\"$1\" &&\n    -+\ttest_when_finished \"rm -f out\" &&\n    -+\ttest_expect_code 129 git $builtin -h >out 2>&1 &&\n    -+\tsed -n \\\n    -+\t\t-e '1,/^$/ {\n    -+\t\t\t/^$/d;\n    -+\t\t\ts/^usage: //;\n    -+\t\t\ts/^ *or: //;\n    -+\t\t\tp;\n    -+\t\t}' <out\n    -+}\n    -+\n    -+builtin_to_txt () {\n    -+\techo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n    -+}\n    -+\n    -+txt_synopsis () {\n    -+\tsed -n \\\n    -+\t\t-e '/^\\[verse\\]$/,/^$/ {\n    -+\t\t\t/^$/d;\n    -+\t\t\t/^\\[verse\\]$/d;\n    + help_to_synopsis () {\n    + \tbuiltin=\"$1\" &&\n    + \tout_dir=\"out/$builtin\" &&\n    +@@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {\n    + \t\t\t/^$/d;\n    + \t\t\t/^\\[verse\\]$/d;\n    + \n     +\t\t\ts/{litdd}/--/g;\n    -+\n     +\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n    -+\t\t\tp;\n    -+\t\t}' \\\n    -+\t\t<\"$1\"\n    -+}\n     +\n    -+HT=\"\t\"\n    + \t\t\tp;\n    + \t\t}' \\\n    + \t\t<\"$b2t\" >\"$out\" &&\n    +@@ t/t0450-txt-doc-vs-help.sh: check_dashed_labels () {\n    + \n    + HT=\"\t\"\n    + \n     +align_after_nl () {\n     +\tbuiltin=\"$1\" &&\n     +\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +}\n     +\n     +test_debug '>failing'\n    -+while read builtin\n    -+do\n    -+\ttest_expect_success \"$builtin -h output has no \\t\" '\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    -+\t\t! grep \"$HT\" help.raw\n    -+\t'\n    -+\n    -+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n    -+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n    -+\n    -+\tif test -f \"$txt\"\n    -+\tthen\n    -+\t\ttest_set_prereq \"$preq\"\n    -+\tfi &&\n    -+\n    + while read builtin\n    + do\n    + \t# -h output assertions\n    +@@ t/t0450-txt-doc-vs-help.sh: do\n    + \ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n    + \t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n    + \t'\n    ++\n    ++\t# *.txt output consistency assertions\n     +\tresult=\n     +\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n     +\tthen\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\telse\n     +\t\tresult=success\n     +\tfi &&\n    -+\n     +\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n    -+\t\ttxt_synopsis \"$txt\" >txt.raw &&\n    ++\t\tt2s=\"$(txt_to_synopsis \"$builtin\")\" &&\n     +\t\tif test \"$builtin\" = \"merge-tree\"\n     +\t\tthen\n    -+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <txt.raw >txt.raw.new &&\n    -+\t\t\tmv txt.raw.new txt.raw\n    ++\t\t\ttest_when_finished \"rm -f t2s.new\" &&\n    ++\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <\"$t2s\" >t2s.new\n    ++\t\t\tt2s=t2s.new\n     +\t\tfi &&\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    ++\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n     +\n     +\t\t# The *.txt and -h use different spacing for the\n     +\t\t# alignment of continued usage output, normalize it.\n    -+\t\talign_after_nl \"$builtin\" <txt.raw >txt &&\n    -+\t\talign_after_nl \"$builtin\" <help.raw >help &&\n    ++\t\talign_after_nl \"$builtin\" <\"$t2s\" >txt &&\n    ++\t\talign_after_nl \"$builtin\" <\"$h2s\" >help &&\n     +\t\ttest_cmp txt help\n     +\t'\n     +\n    @@ t/t0450-txt-doc-vs-help.sh (new)\n     +\t\t# used with --debug\n     +\t\trm -f txt help tmp 2>/dev/null\n     +\tfi\n    -+done <builtins\n    -+\n    + done <builtins\n    + \n     +test_debug 'say \"$(cat failing)\"'\n     +\n    -+test_done\n    + test_done\n     \n      ## t/t0450/txt-help-mismatches (new) ##\n     @@\n36:  b56113dd620 ! 34:  3443ae7ee6b tests: assert consistent whitespace in -h output\n    @@ Commit message\n                        [...]\n                [--create-reflog] [...]\n     \n    -    Which should instead be like this instead, i.e. the options lines\n    -    should be aligned:\n    +    Which should instead be like this, i.e. the options lines should be\n    +    aligned:\n     \n            [...]\n            or: git tag [-n[<num>]]\n    @@ Commit message\n     \n      ## t/t0450-txt-doc-vs-help.sh ##\n     @@ t/t0450-txt-doc-vs-help.sh: do\n    - \t\t! grep \"$HT\" help.raw\n    + \t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n      \t'\n      \n     +\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n    -+\t\tbuiltin_to_synopsis \"$builtin\" >help.raw &&\n    ++\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n     +\t\tsed -n \\\n     +\t\t\t-e \"/^ / {\n     +\t\t\t\ts/[^ ].*//;\n     +\t\t\t\tp;\n     +\t\t\t}\" \\\n    -+\t\t\t<help.raw >help &&\n    ++\t\t\t<\"$h2s\" >help &&\n     +\t\tsort -u help >help.ws &&\n     +\t\tif test -s help.ws\n     +\t\tthen\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464137","messageId":"patch-v4-02.34-c95d3b9ad42-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 02/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:16Z","receivedAt":"2022-10-04T13:24:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nHaving a space around \" | \" for flags, but not for flag values is\ninconsistent, but this style guide codifies existing\npatterns. Grepping shows that we don't have any instance matching the\nsecond \"Don't\" example:\n\n\tgit grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 9fca21cc5f9..3d3bdeba9e4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -650,8 +650,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -665,6 +665,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not immediately after opening or\n+ before closing a [] or () pair:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464138","messageId":"patch-v4-03.34-b7c98a40393-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 03/34] builtin/bundle.c: indent with tabs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:17Z","receivedAt":"2022-10-04T13:24:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464139","messageId":"patch-v4-04.34-522d7fbb0a3-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 04/34] bundle: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:18Z","receivedAt":"2022-10-04T13:24:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git bundle\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 29 +++++++++++++++++++----------\n 1 file changed, 19 insertions(+), 10 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 5c78894afd5..1b08700bf9e 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -11,31 +11,40 @@\n  * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n  */\n \n-static const char * const builtin_bundle_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-\tN_(\"git bundle verify [<options>] <file>\"),\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n-\tNULL\n+#define BUILTIN_BUNDLE_CREATE_USAGE \\\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n+\tN_(\"git bundle verify [<options>] <file>\")\n+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n+\tN_(\"git bundle list-heads <file> [<refname>...]\")\n+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n+\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\n+static char const * const builtin_bundle_usage[] = {\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n+\tNULL,\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-\tN_(\"git bundle verify [<options>] <file>\"),\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464140","messageId":"patch-v4-06.34-f20cbb661c6-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 06/34] doc SYNOPSIS: consistently use ' for commands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:20Z","receivedAt":"2022-10-04T13:24:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Most of our commands use ''-quotation only for the name of the command\nitself, and not its (optional) arguments. Let's do the same for these.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-export.txt     | 2 +-\n Documentation/git-sparse-checkout.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 1978dbdc6ad..4643ddbe68f 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [<options>]' | 'git fast-import'\n+'git fast-export' [<options>] | 'git fast-import'\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 3776705bf53..872436d7426 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [<options>]'\n+'git sparse-checkout' <subcommand> [<options>]\n \n \n DESCRIPTION\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464141","messageId":"patch-v4-05.34-ac437d4eee5-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 05/34] doc SYNOPSIS: don't use ' for subcommands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:19Z","receivedAt":"2022-10-04T13:24:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Almost all of our documentation doesn't use \"'\" syntax for\nsubcommands, but these did, let's make them consistent with the\nrest.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex db9d46edfa9..0537d4645be 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [<log-options>] [<ref>]\n+'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4cfc8833780..4b613d4140c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n \n DESCRIPTION\n -----------\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464142","messageId":"patch-v4-07.34-ecdc14f6dfe-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 07/34] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:21Z","receivedAt":"2022-10-04T13:24:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change commands in the \"diff\" family and \"rev-list\" to separate the\nusage information and option listing with an empty line.\n\nIn the case of \"git diff -h\" we did this already (but let's use a\nconsistent \"\\n\" pattern there), for the rest these are now consistent\nwith how the parse_options() API would emit usage.\n\nAs we'll see in a subsequent commit this also helps to make the \"git\n<cmd> -h\" output more easily machine-readable, as we can assume that\nthe usage information is separated from the options by an empty line.\n\nNote that \"COMMON_DIFF_OPTIONS_HELP\" starts with a \"\\n\", so the\nseeming omission of a \"\\n\" here is correct, the second one is provided\nby the macro.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-files.c | 1 +\n builtin/diff-index.c | 1 +\n builtin/diff-tree.c  | 1 +\n builtin/diff.c       | 3 ++-\n builtin/rev-list.c   | 1 +\n 5 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/diff-files.c b/builtin/diff-files.c\nindex 92cf6e1e922..096ea2fedbc 100644\n--- a/builtin/diff-files.c\n+++ b/builtin/diff-files.c\n@@ -15,6 +15,7 @@\n \n static const char diff_files_usage[] =\n \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_files(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 7d158af6b6d..e667cf52e7d 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -11,6 +11,7 @@\n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 116097a404a..23f58702fa0 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)\n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n \"  --cc          show combined diff for merge commits removing uninteresting hunks\\n\"\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 54bb3de964c..67760b67552 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =\n \"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>\\n\"\n-\"   or: git diff [<options>] --no-index [--] <path> <path>\\n\"\n+\"   or: git diff [<options>] --no-index [--] <path> <path>\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n static const char *blob_path(struct object_array_entry *entry)\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex fba6f5d51f3..f67e2b33555 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -21,6 +21,7 @@\n \n static const char rev_list_usage[] =\n \"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n \"    --max-age=<epoch>\\n\"\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464143","messageId":"patch-v4-09.34-f4598ca1899-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 09/34] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:23Z","receivedAt":"2022-10-04T13:24:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis syntax issue for \"bugreport\" originated in\n238b439d698 (bugreport: add tool to generate debugging info,\n2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\ncreate 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n\"bugreport\" documentation and code.\n\nIn the case of \"Documentation/git-stash.txt\" and \"builtin/stash.c\"\nthis is not a \"doc txt & -h consistency\" change, as we're changing\nboth versions, doing so here makes a subsequent change smaller.\n\nIn that case fix the incorrect \"[-o | --option <argument>]\" syntax,\nwhich should be \"[(-o | --option) <argument>]\", we were previously\nclaiming that only the long option accepted the \"<argument>\", which\nisn't what we meant.\n\nThe \"stash\" issue has been with us in both the \"-h\" and *.txt versions\nsince bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n\nWe could claim that this isn't a syntax issue if a \"vertical bar binds\ntighter than option and its argument\", but such a rule would change\ne.g. this \"cat-file\" SYNOPSIS example to mean something we don't:\n\n\t... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\n\nWe have various other examples where the post-image here is already\nused, e.g. for \"format-patch\" (\"-o\"), \"grep\" (\"-m\"),\n\"submodule\" (\"set-branch -b\") etc.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 6 +++---\n builtin/bugreport.c         | 2 +-\n builtin/diagnose.c          | 2 +-\n builtin/stash.c             | 6 +++---\n 4 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex c5d70918283..4856f452511 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -14,12 +14,12 @@ SYNOPSIS\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n+\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n \n DESCRIPTION\n -----------\n@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n COMMANDS\n --------\n \n-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>...]::\n+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>...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex faa268f3cfb..23170113cc8 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 28c394a62a5..474de9ec647 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 2274aae2556..51d40efaac7 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n \tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [-m|--message <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n \tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464144","messageId":"patch-v4-08.34-1b9b6a91916-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 08/34] doc txt & -h consistency: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:22Z","receivedAt":"2022-10-04T13:24:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere both the -h output and *.txt were lacking in word-wrapping.\n\nThere are many more built-ins that could use this treatment, this\nchange is narrowed to those where this whitespace change is needed to\nmake the -h and *.txt consistent in the end.\n\nIn the case of \"Documentation/git-hash-object.txt\" and\n\"builtin/hash-object.c\" this is not a \"doc txt & -h consistency\"\nchange, as we're changing both versions, doing so here makes a\nsubsequent change smaller.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-hash-object.txt | 3 ++-\n Documentation/git-worktree.txt    | 3 ++-\n builtin/bugreport.c               | 3 ++-\n builtin/commit-graph.c            | 8 ++++----\n builtin/commit-tree.c             | 4 ++--\n builtin/diagnose.c                | 3 ++-\n builtin/hash-object.c             | 3 ++-\n builtin/init-db.c                 | 3 ++-\n builtin/interpret-trailers.c      | 4 +++-\n builtin/read-tree.c               | 4 +++-\n builtin/show-branch.c             | 3 ++-\n builtin/show-ref.c                | 4 +++-\n 12 files changed, 29 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex df9e2c58bdb..58670ef12f7 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+\t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \n DESCRIPTION\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex ada30c86a7c..063d6eeb99d 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees\n SYNOPSIS\n --------\n [verse]\n-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n+\t\t   [-b <new-branch>] <path> [<commit-ish>]\n 'git worktree list' [-v | --porcelain [-z]]\n 'git worktree lock' [--reason <string>] <worktree>\n 'git worktree move' <worktree> <new-path>\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 530895be55f..faa268f3cfb 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]\"),\n+\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 51557fe786e..cd346f95f08 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -13,10 +13,10 @@\n \tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append] \" \\\n-\t   \"[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] \" \\\n-\t   \"[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] \" \\\n-\t   \"<split options>\")\n+\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n+\t   \"                       <split options>\")\n \n static const char * builtin_commit_graph_verify_usage[] = {\n \tBUILTIN_COMMIT_GRAPH_VERIFY_USAGE,\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 63ea3229333..e4b85d29d56 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,8 +15,8 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n-\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] \"\n-\t\t\"[(-F <file>)...] <tree>\"),\n+\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n+\t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 576e0e8e385..28c394a62a5 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,8 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]\"),\n+\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex fbae878c2b9..f7c16802f0c 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n+\t\t   \"                [--stdin] [--] <file>...\"),\n \t\t\"git hash-object  --stdin-paths\",\n \t\tNULL\n \t};\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 546f9c595e7..08ba006d55e 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n }\n \n static const char *const init_db_usage[] = {\n-\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]\"),\n+\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 84748eafc01..4cf0cf265dc 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -13,7 +13,9 @@\n #include \"config.h\"\n \n static const char * const git_interpret_trailers_usage[] = {\n-\tN_(\"git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]\"),\n+\tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n+\t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n+\t   \"                       [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 9f1f33e9546..b3a389e1b1f 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)\n }\n \n static const char * const read_tree_usage[] = {\n-\tN_(\"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+\tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n+\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n \ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex d3f5715e3e3..c013abaf942 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {\n     N_(\"git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\\n\"\n        \"                [--current] [--color[=<when>] | --no-color] [--sparse]\\n\"\n        \"                [--more=<n> | --list | --independent | --merge-base]\\n\"\n-       \"                [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\"),\n+       \"                [--no-name | --sha1-name] [--topics]\\n\"\n+       \"                [(<rev> | <glob>)...]\"),\n     N_(\"git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\"),\n     NULL\n };\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 48569061087..3af6a53ee97 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -9,7 +9,9 @@\n #include \"parse-options.h\"\n \n static const char * const show_ref_usage[] = {\n-\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]\"),\n+\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\\n\"\n+\t   \"             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\\n\"\n+\t   \"             [--heads] [--] [<pattern>...]\"),\n \tN_(\"git show-ref --exclude-existing[=<pattern>]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464145","messageId":"patch-v4-10.34-0e955f294cd-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 10/34] doc txt & -h consistency: add \"-z\" to cat-file \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:24Z","receivedAt":"2022-10-04T13:24:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited\ninput with `-z`, 2022-07-22), before that change the SYNOPSIS and \"-h\"\noutput were the same, but not afterwards.\n\nThat change followed a similar earlier divergence in\n473fa2df08d (Documentation: add --batch-command to cat-file synopsis,\n2022-04-07). Subsequent commits will fix this sort of thing more\nsystematically, but let's fix this one as a one-off.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/cat-file.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 989eee0bb4c..fa7bd891692 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] <object>\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t   \"             [--buffer] [--follow-symlinks] [--unordered]\\n\"\n-\t\t   \"             [--textconv | --filters]\"),\n+\t\t   \"             [--textconv | --filters] [-z]\"),\n \t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n \t\t   \"             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\"),\n \t\tNULL\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464146","messageId":"patch-v4-11.34-aa2f9325839-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 11/34] doc txt & -h consistency: balance unbalanced \"[\" and \"]\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:25Z","receivedAt":"2022-10-04T13:24:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\nin aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n2022-08-12): We need to close the \"[\" we opened. The\ncorresponding *.txt change did not have the same issue.\n\nThe \"help -h\" output then had one \"]\" too many, which is an issue\nintroduced in b40845293b5 (help: correct the usage string in -h and\ndocumentation, 2021-09-10).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/help.c      | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 23170113cc8..bb138161943 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n \n static const char * const bugreport_usage[] = {\n \tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n-\t   \"              [--diagnose[=<mode>]\"),\n+\t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 6f2796f211e..53f2812dfb1 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464147","messageId":"patch-v4-12.34-009a0e586e9-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 12/34] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:26Z","receivedAt":"2022-10-04T13:24:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-diff-files.txt     | 2 +-\n Documentation/git-hash-object.txt    | 2 +-\n Documentation/git-merge-base.txt     | 4 ++--\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-prune-packed.txt   | 2 +-\n Documentation/git-rerere.txt         | 2 +-\n Documentation/git-send-pack.txt      | 2 +-\n Documentation/git-show-branch.txt    | 4 ++--\n Documentation/git-show-ref.txt       | 4 ++--\n Documentation/git-var.txt            | 2 +-\n Documentation/git-verify-pack.txt    | 2 +-\n builtin/bugreport.c                  | 2 +-\n builtin/commit-graph.c               | 2 +-\n builtin/diagnose.c                   | 2 +-\n builtin/sparse-checkout.c            | 2 +-\n 15 files changed, 18 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex bf1febb9ae7..591e3801b7b 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex 58670ef12f7..472b5bb995b 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]\n \t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b01ba3d3565 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n+'git merge-base' [-a | --all] <commit> <commit>...\n+'git merge-base' [-a | --all] --octopus <commit>...\n 'git merge-base' --is-ancestor <commit> <commit>\n 'git merge-base' --independent <commit>...\n 'git merge-base' --fork-point <ref> [<commit>]\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e52..dda80a740c8 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 9fed59a3172..844d6f808a0 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n SYNOPSIS\n --------\n [verse]\n-'git prune-packed' [-n|--dry-run] [-q|--quiet]\n+'git prune-packed' [-n | --dry-run] [-q | --quiet]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4b613d4140c..9d0e6f53e7e 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex be41f119740..e0c71623432 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n-\t\t[--[no-]signed|--signed=(true|false|if-asked)]\n+\t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\n \n DESCRIPTION\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex e5ec6b467f9..71f608b1ff1 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits\n SYNOPSIS\n --------\n [verse]\n-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n \t\t[(<rev> | <glob>)...]\n-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ab4d271925d..d1d56f68b43 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository\n SYNOPSIS\n --------\n [verse]\n-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]\n-\t     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]\n+\t     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n \t     [--heads] [--] [<pattern>...]\n 'git show-ref' --exclude-existing[=<pattern>]\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex 387cc1b9142..6aa521fab23 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -9,7 +9,7 @@ git-var - Show a Git logical variable\n SYNOPSIS\n --------\n [verse]\n-'git var' ( -l | <variable> )\n+'git var' (-l | <variable>)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c20..b8720dce8ab 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files\n SYNOPSIS\n --------\n [verse]\n-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n \n \n DESCRIPTION\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex bb138161943..61d93383f51 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex cd346f95f08..13cbb75ca28 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -14,7 +14,7 @@\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n \tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n-\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 474de9ec647..d52015c67a4 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 287716db68e..aac0f708e42 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init|list|set|add|reapply|disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464148","messageId":"patch-v4-13.34-b568189532f-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 13/34] stash doc SYNOPSIS & -h: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:27Z","receivedAt":"2022-10-04T13:25:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 12 ++++++------\n builtin/stash.c             | 28 ++++++++++++++--------------\n 2 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 4856f452511..ea16d2eae7c 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,17 +9,17 @@ SYNOPSIS\n --------\n [verse]\n 'git stash' list [<log-options>]\n-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n-'git stash' drop [-q|--quiet] [<stash>]\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n+'git stash' drop [-q | --quiet] [<stash>]\n+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 51d40efaac7..d91cf5fd3e1 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -24,16 +24,16 @@\n static const char * const git_stash_usage[] = {\n \tN_(\"git stash list [<options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n-\tN_(\"git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n-\tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"               [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464149","messageId":"patch-v4-14.34-e5cb5c91b82-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 14/34] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:28Z","receivedAt":"2022-10-04T13:25:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"It's arguably more correct to say \"[<option>...]\" than either of these\nforms, but the vast majority of our documentation uses the\n\"[<options>]\" form to indicate an arbitrary number of options, let's\ndo the same in these cases, which were the odd ones out.\n\nIn the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\nto indicate that these are optional.\n\nIn the case of \"t/helper/test-proc-receive.c\" there is no *.txt\nversion, making it the only hunk in this commit that's not a \"doc txt\n& -h consistency\" change.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-mv.txt     | 2 +-\n Documentation/git-status.txt | 2 +-\n builtin/pack-objects.c       | 4 ++--\n builtin/sparse-checkout.c    | 2 +-\n t/helper/test-proc-receive.c | 2 +-\n 5 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 79449bf98fe..972a055fbd8 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' <options>... <args>...\n+'git mv' [<options>] <args>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 54a4b29b473..5e438a7fdc1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -9,7 +9,7 @@ git-status - Show the working tree status\n SYNOPSIS\n --------\n [verse]\n-'git status' [<options>...] [--] [<pathspec>...]\n+'git status' [<options>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3658c05cafc..573d0b20b76 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,\n #define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)\n \n static const char *pack_usage[] = {\n-\tN_(\"git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]\"),\n-\tN_(\"git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex aac0f708e42..58a22503f04 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n \tNULL\n };\n \ndiff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\nindex cc08506cf0b..a4b305f4947 100644\n--- a/t/helper/test-proc-receive.c\n+++ b/t/helper/test-proc-receive.c\n@@ -6,7 +6,7 @@\n #include \"test-tool.h\"\n \n static const char *proc_receive_usage[] = {\n-\t\"test-tool proc-receive [<options>...]\",\n+\t\"test-tool proc-receive [<options>]\",\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464150","messageId":"patch-v4-15.34-403e7ceb449-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 15/34] doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:29Z","receivedAt":"2022-10-04T13:25:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change \"builtin/credential-cache--daemon.c\" to use \"<socket-path>\" not\n\"<socket_path>\" in a placeholder label, almost all of our\ndocumentation uses this form.\n\nThis is now consistent with the \"If a placeholder has multiple words,\nthey are separated by dashes\" guideline added in\n9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's\nadd a now-passing test to assert that that's the case.\n\nTo do this we need to introduce a very sed-powered parser to extract\nthe SYNOPSIS from the *.txt, and handle not all commands with \"-h\"\nhaving a corresponding *.txt (e.g. \"bisect--helper\"). We'll still want\nto handle syntax edge cases in the *.txt in subsequent commits for\nother checks, but let's do that then.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/credential-cache--daemon.c |  2 +-\n t/t0450-txt-doc-vs-help.sh         | 46 ++++++++++++++++++++++++++++++\n 2 files changed, 47 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex 4c6c89ab0de..ca672a6a619 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex c8820bdd38f..efd00cfc51a 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -30,6 +30,35 @@ help_to_synopsis () {\n \techo \"$out\"\n }\n \n+builtin_to_txt () {\n+       echo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n+}\n+\n+txt_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\tout_dir=\"out/$builtin\" &&\n+\tout=\"$out_dir/txt.synopsis\" &&\n+\tif test -f \"$out\"\n+\tthen\n+\t\techo \"$out\" &&\n+\t\treturn 0\n+\tfi &&\n+\tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tsed -n \\\n+\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\t/^\\[verse\\]$/d;\n+\n+\t\t\tp;\n+\t\t}' \\\n+\t\t<\"$b2t\" >\"$out\" &&\n+\techo \"$out\"\n+}\n+\n+check_dashed_labels () {\n+\t! grep -E \"<[^>_-]+_\" \"$1\"\n+}\n+\n HT=\"\t\"\n \n while read builtin\n@@ -39,6 +68,23 @@ do\n \t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n \t\t! grep \"$HT\" \"$h2s\"\n \t'\n+\n+\ttest_expect_success \"$builtin -h output has dashed labels\" '\n+\t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n+\t'\n+\n+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n+\n+\tif test -f \"$txt\"\n+\tthen\n+\t\ttest_set_prereq \"$preq\"\n+\tfi &&\n+\n+\t# *.txt output assertions\n+\ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n+\t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n+\t'\n done <builtins\n \n test_done\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464151","messageId":"patch-v4-17.34-e6ef67f1c4f-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 17/34] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:31Z","receivedAt":"2022-10-04T13:25:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add the \"[--]\" for those cases where the *.txt and -h were\ninconsistent, or where we incorrectly stated in one but not the other\nthat the \"--\" was mandatory.\n\nIn the case of \"rev-list\" both sides were wrong, as we we don't\nrequire one or more paths if \"--\" is used, e.g. this is OK:\n\n\tgit rev-list HEAD --\n\nThat part of this change is not a \"doc txt & -h consistency\" change,\nas we're changing both versions, doing so here makes both sides\nconsistent.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rev-list.txt | 2 +-\n builtin/for-each-repo.c        | 2 +-\n builtin/rev-list.c             | 2 +-\n builtin/verify-pack.c          | 2 +-\n 4 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 20bb8e82176..51029a22715 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order\n SYNOPSIS\n --------\n [verse]\n-'git rev-list' [<options>] <commit>... [[--] <path>...]\n+'git rev-list' [<options>] <commit>... [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex c6379b783c8..d45d873f579 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n+\tN_(\"git for-each-repo --config=<config> [--] <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex ada68a4af5e..3acd93f71e1 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [--] [<path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex db9ac5c4606..27d6f75fd8a 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464152","messageId":"patch-v4-16.34-563ccaab6a9-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:30Z","receivedAt":"2022-10-04T13:25:10Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various inconsistencies between command SYNOPSIS and the\ncorresponding -h output where our translatable labels didn't match\nup.\n\nIn some cases we need to adjust the prose that follows the SYNOPSIS\naccordingly, as it refers back to the changed label.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt                    |  8 ++++----\n Documentation/git-credential-cache--daemon.txt |  4 ++--\n Documentation/git-mv.txt                       |  4 ++--\n Documentation/git-receive-pack.txt             |  4 ++--\n Documentation/git-tag.txt                      | 18 +++++++++---------\n Documentation/git-upload-archive.txt           |  4 ++--\n builtin/bugreport.c                            |  2 +-\n builtin/clean.c                                |  2 +-\n builtin/commit-graph.c                         |  4 ++--\n builtin/for-each-repo.c                        |  2 +-\n builtin/pack-redundant.c                       |  2 +-\n builtin/rerere.c                               |  2 +-\n builtin/rev-list.c                             |  2 +-\n builtin/stash.c                                |  2 +-\n builtin/unpack-file.c                          |  2 +-\n builtin/upload-archive.c                       |  2 +-\n builtin/verify-pack.c                          |  2 +-\n builtin/worktree.c                             |  2 +-\n 18 files changed, 34 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 91742633fa8..61b6d8667a4 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\n-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n \n DESCRIPTION\n -----------\n@@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n \n-If any optional `<path>...` arguments are given, only those paths\n-are affected.\n+If any optional `<pathspec>...` arguments are given, only those paths\n+that match the pathspec are affected.\n \n OPTIONS\n -------\n -d::\n-\tNormally, when no <path> is specified, git clean will not\n+\tNormally, when no <pathspec> is specified, git clean will not\n \trecurse into untracked directories to avoid removing too much.\n \tSpecify -d to have it recurse into such directories as well.\n \tIf any paths are specified, -d is irrelevant; all untracked\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 01e1c214dd8..650a15a7edf 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\n@@ -16,7 +16,7 @@ DESCRIPTION\n NOTE: You probably don't want to invoke this command yourself; it is\n started automatically when you use linkgit:git-credential-cache[1].\n \n-This command listens on the Unix domain socket specified by `<socket>`\n+This command listens on the Unix domain socket specified by `<socket-path>`\n for `git-credential-cache` clients. Clients may store and retrieve\n credentials. Each credential is held for a timeout specified by the\n client; once no credentials are held, the daemon exits.\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 972a055fbd8..fb0220fd18d 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [<options>] <args>...\n+'git mv' [<options>] <source>... <destination>\n \n DESCRIPTION\n -----------\n@@ -30,7 +30,7 @@ OPTIONS\n -------\n -f::\n --force::\n-\tForce renaming or moving of a file even if the target exists\n+\tForce renaming or moving of a file even if the <destination> exists.\n -k::\n \tSkip move or rename actions which would lead to an error\n \tcondition. An error happens when a source is neither existing nor\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 014a78409b9..5c297db1a4b 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\n@@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1].\n \n OPTIONS\n -------\n-<directory>::\n+<git-dir>::\n \tThe repository to sync into.\n \n --http-backend-info-refs::\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31a97a1b6c5..fdc72b5875a 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n \t<tagname> [<commit> | <object>]\n 'git tag' -d <tagname>...\n 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n@@ -26,19 +26,19 @@ to delete, list or verify tags.\n \n Unless `-f` is given, the named tag must not yet exist.\n \n-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command\n+If one of `-a`, `-s`, or `-u <key-id>` is passed, the command\n creates a 'tag' object, and requires a tag message.  Unless\n `-m <msg>` or `-F <file>` is given, an editor is started for the user to type\n in the tag message.\n \n-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`\n+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`\n are absent, `-a` is implied.\n \n Otherwise, a tag reference that points directly at the given object\n (i.e., a lightweight tag) is created.\n \n A GnuPG signed tag object will be created when `-s` or `-u\n-<keyid>` is used.  When `-u <keyid>` is not used, the\n+<key-id>` is used.  When `-u <key-id>` is not used, the\n committer identity for the current user is used to find the\n GnuPG key for signing. \tThe configuration variable `gpg.program`\n is used to specify custom GnuPG binary.\n@@ -72,8 +72,8 @@ OPTIONS\n \tOverride `tag.gpgSign` configuration variable that is\n \tset to force each and every tag to be signed.\n \n--u <keyid>::\n---local-user=<keyid>::\n+-u <key-id>::\n+--local-user=<key-id>::\n \tMake a GPG-signed tag, using the given key.\n \n -f::\n@@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines.\n \tUse the given tag message (instead of prompting).\n \tIf multiple `-m` options are given, their values are\n \tconcatenated as separate paragraphs.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n+\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n \tis given.\n \n -F <file>::\n --file=<file>::\n \tTake the tag message from the given file.  Use '-' to\n \tread the message from the standard input.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n+\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n \tis given.\n \n -e::\n@@ -220,7 +220,7 @@ it in the repository configuration as follows:\n \n -------------------------------------\n [user]\n-    signingKey = <gpg-keyid>\n+    signingKey = <gpg-key_id>\n -------------------------------------\n \n `pager.tag` is only respected when listing tags, i.e., when `-l` is\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex fba0f1c1b27..e8eb10baad7 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n SYNOPSIS\n --------\n [verse]\n-'git upload-archive' <directory>\n+'git upload-archive' <repository>\n \n DESCRIPTION\n -----------\n@@ -54,7 +54,7 @@ access via non-smart-http.\n \n OPTIONS\n -------\n-<directory>::\n+<repository>::\n \tThe repository to get a tar archive from.\n \n GIT\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 61d93383f51..96052541cbf 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 5466636e666..6f039f555b2 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 13cbb75ca28..e8f77f535f3 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -10,10 +10,10 @@\n #include \"tag.h\"\n \n #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n-\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n+\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n \t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex fd86e5a8619..c6379b783c8 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <command-args>\"),\n+\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c\nindex ed9b9013a5f..ecd49ca268f 100644\n--- a/builtin/pack-redundant.c\n+++ b/builtin/pack-redundant.c\n@@ -14,7 +14,7 @@\n #define BLKSIZE 512\n \n static const char pack_redundant_usage[] =\n-\"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)\";\n+\"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\";\n \n static int load_all_packs, verbose, alt_odb;\n \ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 83d7a778e37..12570537d37 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <path>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n \tNULL,\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex f67e2b33555..ada68a4af5e 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex d91cf5fd3e1..83c9591ea6d 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -22,7 +22,7 @@\n #define INCLUDE_ALL_FILES 2\n \n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tN_(\"git stash list [<log-options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n \tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\ndiff --git a/builtin/unpack-file.c b/builtin/unpack-file.c\nindex 58652229f27..9e8119dd354 100644\n--- a/builtin/unpack-file.c\n+++ b/builtin/unpack-file.c\n@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)\n \tstruct object_id oid;\n \n \tif (argc != 2 || !strcmp(argv[1], \"-h\"))\n-\t\tusage(\"git unpack-file <sha1>\");\n+\t\tusage(\"git unpack-file <blob>\");\n \tif (get_oid(argv[1], &oid))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n \ndiff --git a/builtin/upload-archive.c b/builtin/upload-archive.c\nindex 98d028dae67..945ee2b4126 100644\n--- a/builtin/upload-archive.c\n+++ b/builtin/upload-archive.c\n@@ -10,7 +10,7 @@\n #include \"strvec.h\"\n \n static const char upload_archive_usage[] =\n-\t\"git upload-archive <repo>\";\n+\t\"git upload-archive <repository>\";\n \n static const char deadchild[] =\n \"git upload-archive: archiver died with error\";\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex 05c52135946..db9ac5c4606 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n \tNULL\n };\n \ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex c6710b25520..5bfc18e5a24 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {\n \tN_(\"git worktree prune [<options>]\"),\n \tN_(\"git worktree remove [<options>] <worktree>\"),\n \tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <path>\"),\n+\tN_(\"git worktree unlock <worktree>\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464153","messageId":"patch-v4-18.34-766bafcde05-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 18/34] doc txt & -h consistency: make output order consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:32Z","receivedAt":"2022-10-04T13:25:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix cases where the SYNOPSIS and -h output was presented in a\ndifferent order.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/merge-base.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex a11f8c6e4bb..6f3941f2a49 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n static const char * const merge_base_usage[] = {\n \tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n \tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n+\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464154","messageId":"patch-v4-19.34-fb95d7a9f86-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 19/34] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:33Z","receivedAt":"2022-10-04T13:25:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various issues of SYNOPSIS and -h output syntax where:\n\n * Options such as --force were missing entirely\n * ...or the short option, such as -f\n\n * We said \"opts\" or \"options\", but could instead enumerate\n   the (small) set of supported options\n\n * Options that were missing entirely (ls-remote's --sort=<key>)\n\n   As we can specify \"--sort\" multiple times (it's backed by a\n   string-list\" it should really be \"[(--sort=<key>)...]\", which is\n   what \"git for-each-ref\" lists it as, but let's leave that issue for\n   a subsequent cleanup, and stop at making these consistent. Other\n   \"ref-filter.h\" users share the same issue, e.g. \"git-branch.txt\".\n\n * For \"verify-tag\" and \"verify-commit\" we were missing the \"--raw\"\n   option.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-send-pack.txt          |  3 ++-\n Documentation/git-sparse-checkout.txt    |  2 +-\n Documentation/git-update-server-info.txt |  8 +++++++-\n Documentation/git-verify-commit.txt      |  2 +-\n Documentation/git-verify-tag.txt         |  2 +-\n builtin/credential-cache--daemon.c       |  2 +-\n builtin/describe.c                       |  5 +++--\n builtin/diff-index.c                     |  2 +-\n builtin/ls-remote.c                      |  2 +-\n builtin/pack-refs.c                      |  2 +-\n builtin/revert.c                         |  9 +++++----\n builtin/send-pack.c                      |  1 +\n builtin/symbolic-ref.c                   |  5 +++--\n builtin/tag.c                            | 10 ++++++----\n builtin/update-server-info.c             |  2 +-\n builtin/upload-pack.c                    |  3 ++-\n builtin/verify-commit.c                  |  2 +-\n builtin/verify-tag.c                     |  2 +-\n help.c                                   |  2 +-\n 19 files changed, 40 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex e0c71623432..595b002152f 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n+'git send-pack' [--mirror] [--dry-run] [--force]\n+\t\t[--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n \t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 872436d7426..68392d2a56e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout' <subcommand> [<options>]\n+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\nindex 969bb2e15f1..17e429dbd09 100644\n--- a/Documentation/git-update-server-info.txt\n+++ b/Documentation/git-update-server-info.txt\n@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n SYNOPSIS\n --------\n [verse]\n-'git update-server-info'\n+'git update-server-info' [-f | --force]\n \n DESCRIPTION\n -----------\n@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n what references and packs the server has.  This command\n generates such auxiliary files.\n \n+OPTIONS\n+-------\n+-f::\n+--force::\n+\tupdate the info files from scratch.\n+\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\nindex 92097f6673d..aee4c40eac4 100644\n--- a/Documentation/git-verify-commit.txt\n+++ b/Documentation/git-verify-commit.txt\n@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n SYNOPSIS\n --------\n [verse]\n-'git verify-commit' <commit>...\n+'git verify-commit' [-v | --verbose] [--raw] <commit>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\nindex 0b8075dad96..81d50ecc4c6 100644\n--- a/Documentation/git-verify-tag.txt\n+++ b/Documentation/git-verify-tag.txt\n@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n SYNOPSIS\n --------\n [verse]\n-'git verify-tag' [--format=<format>] <tag>...\n+'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex ca672a6a619..d4eb0097d24 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n+\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex e17c4b4c69b..23e3f05fb10 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -23,8 +23,9 @@\n define_commit_slab(commit_names, struct commit_name *);\n \n static const char * const describe_usage[] = {\n-\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n-\tN_(\"git describe [<options>] --dirty\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n+\tN_(\"git describe <blob>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex e667cf52e7d..aea139b9d8f 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -9,7 +9,7 @@\n #include \"submodule.h\"\n \n static const char diff_cache_usage[] =\n-\"git diff-index [-m] [--cached] \"\n+\"git diff-index [-m] [--cached] [--merge-base] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n \"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex df44e5cc0d1..5d5ac038716 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -7,7 +7,7 @@\n \n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n-\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n+\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n \t   \"              [--symref] [<repository> [<refs>...]]\"),\n \tNULL\n };\ndiff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\nindex cfbd5c36c76..27c2ca06acb 100644\n--- a/builtin/pack-refs.c\n+++ b/builtin/pack-refs.c\n@@ -5,7 +5,7 @@\n #include \"repository.h\"\n \n static char const * const pack_refs_usage[] = {\n-\tN_(\"git pack-refs [<options>]\"),\n+\tN_(\"git pack-refs [--all] [--no-prune]\"),\n \tNULL\n };\n \ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex ee2a0807f01..ee32c714a76 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -21,14 +21,15 @@\n  */\n \n static const char * const revert_usage[] = {\n-\tN_(\"git revert [<options>] <commit-ish>...\"),\n-\tN_(\"git revert <subcommand>\"),\n+\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n-\tN_(\"git cherry-pick <subcommand>\"),\n+\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n+\t   \"                [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \ndiff --git a/builtin/send-pack.c b/builtin/send-pack.c\nindex 64962be0168..4c5d125fa0a 100644\n--- a/builtin/send-pack.c\n+++ b/builtin/send-pack.c\n@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n+\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n \tNULL,\n };\ndiff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\nindex 1b0f10225f0..50b6df78df0 100644\n--- a/builtin/symbolic-ref.c\n+++ b/builtin/symbolic-ref.c\n@@ -5,8 +5,9 @@\n #include \"parse-options.h\"\n \n static const char * const git_symbolic_ref_usage[] = {\n-\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n-\tN_(\"git symbolic-ref -d [-q] <name>\"),\n+\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n+\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n+\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n \tNULL\n };\n \ndiff --git a/builtin/tag.c b/builtin/tag.c\nindex 75dece0e4f1..d428c45dc8d 100644\n--- a/builtin/tag.c\n+++ b/builtin/tag.c\n@@ -23,11 +23,13 @@\n #include \"date.h\"\n \n static const char * const git_tag_usage[] = {\n-\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n-\t   \"        <tagname> [<head>]\"),\n+\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n+\t   \"        <tagname> [<commit> | <object>]\"),\n \tN_(\"git tag -d <tagname>...\"),\n-\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n-\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n+\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n+\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n+\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n+\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n \tNULL\n };\ndiff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\nindex 880fffec587..d2239c9ef4d 100644\n--- a/builtin/update-server-info.c\n+++ b/builtin/update-server-info.c\n@@ -4,7 +4,7 @@\n #include \"parse-options.h\"\n \n static const char * const update_server_info_usage[] = {\n-\t\"git update-server-info [--force]\",\n+\t\"git update-server-info [-f | --force]\",\n \tNULL\n };\n \ndiff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\nindex 125af53885f..25b69da2bf2 100644\n--- a/builtin/upload-pack.c\n+++ b/builtin/upload-pack.c\n@@ -8,7 +8,8 @@\n #include \"serve.h\"\n \n static const char * const upload_pack_usage[] = {\n-\tN_(\"git upload-pack [<options>] <dir>\"),\n+\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n+\t   \"                [--advertise-refs] <directory>\"),\n \tNULL\n };\n \ndiff --git a/builtin/verify-commit.c b/builtin/verify-commit.c\nindex 40c69a0bedd..3ebad32b0f1 100644\n--- a/builtin/verify-commit.c\n+++ b/builtin/verify-commit.c\n@@ -16,7 +16,7 @@\n #include \"gpg-interface.h\"\n \n static const char * const verify_commit_usage[] = {\n-\t\tN_(\"git verify-commit [-v | --verbose] <commit>...\"),\n+\t\tN_(\"git verify-commit [-v | --verbose] [--raw] <commit>...\"),\n \t\tNULL\n };\n \ndiff --git a/builtin/verify-tag.c b/builtin/verify-tag.c\nindex f45136a06ba..217566952d8 100644\n--- a/builtin/verify-tag.c\n+++ b/builtin/verify-tag.c\n@@ -15,7 +15,7 @@\n #include \"ref-filter.h\"\n \n static const char * const verify_tag_usage[] = {\n-\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] <tag>...\"),\n+\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...\"),\n \t\tNULL\n };\n \ndiff --git a/help.c b/help.c\nindex d04542d8261..f1e090a4428 100644\n--- a/help.c\n+++ b/help.c\n@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \tstruct strbuf buf = STRBUF_INIT;\n \tint build_options = 0;\n \tconst char * const usage[] = {\n-\t\tN_(\"git version [<options>]\"),\n+\t\tN_(\"git version [--build-options]\"),\n \t\tNULL\n \t};\n \tstruct option options[] = {\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464155","messageId":"patch-v4-20.34-729029f49c3-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 20/34] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:34Z","receivedAt":"2022-10-04T13:25:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\nthe order that they're discussed in the \"COMMANDS\" section of the\ndocumentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rerere.txt | 2 +-\n builtin/rerere.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 9d0e6f53e7e..992b469270c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 12570537d37..8b7392d5b44 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n \tNULL,\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464156","messageId":"patch-v4-22.34-c3d227c17c6-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 22/34] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:36Z","receivedAt":"2022-10-04T13:25:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend the -h output to match that of the *.txt output, the differences\nwere fairly small. In the case of \"[<options>]\" we only have a few of\nthem, so let's exhaustively list them as in the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 1b08700bf9e..544c78a5f3a 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,13 +12,14 @@\n  */\n \n #define BUILTIN_BUNDLE_CREATE_USAGE \\\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n+\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n-\tN_(\"git bundle verify [<options>] <file>\")\n+\tN_(\"git bundle verify [-q | --quiet] <file>\")\n #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n \tN_(\"git bundle list-heads <file> [<refname>...]\")\n #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n-\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n \n static char const * const builtin_bundle_usage[] = {\n \tBUILTIN_BUNDLE_CREATE_USAGE,\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464157","messageId":"patch-v4-21.34-2d4fdbd1aa1-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 21/34] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:35Z","receivedAt":"2022-10-04T13:25:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The C version was right to use \"()\" in place of \"[]\" around the option\nlisting, let's update the *.txt version accordingly, and furthermore\nlist the *.c options in the same order as the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-read-tree.txt | 2 +-\n builtin/read-tree.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex b9bfdc0a319..7567955bad8 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n SYNOPSIS\n --------\n [verse]\n-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex b3a389e1b1f..f4cbe460b97 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n \n static const char * const read_tree_usage[] = {\n \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n-\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464158","messageId":"patch-v4-23.34-02e450ea39b-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 23/34] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:37Z","receivedAt":"2022-10-04T13:25:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\nreceive-pack\" and \"git credential-cache--daemon\".\n\nFor \"git-receive-pack\" we do have a binary with that name, even when\ninstalled with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes\nof the SYNOPSIS let's use the \"git cmd\" form like everywhere else. It\ncan be invoked like that (and our tests do so), the parts of our\ndocumentation that explain when you need to use the dashed form do so,\nand use it.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-receive-pack.txt | 2 +-\n builtin/credential-cache--daemon.c | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 5c297db1a4b..65ff518ccff 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <git-dir>\n+'git receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex d4eb0097d24..f3c89831d4a 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\n@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n {\n \tconst char * const usage[] = {\n-\t\t\"git credential-cache--daemon [options] <action>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\t\"\",\n \t\t\"credential-cache--daemon is disabled in this build of Git\",\n \t\tNULL\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464159","messageId":"patch-v4-26.34-c02fc626542-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 26/34] doc txt & -h consistency: make \"annotate\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:40Z","receivedAt":"2022-10-04T13:25:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cmd_blame() already detected whether it was processing \"blame\" or\n\"annotate\", but it didn't adjust its usage output accordingly. Let's\ndo that.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-annotate.txt |  2 +-\n builtin/blame.c                | 22 ++++++++++++++++------\n 2 files changed, 17 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex e44a831339d..5ae8aabe0f8 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [<options>] <file> [<revision>]\n+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex a9fe8cf7a68..71f925e456c 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -30,6 +30,7 @@\n #include \"tag.h\"\n \n static char blame_usage[] = N_(\"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n+static char annotate_usage[] = N_(\"git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n \n static const char *blame_opt_usage[] = {\n \tblame_usage,\n@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {\n \tNULL\n };\n \n+static const char *annotate_opt_usage[] = {\n+\tannotate_usage,\n+\t\"\",\n+\tN_(\"<rev-opts> are documented in git-rev-list(1)\"),\n+\tNULL\n+};\n+\n static int longest_file;\n static int longest_author;\n static int max_orig_digits;\n@@ -899,6 +907,8 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tlong anchor;\n \tconst int hexsz = the_hash_algo->hexsz;\n \tlong num_lines = 0;\n+\tconst char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;\n+\tconst char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n \n \tsetup_default_color_by_age();\n \tgit_config(git_blame_config, &output_option);\n@@ -914,7 +924,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tparse_options_start(&ctx, argc, argv, prefix, options,\n \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n \tfor (;;) {\n-\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n+\t\tswitch (parse_options_step(&ctx, options, opt_usage)) {\n \t\tcase PARSE_OPT_NON_OPTION:\n \t\tcase PARSE_OPT_UNKNOWN:\n \t\t\tbreak;\n@@ -934,7 +944,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\tctx.argv[0] = \"--children\";\n \t\t\treverse = 1;\n \t\t}\n-\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n+\t\tparse_revision_opt(&revs, &ctx, options, opt_usage);\n \t}\n parse_done:\n \trevision_opts_finish(&revs);\n@@ -1040,7 +1050,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\tswitch (argc - dashdash_pos - 1) {\n \t\tcase 2: /* (1b) */\n \t\t\tif (argc != 4)\n-\t\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\t\tusage_with_options(opt_usage, options);\n \t\t\t/* reorder for the new way: <rev> -- <path> */\n \t\t\targv[1] = argv[3];\n \t\t\targv[3] = argv[2];\n@@ -1051,11 +1061,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\targv[argc] = NULL;\n \t\t\tbreak;\n \t\tdefault:\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(opt_usage, options);\n \t\t}\n \t} else {\n \t\tif (argc < 2)\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(opt_usage, options);\n \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n \t\t\tpath = add_prefix(prefix, argv[1]);\n \t\t\targv[1] = argv[2];\n@@ -1113,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\t\t    nth_line_cb, &sb, lno, anchor,\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n-\t\t\tusage(blame_usage);\n+\t\t\tusage(str_usage);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464160","messageId":"patch-v4-24.34-430d40d3083-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 24/34] doc txt & -h consistency: add missing options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:38Z","receivedAt":"2022-10-04T13:25:59Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change those built-in commands that were attempting to exhaustively\nlist the options in the \"-h\" output to actually do so, and always\nhave *.txt documentation know about the exhaustive list of options.\n\nLet's also fix the documentation and -h output for those built-in\ncommands where the *.txt and -h output was a mismatch of missing\noptions on both sides.\n\nIn the case of \"interpret-trailers\" fixing the missing options reveals\nthat the *.txt version was implicitly claiming that the command had\ntwo operating modes, which a look at the -h version (and studying the\ndocumentation) will show is not the case.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-commit-graph.txt       | 5 ++++-\n Documentation/git-interpret-trailers.txt | 5 +++--\n builtin/commit-tree.c                    | 1 +\n builtin/fsck.c                           | 5 ++++-\n builtin/hash-object.c                    | 4 ++--\n builtin/init-db.c                        | 2 ++\n builtin/interpret-trailers.c             | 2 +-\n builtin/rm.c                             | 4 +++-\n 8 files changed, 20 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 36fe56c2c71..c8dbceba014 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -10,7 +10,10 @@ SYNOPSIS\n --------\n [verse]\n 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n+'git commit-graph write' [--object-dir <dir>] [--append]\n+\t\t\t[--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n+\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n+\t\t\t<split options>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 6d6197cd0a4..22ff3a603e0 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [<options>] [--parse] [<file>...]\n+'git interpret-trailers' [--in-place] [--trim-empty]\n+\t\t\t[(--trailer <token>[(=|:)<value>])...]\n+\t\t\t[--parse] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex e4b85d29d56..cc8d584be2f 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,6 +15,7 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n+\tN_(\"git commit-tree <tree> [(-p <parent>)...]\"),\n \tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n \t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\ndiff --git a/builtin/fsck.c b/builtin/fsck.c\nindex f7916f06ed5..ef273321d0b 100644\n--- a/builtin/fsck.c\n+++ b/builtin/fsck.c\n@@ -821,7 +821,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,\n }\n \n static char const * const fsck_usage[] = {\n-\tN_(\"git fsck [<options>] [<object>...]\"),\n+\tN_(\"git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\\n\"\n+\t   \"         [--[no-]full] [--strict] [--verbose] [--lost-found]\\n\"\n+\t   \"         [--[no-]dangling] [--[no-]progress] [--connectivity-only]\\n\"\n+\t   \"         [--[no-]name-objects] [<object>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex f7c16802f0c..b5063815020 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n \t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n-\t\t   \"                [--stdin] [--] <file>...\"),\n-\t\t\"git hash-object  --stdin-paths\",\n+\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n \t\tNULL\n \t};\n \tconst char *type = blob_type;\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 08ba006d55e..dcaaf102eaf 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n \n static const char *const init_db_usage[] = {\n \tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--separate-git-dir <git-dir>] [--object-format=<format>]\\n\"\n+\t   \"         [-b <branch-name> | --initial-branch=<branch-name>]\\n\"\n \t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 4cf0cf265dc..e58627c72a9 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -15,7 +15,7 @@\n static const char * const git_interpret_trailers_usage[] = {\n \tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n \t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n-\t   \"                       [<file>...]\"),\n+\t   \"                       [--parse] [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex b6ba859fe42..f0d025a4e23 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -17,7 +17,9 @@\n #include \"pathspec.h\"\n \n static const char * const builtin_rm_usage[] = {\n-\tN_(\"git rm [<options>] [--] <file>...\"),\n+\tN_(\"git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\\n\"\n+\t   \"       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"       [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464161","messageId":"patch-v4-27.34-d991b9ef611-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 27/34] doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:41Z","receivedAt":"2022-10-04T13:26:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Correct uses of \"<label>...\" where we really meant to say\n\"[<label>...]\", i.e. the command in question taken an optional set of\n\"<label>\". As the CodingGuidelines notes \"[o]ptional parts [should be]\nenclosed in square brackets\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt | 2 +-\n builtin/clean.c             | 2 +-\n builtin/commit.c            | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 61b6d8667a4..62b5715ba1f 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\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>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 6f039f555b2..40ff2c578de 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex fcf9c85947e..21ad4ccbf87 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {\n };\n \n static const char * const builtin_status_usage[] = {\n-\tN_(\"git status [<options>] [--] <pathspec>...\"),\n+\tN_(\"git status [<options>] [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464162","messageId":"patch-v4-25.34-acd6e1f2632-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 25/34] doc txt & -h consistency: make \"stash\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:39Z","receivedAt":"2022-10-04T13:26:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend both the -h output and *.txt to match one another. In this case\nthe *.txt didn't list the \"save\" subcommand, and the \"-h\" was\nsimilarly missing some commands.\n\nLet's also convert the *.c code to use a macro definition, similar to\nthat used in preceding commits. This avoids duplication.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt |  5 ++-\n builtin/stash.c             | 73 ++++++++++++++++++++++++-------------\n 2 files changed, 52 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex ea16d2eae7c..f4bb6114d91 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,12 +11,15 @@ SYNOPSIS\n 'git stash' list [<log-options>]\n 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n 'git stash' drop [-q | --quiet] [<stash>]\n-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n+'git stash' pop [--index] [-q | --quiet] [<stash>]\n+'git stash' apply [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [<message>]\n 'git stash' clear\n 'git stash' create [<message>]\n 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 83c9591ea6d..bb5485b4095 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -21,72 +21,95 @@\n \n #define INCLUDE_ALL_FILES 2\n \n+#define BUILTIN_STASH_LIST_USAGE \\\n+\tN_(\"git stash list [<log-options>]\")\n+#define BUILTIN_STASH_SHOW_USAGE \\\n+\tN_(\"git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\")\n+#define BUILTIN_STASH_DROP_USAGE \\\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_POP_USAGE \\\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_APPLY_USAGE \\\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_BRANCH_USAGE \\\n+\tN_(\"git stash branch <branchname> [<stash>]\")\n+#define BUILTIN_STASH_STORE_USAGE \\\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\")\n+#define BUILTIN_STASH_PUSH_USAGE \\\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\" \\\n+\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\" \\\n+\t   \"          [--] [<pathspec>...]]\")\n+#define BUILTIN_STASH_SAVE_USAGE \\\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\")\n+#define BUILTIN_STASH_CREATE_USAGE \\\n+\tN_(\"git stash create [<message>]\")\n+#define BUILTIN_STASH_CLEAR_USAGE \\\n+\t\"git stash clear\"\n+\n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<log-options>]\"),\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n-\t\"git stash clear\",\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n+\tBUILTIN_STASH_SHOW_USAGE,\n+\tBUILTIN_STASH_DROP_USAGE,\n+\tBUILTIN_STASH_POP_USAGE,\n+\tBUILTIN_STASH_APPLY_USAGE,\n+\tBUILTIN_STASH_BRANCH_USAGE,\n+\tBUILTIN_STASH_PUSH_USAGE,\n+\tBUILTIN_STASH_SAVE_USAGE,\n+\tBUILTIN_STASH_CLEAR_USAGE,\n+\tBUILTIN_STASH_CREATE_USAGE,\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_list_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_show_usage[] = {\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n+\tBUILTIN_STASH_SHOW_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_DROP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_POP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_APPLY_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_branch_usage[] = {\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_clear_usage[] = {\n-\t\"git stash clear\",\n+\tBUILTIN_STASH_CLEAR_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n+\tBUILTIN_STASH_PUSH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_SAVE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464163","messageId":"patch-v4-34.34-3443ae7ee6b-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 34/34] tests: assert consistent whitespace in -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:48Z","receivedAt":"2022-10-04T13:26:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test for the *.txt and *.c output assertions which asserts that\nfor \"-h\" lines that aren't the \"usage: \" or \" or: \" lines they start\nwith the same amount of whitespace. This ensures that we won't have\nbuggy output like:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n       [--create-reflog] [...]\n\nWhich should instead be like this, i.e. the options lines should be\naligned:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n               [--create-reflog] [...]\n\nIt would be better to be able to use \"test_cmp\" here, i.e. to\nconstruct the output we expect, and compare it against the actual\noutput.\n\nFor most built-in commands this would be rather straightforward. In\n\"t0450-txt-doc-vs-help.sh\" we already compute the whitespace that a\n\"git-$builtin\" needs, and strip away \"usage: \" or \" or: \" from the\nstart of lines. The problem is:\n\n * For commands that implement subcommands, such as \"git bundle\", we\n   don't know whether e.g. \"git bundle create\" is the subcommand\n   \"create\", or the argument \"create\" to \"bundle\" for the purposes of\n   alignment.\n\n   We *do* have that information from the *.txt version, since the\n   part within the ''-quotes should be the command & subcommand, but\n   that isn't consistent (e.g. see \"git bundle\" and \"git\n   commit-graph\", only the latter is correct), and parsing that out\n   would be non-trivial.\n\n * If we were to make this stricter we have various\n   non-parse_options() users (e.g. \"git diff-tree\") that don't have the\n   nicely aligned output which we've had since\n   4631cfc20bd (parse-options: properly align continued usage output,\n   2021-09-21).\n\nSo rather than make perfect the enemy of the good let's assert that\nfor those lines that are indented they should all use the same\nindentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 8fd20b6dba6..cd3969e852b 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -96,6 +96,21 @@ do\n \t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n \t'\n \n+\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\t\tsed -n \\\n+\t\t\t-e \"/^ / {\n+\t\t\t\ts/[^ ].*//;\n+\t\t\t\tp;\n+\t\t\t}\" \\\n+\t\t\t<\"$h2s\" >help &&\n+\t\tsort -u help >help.ws &&\n+\t\tif test -s help.ws\n+\t\tthen\n+\t\t\ttest_line_count = 1 help.ws\n+\t\tfi\n+\t'\n+\n \ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n \tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464164","messageId":"patch-v4-29.34-3c8154151f3-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 29/34] doc txt & -h consistency: make \"commit\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:43Z","receivedAt":"2022-10-04T13:26:19Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"-h\" output of \"git commit\" consistent with the *.txt version\nby exhaustively listing the options that it takes.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/commit.c | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex 21ad4ccbf87..64f420bcbf6 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -40,7 +40,14 @@\n #include \"pretty.h\"\n \n static const char * const builtin_commit_usage[] = {\n-\tN_(\"git commit [<options>] [--] <pathspec>...\"),\n+\tN_(\"git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\\n\"\n+\t   \"           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\\n\"\n+\t   \"           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\\n\"\n+\t   \"           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\\n\"\n+\t   \"           [--date=<date>] [--cleanup=<mode>] [--[no-]status]\\n\"\n+\t   \"           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\\n\"\n+\t   \"           [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464165","messageId":"patch-v4-31.34-dbcabff3421-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 31/34] worktree: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:45Z","receivedAt":"2022-10-04T13:26:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git worktree\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------\n 1 file changed, 84 insertions(+), 25 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 5bfc18e5a24..ba6846c3788 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -15,15 +15,72 @@\n #include \"worktree.h\"\n #include \"quote.h\"\n \n-static const char * const worktree_usage[] = {\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\"),\n-\tN_(\"git worktree list [<options>]\"),\n-\tN_(\"git worktree lock [<options>] <path>\"),\n-\tN_(\"git worktree move <worktree> <new-path>\"),\n-\tN_(\"git worktree prune [<options>]\"),\n-\tN_(\"git worktree remove [<options>] <worktree>\"),\n-\tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <worktree>\"),\n+#define BUILTIN_WORKTREE_ADD_USAGE \\\n+\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+#define BUILTIN_WORKTREE_LIST_USAGE \\\n+\tN_(\"git worktree list [<options>]\")\n+#define BUILTIN_WORKTREE_LOCK_USAGE \\\n+\tN_(\"git worktree lock [<options>] <path>\")\n+#define BUILTIN_WORKTREE_MOVE_USAGE \\\n+\tN_(\"git worktree move <worktree> <new-path>\")\n+#define BUILTIN_WORKTREE_PRUNE_USAGE \\\n+\tN_(\"git worktree prune [<options>]\")\n+#define BUILTIN_WORKTREE_REMOVE_USAGE \\\n+\tN_(\"git worktree remove [<options>] <worktree>\")\n+#define BUILTIN_WORKTREE_REPAIR_USAGE \\\n+\tN_(\"git worktree repair [<path>...]\")\n+#define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n+\tN_(\"git worktree unlock <worktree>\")\n+\n+static const char * const git_worktree_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_add_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tNULL,\n+};\n+\n+static const char * const git_worktree_list_usage[] = {\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_lock_usage[] = {\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_move_usage[] = {\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_prune_usage[] = {\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_remove_usage[] = {\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_repair_usage[] = {\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_unlock_usage[] = {\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n \tNULL\n };\n \n@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,\n+\t\t\t   0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_prune_usage, options);\n \tprune_worktrees();\n \treturn 0;\n }\n@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)\n \n \tmemset(&opts, 0, sizeof(opts));\n \topts.checkout = 1;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);\n \tif (!!opts.detach + !!new_branch + !!new_branch_force > 1)\n \t\tdie(_(\"options '%s', '%s', and '%s' cannot be used together\"), \"-b\", \"-B\", \"--detach\");\n \tif (lock_reason && !keep_locked)\n@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\topts.keep_locked = _(\"added with --lock\");\n \n \tif (ac < 1 || ac > 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_add_usage, options);\n \n \tpath = prefix_filename(prefix, av[0]);\n \tbranch = ac < 2 ? \"HEAD\" : av[1];\n@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_list_usage, options);\n \telse if (verbose && porcelain)\n \t\tdie(_(\"options '%s' and '%s' cannot be used together\"), \"--verbose\", \"--porcelain\");\n \telse if (!line_terminator && !porcelain)\n@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)\n \t};\n \tstruct worktree **worktrees, *wt;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_lock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)\n \tstruct worktree **worktrees, *wt;\n \tint ret;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_unlock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tchar *path;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_move_usage,\n+\t\t\t   0);\n \tif (ac != 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_move_usage, options);\n \n \tpath = prefix_filename(prefix, av[1]);\n \tstrbuf_addstr(&dst, path);\n@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tint ret = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_remove_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)\n \t};\n \tint rc = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);\n \tp = ac > 0 ? av : self;\n \tfor (; *p; p++)\n \t\trepair_worktree_at_path(*p, report_repair, &rc);\n@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)\n \tif (!prefix)\n \t\tprefix = \"\";\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);\n \treturn fn(ac, av, prefix);\n }\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464166","messageId":"patch-v4-33.34-a2abf7a1161-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:47Z","receivedAt":"2022-10-04T13:26:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's been a lot of incremental effort to make the SYNOPSIS output\nin our documentation consistent with the -h output,\ne.g. cbe485298bf (git reflog [expire|delete]: make -h output\nconsistent with SYNOPSIS, 2022-03-17) is one recent example, but that\neffort has been an uphill battle due to the lack of regression\ntesting.\n\nThis adds such regression testing, we can parse out the SYNOPSIS\noutput with \"sed\", and it turns out it's relatively easy to normalize\nit and the \"-h\" output to match on another.\n\nWe now ensure that we won't have regressions when it comes to the list\nof commands in \"expect_help_to_match_txt\" below, and in subsequent\ncommits we'll make more of them consistent.\n\nThe naïve parser here gets quite a few things wrong, but it doesn't\nneed to be perfect, just good enough that we can compare /some/ of\nthis help output. There's no cases where the output would match except\nfor the parser's stupidity, it's all cases of e.g. comparing the *.txt\nto non-parse_options() output.\n\nSince that output is wildly different than the *.txt anyway let's\nleave this for now, we can fix the parser some other time, or it won't\nbecome necessary as we'll e.g. convert more things to using\nparse_options().\n\nHaving a special-case for \"merge-tree\"'s 1f0c3a29da3 (merge-tree:\nimplement real merges, 2022-06-18) is a bit ugly, but preferred to\nblessing that \" (deprecated)\" pattern for other commands. We'd\nprobably want to add some other way of marking deprecated commands in\nthe SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is\nindistinguishable from the command taking an optional literal\n\"deprecated\" string as an argument.\n\nSome of the issues that are left:\n\n * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n   all showing \"git log\" and \"git show\" usage output. I.e. the\n   \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n   command we're running.\n\n * Commands which implement subcommands such as like\n   \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n   in a very different order in the *.txt and *.c. Fixing it would\n   require some verbose diffs, so it's been left alone for now.\n\n * Commands such as \"format-patch\" have a very long argument list in\n   the *.txt, but just \"[<options>]\" in the *.c.\n\n   What to do about these has been left out of this series, except to\n   the extent that preceding commits changed \"[<options>]\" (or\n   equivalent) to the list of options in cases where that list of\n   options was tiny, or we clearly meant to exhaustively list the\n   options in both *.txt and *.c.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh  | 69 ++++++++++++++++++++++++++++++++++++-\n t/t0450/txt-help-mismatches | 58 +++++++++++++++++++++++++++++++\n 2 files changed, 126 insertions(+), 1 deletion(-)\n create mode 100644 t/t0450/txt-help-mismatches\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex efd00cfc51a..8fd20b6dba6 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -1,6 +1,9 @@\n #!/bin/sh\n \n-test_description='assert (unbuilt) Documentation/*.txt and -h output'\n+test_description='assert (unbuilt) Documentation/*.txt and -h output\n+\n+Run this with --debug to see a summary of where we still fail to make\n+the two versions consistent with one another.'\n \n TEST_PASSES_SANITIZE_LEAK=true\n . ./test-lib.sh\n@@ -9,6 +12,14 @@ test_expect_success 'setup: list of builtins' '\n \tgit --list-cmds=builtins >builtins\n '\n \n+test_expect_success 'list of txt and help mismatches is sorted' '\n+\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n+\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tBUG \"please keep the list of txt and help mismatches sorted\"\n+\tfi\n+'\n+\n help_to_synopsis () {\n \tbuiltin=\"$1\" &&\n \tout_dir=\"out/$builtin\" &&\n@@ -49,6 +60,9 @@ txt_to_synopsis () {\n \t\t\t/^$/d;\n \t\t\t/^\\[verse\\]$/d;\n \n+\t\t\ts/{litdd}/--/g;\n+\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\n \t\t\tp;\n \t\t}' \\\n \t\t<\"$b2t\" >\"$out\" &&\n@@ -61,6 +75,15 @@ check_dashed_labels () {\n \n HT=\"\t\"\n \n+align_after_nl () {\n+\tbuiltin=\"$1\" &&\n+\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n+\tpad=$(printf \"%${len}s\" \"\") &&\n+\n+\tsed \"s/^[ $HT][ $HT]*/$pad/\"\n+}\n+\n+test_debug '>failing'\n while read builtin\n do\n \t# -h output assertions\n@@ -85,6 +108,50 @@ do\n \ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n \t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n \t'\n+\n+\t# *.txt output consistency assertions\n+\tresult=\n+\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tresult=failure\n+\telse\n+\t\tresult=success\n+\tfi &&\n+\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n+\t\tt2s=\"$(txt_to_synopsis \"$builtin\")\" &&\n+\t\tif test \"$builtin\" = \"merge-tree\"\n+\t\tthen\n+\t\t\ttest_when_finished \"rm -f t2s.new\" &&\n+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <\"$t2s\" >t2s.new\n+\t\t\tt2s=t2s.new\n+\t\tfi &&\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\n+\t\t# The *.txt and -h use different spacing for the\n+\t\t# alignment of continued usage output, normalize it.\n+\t\talign_after_nl \"$builtin\" <\"$t2s\" >txt &&\n+\t\talign_after_nl \"$builtin\" <\"$h2s\" >help &&\n+\t\ttest_cmp txt help\n+\t'\n+\n+\tif test_have_prereq \"$preq\" && test -e txt && test -e help\n+\tthen\n+\t\ttest_debug '\n+\t\t\tif test_cmp txt help >cmp 2>/dev/null\n+\t\t\tthen\n+\t\t\t\techo \"=== DONE: $builtin ===\"\n+\t\t\telse\n+\t\t\t\techo \"=== TODO: $builtin ===\" &&\n+\t\t\t\tcat cmp\n+\t\t\tfi >>failing\n+\t\t'\n+\n+\t\t# Not in test_expect_success in case --run is being\n+\t\t# used with --debug\n+\t\trm -f txt help tmp 2>/dev/null\n+\tfi\n done <builtins\n \n+test_debug 'say \"$(cat failing)\"'\n+\n test_done\ndiff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches\nnew file mode 100644\nindex 00000000000..a0777acd667\n--- /dev/null\n+++ b/t/t0450/txt-help-mismatches\n@@ -0,0 +1,58 @@\n+add\n+am\n+apply\n+archive\n+bisect\n+blame\n+branch\n+check-ref-format\n+checkout\n+checkout-index\n+clone\n+column\n+config\n+credential\n+credential-cache\n+credential-store\n+fast-export\n+fast-import\n+fetch-pack\n+fmt-merge-msg\n+for-each-ref\n+format-patch\n+fsck-objects\n+fsmonitor--daemon\n+gc\n+grep\n+index-pack\n+init-db\n+log\n+ls-files\n+ls-tree\n+mailinfo\n+mailsplit\n+maintenance\n+merge\n+merge-file\n+merge-index\n+merge-one-file\n+multi-pack-index\n+name-rev\n+notes\n+pack-objects\n+push\n+range-diff\n+rebase\n+remote\n+remote-ext\n+remote-fd\n+repack\n+reset\n+restore\n+rev-parse\n+show\n+stage\n+switch\n+update-index\n+update-ref\n+whatchanged\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464167","messageId":"patch-v4-28.34-dd7d2f0b167-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 28/34] doc txt & -h consistency: make \"diff-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:42Z","receivedAt":"2022-10-04T13:26:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"diff-tree -h\" output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-tree.c | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 23f58702fa0..85e8c81e594 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)\n }\n \n static const char diff_tree_usage[] =\n-\"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\\n\"\n+\"              [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\\n\"\n+\"              [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n \"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464168","messageId":"patch-v4-30.34-2452157548b-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 30/34] reflog doc: list real subcommands up-front","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:44Z","receivedAt":"2022-10-04T13:26:50Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"git reflog\" documentation to exhaustively list the\nsubcommands it accepts in the SYNOPSIS, as opposed to leaving that for\na \"[verse]\" in the DESCRIPTION section. This documentation style was\nadded in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how\nother commands which take subcommands are documented.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 15 ++++++---------\n 1 file changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 0537d4645be..ec64cbff4c6 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -8,14 +8,6 @@ git-reflog - Manage reflog information\n \n SYNOPSIS\n --------\n-[verse]\n-'git reflog' <subcommand> <options>\n-\n-DESCRIPTION\n------------\n-The command takes various subcommands, and different options\n-depending on the subcommand:\n-\n [verse]\n 'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n@@ -25,6 +17,10 @@ depending on the subcommand:\n \t[--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n 'git reflog exists' <ref>\n \n+DESCRIPTION\n+-----------\n+This command manages the information recorded in the reflogs.\n+\n Reference logs, or \"reflogs\", record when the tips of branches and\n other references were updated in the local repository. Reflogs are\n useful in various Git commands, to specify the old value of a\n@@ -33,7 +29,8 @@ moves ago\", `master@{one.week.ago}` means \"where master used to point\n to one week ago in this local repository\", and so on. See\n linkgit:gitrevisions[7] for more details.\n \n-This command manages the information recorded in the reflogs.\n+The command takes various subcommands, and different options\n+depending on the subcommand:\n \n The \"show\" subcommand (which is also the default, in the absence of\n any subcommands) shows the log of the reference provided in the\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464169","messageId":"patch-v4-32.34-ea82721b057-20221004T132211Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com","subject":"[PATCH v4 32/34] doc txt & -h consistency: make \"worktree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-04T13:23:46Z","receivedAt":"2022-10-04T13:26:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"worktree\" -h output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex ba6846c3788..4a24d53be15 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -16,17 +16,18 @@\n #include \"quote.h\"\n \n #define BUILTIN_WORKTREE_ADD_USAGE \\\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+\tN_(\"git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\\n\" \\\n+\t   \"                 [-b <new-branch>] <path> [<commit-ish>]\")\n #define BUILTIN_WORKTREE_LIST_USAGE \\\n-\tN_(\"git worktree list [<options>]\")\n+\tN_(\"git worktree list [-v | --porcelain [-z]]\")\n #define BUILTIN_WORKTREE_LOCK_USAGE \\\n-\tN_(\"git worktree lock [<options>] <path>\")\n+\tN_(\"git worktree lock [--reason <string>] <worktree>\")\n #define BUILTIN_WORKTREE_MOVE_USAGE \\\n \tN_(\"git worktree move <worktree> <new-path>\")\n #define BUILTIN_WORKTREE_PRUNE_USAGE \\\n-\tN_(\"git worktree prune [<options>]\")\n+\tN_(\"git worktree prune [-n] [-v] [--expire <expire>]\")\n #define BUILTIN_WORKTREE_REMOVE_USAGE \\\n-\tN_(\"git worktree remove [<options>] <worktree>\")\n+\tN_(\"git worktree remove [-f] <worktree>\")\n #define BUILTIN_WORKTREE_REPAIR_USAGE \\\n \tN_(\"git worktree repair [<path>...]\")\n #define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n-- \n2.38.0.rc2.935.g6b421ae1592\n\n"},{"id":"464193","messageId":"xmqqlepvsgeo.fsf@gitster.g","threadId":"58397","inReplyTo":"patch-v4-16.34-563ccaab6a9-20221004T132211Z-avarab@gmail.com","subject":"Re: [PATCH v4 16/34] doc txt & -h consistency: fix mismatching labels","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-04T16:27:27Z","receivedAt":"2022-10-04T16:27:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\n> index 91742633fa8..61b6d8667a4 100644\n> --- a/Documentation/git-clean.txt\n> +++ b/Documentation/git-clean.txt\n> @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n> +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n>  \n>  DESCRIPTION\n>  -----------\n> @@ -20,13 +20,13 @@ Normally, only files unknown to Git are removed, but if the `-x`\n>  option is specified, ignored files are also removed. This can, for\n>  example, be useful to remove all build products.\n>  \n> -If any optional `<path>...` arguments are given, only those paths\n> -are affected.\n> +If any optional `<pathspec>...` arguments are given, only those paths\n> +that match the pathspec are affected.\n\nOK.  But ...\n\n>  OPTIONS\n>  -------\n>  -d::\n> -\tNormally, when no <path> is specified, git clean will not\n> +\tNormally, when no <pathspec> is specified, git clean will not\n>  \trecurse into untracked directories to avoid removing too much.\n>  \tSpecify -d to have it recurse into such directories as well.\n>  \tIf any paths are specified, -d is irrelevant; all untracked\n\n... this \"any paths are\" needs the same treatment.  I didn't point\nout every instances of the same error in my previous review, but was\nhoping that a reroll was done a bit more care than just fixing exact\nlocations pointed out.\n\nThere may be other such instances in this round, but this somehow\nstood out in my quick scan.  I am offline today, and will not\nreading the other patches until tomorrow.\n\nThanks for  working on the topic.\n\n"},{"id":"464247","messageId":"xmqqilkyqj9t.fsf@gitster.g","threadId":"58397","inReplyTo":"221004.86fsg4t3x2.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v3 22/36] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-05T17:20:46Z","receivedAt":"2022-10-05T17:20:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n>> Not really.  A <pathspec> is a set of <pathspec element>s, so\n>> writing \"<pathspec-element>...\" and \"<pathspec>\" are equivalent.\n>\n> So, \"yes\"? I.e. leaving aside \"pathspec\" or \"pathspec-element\"\n> \"<pathspecs>\" is redundant to \"<pathspecs>...\" in this intpreretation?\n\nIf you leave it aside, then the answer becomes meaningless, no?\n\n> But for any given \"<x>\" the \"<x>\" is not the same as \"<x>...\"?\n\nCorrect.  \"<collection-of-xs>\" is equivalent to \"[<x>...]\", but\n\"<x>\" is not equivalent to \"[<x>...]\" (with or without [] around the\nlatter).\n\n> But that's really not what we mean most of the time, we *don't* want\n> that \"...\" on the argument to \"--opt\", because it only takes one\n> argument.\n\nYes.  So an option that takes a single pathspec element should say\nas such, I would think.\n\nBut I thought that I have already said we should shrink the scope of\nthis series, concentrating on making -h output and doc match, while\nadjusting the body text in the doc to match the phrasing used in the\nSYNOPSIS updated to match -h output, so this whole thing is outside\nthe scope of this topic, I would say.\n\nThanks.\n\n\n"},{"id":"464830","messageId":"patch-v5-03.34-dadae0d364f-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 03/34] builtin/bundle.c: indent with tabs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:57Z","receivedAt":"2022-10-13T15:39:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix indentation issues introduced with 73c3253d75e (bundle: framework\nfor options before bundle file, 2019-11-10), and carried forward in\nsome subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 26 +++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex e80efce3a42..5c78894afd5 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,31 +12,31 @@\n  */\n \n static const char * const builtin_bundle_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-  N_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-  NULL\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-  N_(\"git bundle verify [<options>] <file>\"),\n-  NULL\n+\tN_(\"git bundle verify [<options>] <file>\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-  N_(\"git bundle list-heads <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-  N_(\"git bundle unbundle <file> [<refname>...]\"),\n-  NULL\n+\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tNULL\n };\n \n static int parse_options_cmd_bundle(int argc,\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464831","messageId":"patch-v5-01.34-cb0e2ffcd2c-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 01/34] tests: assert *.txt SYNOPSIS and -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:55Z","receivedAt":"2022-10-13T15:39:47Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test to assert basic compliance with the CodingGuidelines in the\nSYNOPSIS and builtin -h output. For now we only assert that the \"-h\"\noutput doesn't have \"\\t\" characters, as a very basic syntax check.\n\nSubsequent commits will expand on the checks here as various issues\nare fixed, but let's first add the test scaffolding.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 44 ++++++++++++++++++++++++++++++++++++++\n 1 file changed, 44 insertions(+)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nnew file mode 100755\nindex 00000000000..c8820bdd38f\n--- /dev/null\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -0,0 +1,44 @@\n+#!/bin/sh\n+\n+test_description='assert (unbuilt) Documentation/*.txt and -h output'\n+\n+TEST_PASSES_SANITIZE_LEAK=true\n+. ./test-lib.sh\n+\n+test_expect_success 'setup: list of builtins' '\n+\tgit --list-cmds=builtins >builtins\n+'\n+\n+help_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\tout_dir=\"out/$builtin\" &&\n+\tout=\"$out_dir/help.synopsis\" &&\n+\tif test -f \"$out\"\n+\tthen\n+\t\techo \"$out\" &&\n+\t\treturn 0\n+\tfi &&\n+\tmkdir -p \"$out_dir\" &&\n+\ttest_expect_code 129 git $builtin -h >\"$out.raw\" 2>&1 &&\n+\tsed -n \\\n+\t\t-e '1,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\ts/^usage: //;\n+\t\t\ts/^ *or: //;\n+\t\t\tp;\n+\t\t}' <\"$out.raw\" >\"$out\" &&\n+\techo \"$out\"\n+}\n+\n+HT=\"\t\"\n+\n+while read builtin\n+do\n+\t# -h output assertions\n+\ttest_expect_success \"$builtin -h output has no \\t\" '\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\t\t! grep \"$HT\" \"$h2s\"\n+\t'\n+done <builtins\n+\n+test_done\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464832","messageId":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v3-00.34-00000000000-20221004T131009Z-avarab@gmail.com","subject":"[PATCH v5 00/34] doc/UX: make txt & -h output more consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:54Z","receivedAt":"2022-10-13T15:39:49Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"We are currently wildly inconsistent in whether the SYNOPSIS in the\nmanual page matches the first line of the -h output, and as we add new\noptions we routinely forget to add them to one or the other (or both).\n\nWithout a more complex approach it's hard to do something about the\n\"or both\" case. But we can rather easily test whether the -h output\nmatches the *.txt version, and report differences.\n\nAs this series shows that allows us to fix a lot of issues we've\neffectively already \"fixed\", we just fixed them in one version, but\nnot the other.\n\nFor the rest of the general overview (the first paragraphs are\ncopy/pasted) see the v1 at:\nhttps://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com\nFor v3 see:\nhttps://lore.kernel.org/git/cover-v4-00.34-00000000000-20221004T132211Z-avarab@gmail.com/\n\nJunio: A trivial v5 re your\nhttps://lore.kernel.org/git/xmqqlepvsgeo.fsf@gitster.g/; FWIW I saw\nthat existing prose, but figured we could continue to use \"any paths\",\nbut it's rephrased to incorporate \"<pathspec>\" here, no other changes.\n\nI'm aware of the minor merge conflict with the builtin/symbolic-ref.c\ntopic of yours, but I see you've resolved it on your side, so this is\nstill based on \"master\".\n\nÆvar Arnfjörð Bjarmason (34):\n  tests: assert *.txt SYNOPSIS and -h output\n  CodingGuidelines: update and clarify command-line conventions\n  builtin/bundle.c: indent with tabs\n  bundle: define subcommand -h in terms of command -h\n  doc SYNOPSIS: don't use ' for subcommands\n  doc SYNOPSIS: consistently use ' for commands\n  built-ins: consistently add \"\\n\" between \"usage\" and options\n  doc txt & -h consistency: word-wrap\n  doc txt & -h consistency: fix incorrect alternates syntax\n  doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n  doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n  doc txt & -h consistency: correct padding around \"[]()\"\n  stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n  doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n  doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n  doc txt & -h consistency: fix mismatching labels\n  doc txt & -h consistency: add or fix optional \"--\" syntax\n  doc txt & -h consistency: make output order consistent\n  doc txt & -h consistency: add missing options and labels\n  doc txt & -h consistency: make \"rerere\" consistent\n  doc txt & -h consistency: make \"read-tree\" consistent\n  doc txt & -h consistency: make \"bundle\" consistent\n  doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n  doc txt & -h consistency: add missing options\n  doc txt & -h consistency: make \"stash\" consistent\n  doc txt & -h consistency: make \"annotate\" consistent\n  doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n  doc txt & -h consistency: make \"diff-tree\" consistent\n  doc txt & -h consistency: make \"commit\" consistent\n  reflog doc: list real subcommands up-front\n  worktree: define subcommand -h in terms of command -h\n  doc txt & -h consistency: make \"worktree\" consistent\n  tests: start asserting that *.txt SYNOPSIS matches -h output\n  tests: assert consistent whitespace in -h output\n\n Documentation/CodingGuidelines                |  14 +-\n Documentation/git-annotate.txt                |   2 +-\n Documentation/git-clean.txt                   |  10 +-\n Documentation/git-commit-graph.txt            |   5 +-\n .../git-credential-cache--daemon.txt          |   4 +-\n Documentation/git-diff-files.txt              |   2 +-\n Documentation/git-fast-export.txt             |   2 +-\n Documentation/git-hash-object.txt             |   3 +-\n Documentation/git-interpret-trailers.txt      |   5 +-\n Documentation/git-merge-base.txt              |   4 +-\n Documentation/git-mv.txt                      |   4 +-\n Documentation/git-pack-redundant.txt          |   2 +-\n Documentation/git-prune-packed.txt            |   2 +-\n Documentation/git-read-tree.txt               |   2 +-\n Documentation/git-receive-pack.txt            |   4 +-\n Documentation/git-reflog.txt                  |  17 +-\n Documentation/git-rerere.txt                  |   2 +-\n Documentation/git-rev-list.txt                |   2 +-\n Documentation/git-send-pack.txt               |   5 +-\n Documentation/git-show-branch.txt             |   4 +-\n Documentation/git-show-ref.txt                |   4 +-\n Documentation/git-sparse-checkout.txt         |   2 +-\n Documentation/git-stash.txt                   |  17 +-\n Documentation/git-status.txt                  |   2 +-\n Documentation/git-tag.txt                     |  18 +-\n Documentation/git-update-server-info.txt      |   8 +-\n Documentation/git-upload-archive.txt          |   4 +-\n Documentation/git-var.txt                     |   2 +-\n Documentation/git-verify-commit.txt           |   2 +-\n Documentation/git-verify-pack.txt             |   2 +-\n Documentation/git-verify-tag.txt              |   2 +-\n Documentation/git-worktree.txt                |   3 +-\n builtin/blame.c                               |  22 ++-\n builtin/bugreport.c                           |   3 +-\n builtin/bundle.c                              |  38 ++--\n builtin/cat-file.c                            |   2 +-\n builtin/clean.c                               |   2 +-\n builtin/commit-graph.c                        |  10 +-\n builtin/commit-tree.c                         |   5 +-\n builtin/commit.c                              |  11 +-\n builtin/credential-cache--daemon.c            |   4 +-\n builtin/describe.c                            |   5 +-\n builtin/diagnose.c                            |   3 +-\n builtin/diff-files.c                          |   1 +\n builtin/diff-index.c                          |   3 +-\n builtin/diff-tree.c                           |   6 +-\n builtin/diff.c                                |   3 +-\n builtin/for-each-repo.c                       |   2 +-\n builtin/fsck.c                                |   5 +-\n builtin/hash-object.c                         |   5 +-\n builtin/help.c                                |   2 +-\n builtin/init-db.c                             |   5 +-\n builtin/interpret-trailers.c                  |   4 +-\n builtin/ls-remote.c                           |   2 +-\n builtin/merge-base.c                          |   2 +-\n builtin/pack-objects.c                        |   4 +-\n builtin/pack-redundant.c                      |   2 +-\n builtin/pack-refs.c                           |   2 +-\n builtin/read-tree.c                           |   4 +-\n builtin/rerere.c                              |   2 +-\n builtin/rev-list.c                            |   3 +-\n builtin/revert.c                              |   9 +-\n builtin/rm.c                                  |   4 +-\n builtin/send-pack.c                           |   1 +\n builtin/show-branch.c                         |   3 +-\n builtin/show-ref.c                            |   4 +-\n builtin/sparse-checkout.c                     |   2 +-\n builtin/stash.c                               |  73 +++++---\n builtin/symbolic-ref.c                        |   5 +-\n builtin/tag.c                                 |  10 +-\n builtin/unpack-file.c                         |   2 +-\n builtin/update-server-info.c                  |   2 +-\n builtin/upload-archive.c                      |   2 +-\n builtin/upload-pack.c                         |   3 +-\n builtin/verify-commit.c                       |   2 +-\n builtin/verify-pack.c                         |   2 +-\n builtin/verify-tag.c                          |   2 +-\n builtin/worktree.c                            | 110 ++++++++---\n help.c                                        |   2 +-\n t/helper/test-proc-receive.c                  |   2 +-\n t/t0450-txt-doc-vs-help.sh                    | 172 ++++++++++++++++++\n t/t0450/txt-help-mismatches                   |  58 ++++++\n 82 files changed, 594 insertions(+), 199 deletions(-)\n create mode 100755 t/t0450-txt-doc-vs-help.sh\n create mode 100644 t/t0450/txt-help-mismatches\n\nRange-diff against v4:\n 1:  f76804fe9ae =  1:  cb0e2ffcd2c tests: assert *.txt SYNOPSIS and -h output\n 2:  c95d3b9ad42 =  2:  998cd47045b CodingGuidelines: update and clarify command-line conventions\n 3:  b7c98a40393 =  3:  dadae0d364f builtin/bundle.c: indent with tabs\n 4:  522d7fbb0a3 =  4:  7c9b42d8a9b bundle: define subcommand -h in terms of command -h\n 5:  ac437d4eee5 =  5:  88fdaff4f28 doc SYNOPSIS: don't use ' for subcommands\n 6:  f20cbb661c6 =  6:  7a4e244b261 doc SYNOPSIS: consistently use ' for commands\n 7:  ecdc14f6dfe =  7:  c31e6eba62d built-ins: consistently add \"\\n\" between \"usage\" and options\n 8:  1b9b6a91916 =  8:  e029f1303af doc txt & -h consistency: word-wrap\n 9:  f4598ca1899 =  9:  d878b1fd91d doc txt & -h consistency: fix incorrect alternates syntax\n10:  0e955f294cd = 10:  323afb78f75 doc txt & -h consistency: add \"-z\" to cat-file \"-h\"\n11:  aa2f9325839 = 11:  84a81046a95 doc txt & -h consistency: balance unbalanced \"[\" and \"]\"\n12:  009a0e586e9 = 12:  f5bd52cb103 doc txt & -h consistency: correct padding around \"[]()\"\n13:  b568189532f = 13:  83d53381165 stash doc SYNOPSIS & -h: correct padding around \"[]()\"\n14:  e5cb5c91b82 = 14:  760bc0a6727 doc txt & -h consistency: use \"<options>\", not \"<options>...\"\n15:  403e7ceb449 = 15:  00b4cc7dfcc doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"\n16:  563ccaab6a9 ! 16:  503bd076a6b doc txt & -h consistency: fix mismatching labels\n    @@ Documentation/git-clean.txt: Normally, only files unknown to Git are removed, bu\n     +\tNormally, when no <pathspec> is specified, git clean will not\n      \trecurse into untracked directories to avoid removing too much.\n      \tSpecify -d to have it recurse into such directories as well.\n    - \tIf any paths are specified, -d is irrelevant; all untracked\n    +-\tIf any paths are specified, -d is irrelevant; all untracked\n    ++\tIf a <pathspec> is specified, -d is irrelevant; all untracked\n    + \tfiles matching the specified paths (with exceptions for nested\n    + \tgit directories mentioned under `--force`) will be removed.\n    + \n     \n      ## Documentation/git-credential-cache--daemon.txt ##\n     @@ Documentation/git-credential-cache--daemon.txt: git-credential-cache--daemon - Temporarily store user credentials in memory\n17:  e6ef67f1c4f = 17:  a27ce91d9b3 doc txt & -h consistency: add or fix optional \"--\" syntax\n18:  766bafcde05 = 18:  517ff5a4565 doc txt & -h consistency: make output order consistent\n19:  fb95d7a9f86 = 19:  f5ad5f0a87f doc txt & -h consistency: add missing options and labels\n20:  729029f49c3 = 20:  058b22e22f7 doc txt & -h consistency: make \"rerere\" consistent\n21:  2d4fdbd1aa1 = 21:  2c4c48792b3 doc txt & -h consistency: make \"read-tree\" consistent\n22:  c3d227c17c6 = 22:  c616f2e9129 doc txt & -h consistency: make \"bundle\" consistent\n23:  02e450ea39b = 23:  1a49bbd1f6a doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"\n24:  430d40d3083 = 24:  bacce14d438 doc txt & -h consistency: add missing options\n25:  acd6e1f2632 = 25:  89ad801409d doc txt & -h consistency: make \"stash\" consistent\n26:  c02fc626542 = 26:  a7762e82f71 doc txt & -h consistency: make \"annotate\" consistent\n27:  d991b9ef611 = 27:  6c68125f191 doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"\n28:  dd7d2f0b167 = 28:  abaffb0b0df doc txt & -h consistency: make \"diff-tree\" consistent\n29:  3c8154151f3 = 29:  65cd6340726 doc txt & -h consistency: make \"commit\" consistent\n30:  2452157548b = 30:  f8f716e6ff5 reflog doc: list real subcommands up-front\n31:  dbcabff3421 = 31:  fd2d358fc05 worktree: define subcommand -h in terms of command -h\n32:  ea82721b057 = 32:  48c1bb97a91 doc txt & -h consistency: make \"worktree\" consistent\n33:  a2abf7a1161 = 33:  099998e8cba tests: start asserting that *.txt SYNOPSIS matches -h output\n34:  3443ae7ee6b = 34:  4de83d3d89a tests: assert consistent whitespace in -h output\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464833","messageId":"patch-v5-02.34-998cd47045b-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 02/34] CodingGuidelines: update and clarify command-line conventions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:56Z","receivedAt":"2022-10-13T15:39:54Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Edit the section which explains how to create a good SYNOPSIS section\nfor clarity and accuracy, it was mostly introduced in\nc455bd8950e (CodingGuidelines: Add a section on writing documentation,\n2010-11-04):\n\n * Change \"extra\" example to \"file\", which now naturally follows from\n   previous \"<file>...\" example (one or more) to \"[<file>...]\" (zero or\n   more).\n\n * Explain how we prefer spacing around \"[]()\" tokens and \"|\"\n   alternatives, this is not a new policy, but just codifies what's\n   already the pattern in the most wide use in the documentation.\n\nHaving a space around \" | \" for flags, but not for flag values is\ninconsistent, but this style guide codifies existing\npatterns. Grepping shows that we don't have any instance matching the\nsecond \"Don't\" example:\n\n\tgit grep -E -h -o '=\\([^)]+\\)' -- builtin Documentation/\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/CodingGuidelines | 14 ++++++++++++--\n 1 file changed, 12 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex cb7a367ea08..2a03f748551 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -648,8 +648,8 @@ Writing Documentation:\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [<extra>]\n-   (Zero or one <extra>.)\n+   [<file>...]\n+   (Zero or more of <file>.)\n \n    --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n@@ -663,6 +663,16 @@ Writing Documentation:\n    [-q | --quiet]\n    [--utf8 | --no-utf8]\n \n+ Use spacing around \"|\" token(s), but not immediately after opening or\n+ before closing a [] or () pair:\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n+\n+ Don't use spacing around \"|\" tokens when they're used to seperate the\n+ alternate arguments of an option:\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n+\n  Parentheses are used for grouping:\n    [(<rev> | <range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464834","messageId":"patch-v5-05.34-88fdaff4f28-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 05/34] doc SYNOPSIS: don't use ' for subcommands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:59Z","receivedAt":"2022-10-13T15:39:55Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Almost all of our documentation doesn't use \"'\" syntax for\nsubcommands, but these did, let's make them consistent with the\nrest.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-rerere.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex db9d46edfa9..0537d4645be 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,7 +17,7 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [<log-options>] [<ref>]\n+'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4cfc8833780..4b613d4140c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']\n+'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n \n DESCRIPTION\n -----------\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464835","messageId":"patch-v5-04.34-7c9b42d8a9b-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 04/34] bundle: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:38:58Z","receivedAt":"2022-10-13T15:39:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git bundle\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 29 +++++++++++++++++++----------\n 1 file changed, 19 insertions(+), 10 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 5c78894afd5..1b08700bf9e 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -11,31 +11,40 @@\n  * bundle supporting \"fetch\", \"pull\", and \"ls-remote\".\n  */\n \n-static const char * const builtin_bundle_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n-\tN_(\"git bundle verify [<options>] <file>\"),\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n-\tNULL\n+#define BUILTIN_BUNDLE_CREATE_USAGE \\\n+\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+#define BUILTIN_BUNDLE_VERIFY_USAGE \\\n+\tN_(\"git bundle verify [<options>] <file>\")\n+#define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n+\tN_(\"git bundle list-heads <file> [<refname>...]\")\n+#define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n+\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\n+static char const * const builtin_bundle_usage[] = {\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n+\tNULL,\n };\n \n static const char * const builtin_bundle_create_usage[] = {\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\"),\n+\tBUILTIN_BUNDLE_CREATE_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_verify_usage[] = {\n-\tN_(\"git bundle verify [<options>] <file>\"),\n+\tBUILTIN_BUNDLE_VERIFY_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_list_heads_usage[] = {\n-\tN_(\"git bundle list-heads <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_LIST_HEADS_USAGE,\n \tNULL\n };\n \n static const char * const builtin_bundle_unbundle_usage[] = {\n-\tN_(\"git bundle unbundle <file> [<refname>...]\"),\n+\tBUILTIN_BUNDLE_UNBUNDLE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464836","messageId":"patch-v5-06.34-7a4e244b261-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 06/34] doc SYNOPSIS: consistently use ' for commands","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:00Z","receivedAt":"2022-10-13T15:40:11Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Most of our commands use ''-quotation only for the name of the command\nitself, and not its (optional) arguments. Let's do the same for these.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-export.txt     | 2 +-\n Documentation/git-sparse-checkout.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 1978dbdc6ad..4643ddbe68f 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [<options>]' | 'git fast-import'\n+'git fast-export' [<options>] | 'git fast-import'\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 3776705bf53..872436d7426 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [<options>]'\n+'git sparse-checkout' <subcommand> [<options>]\n \n \n DESCRIPTION\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464837","messageId":"patch-v5-07.34-c31e6eba62d-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 07/34] built-ins: consistently add \"\\n\" between \"usage\" and options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:01Z","receivedAt":"2022-10-13T15:40:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change commands in the \"diff\" family and \"rev-list\" to separate the\nusage information and option listing with an empty line.\n\nIn the case of \"git diff -h\" we did this already (but let's use a\nconsistent \"\\n\" pattern there), for the rest these are now consistent\nwith how the parse_options() API would emit usage.\n\nAs we'll see in a subsequent commit this also helps to make the \"git\n<cmd> -h\" output more easily machine-readable, as we can assume that\nthe usage information is separated from the options by an empty line.\n\nNote that \"COMMON_DIFF_OPTIONS_HELP\" starts with a \"\\n\", so the\nseeming omission of a \"\\n\" here is correct, the second one is provided\nby the macro.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-files.c | 1 +\n builtin/diff-index.c | 1 +\n builtin/diff-tree.c  | 1 +\n builtin/diff.c       | 3 ++-\n builtin/rev-list.c   | 1 +\n 5 files changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/diff-files.c b/builtin/diff-files.c\nindex 92cf6e1e922..096ea2fedbc 100644\n--- a/builtin/diff-files.c\n+++ b/builtin/diff-files.c\n@@ -15,6 +15,7 @@\n \n static const char diff_files_usage[] =\n \"git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_files(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex 7d158af6b6d..e667cf52e7d 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -11,6 +11,7 @@\n static const char diff_cache_usage[] =\n \"git diff-index [-m] [--cached] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n int cmd_diff_index(int argc, const char **argv, const char *prefix)\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 116097a404a..23f58702fa0 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -85,6 +85,7 @@ static int diff_tree_stdin(char *line)\n static const char diff_tree_usage[] =\n \"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n \"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n \"  --cc          show combined diff for merge commits removing uninteresting hunks\\n\"\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 54bb3de964c..67760b67552 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -30,7 +30,8 @@ static const char builtin_diff_usage[] =\n \"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>\\n\"\n-\"   or: git diff [<options>] --no-index [--] <path> <path>\\n\"\n+\"   or: git diff [<options>] --no-index [--] <path> <path>\"\n+\"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\n \n static const char *blob_path(struct object_array_entry *entry)\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex fba6f5d51f3..f67e2b33555 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -21,6 +21,7 @@\n \n static const char rev_list_usage[] =\n \"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\n \"    --max-age=<epoch>\\n\"\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464838","messageId":"patch-v5-09.34-d878b1fd91d-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 09/34] doc txt & -h consistency: fix incorrect alternates syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:03Z","receivedAt":"2022-10-13T15:40:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix the incorrect \"[-o | --option <argument>]\" syntax, which should be\n\"[(-o | --option) <argument>]\", we were previously claiming that only\nthe long option accepted the \"<argument>\", which isn't what we meant.\n\nThis syntax issue for \"bugreport\" originated in\n238b439d698 (bugreport: add tool to generate debugging info,\n2020-04-16), and for \"diagnose\" in 6783fd3cef0 (builtin/diagnose.c:\ncreate 'git diagnose' builtin, 2022-08-12), which copied and adjusted\n\"bugreport\" documentation and code.\n\nIn the case of \"Documentation/git-stash.txt\" and \"builtin/stash.c\"\nthis is not a \"doc txt & -h consistency\" change, as we're changing\nboth versions, doing so here makes a subsequent change smaller.\n\nIn that case fix the incorrect \"[-o | --option <argument>]\" syntax,\nwhich should be \"[(-o | --option) <argument>]\", we were previously\nclaiming that only the long option accepted the \"<argument>\", which\nisn't what we meant.\n\nThe \"stash\" issue has been with us in both the \"-h\" and *.txt versions\nsince bd514cada4b (stash: introduce 'git stash store', 2013-06-15).\n\nWe could claim that this isn't a syntax issue if a \"vertical bar binds\ntighter than option and its argument\", but such a rule would change\ne.g. this \"cat-file\" SYNOPSIS example to mean something we don't:\n\n\t... [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\n\nWe have various other examples where the post-image here is already\nused, e.g. for \"format-patch\" (\"-o\"), \"grep\" (\"-m\"),\n\"submodule\" (\"set-branch -b\") etc.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 6 +++---\n builtin/bugreport.c         | 2 +-\n builtin/diagnose.c          | 2 +-\n builtin/stash.c             | 6 +++---\n 4 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex c5d70918283..4856f452511 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -14,12 +14,12 @@ SYNOPSIS\n 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [-m|--message <message>]\n+\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [-m|--message <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n \n DESCRIPTION\n -----------\n@@ -47,7 +47,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`).\n COMMANDS\n --------\n \n-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>...]::\n+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>...]::\n \n \tSave your local modifications to a new 'stash entry' and roll them\n \tback to HEAD (in the working tree and in the index).\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex faa268f3cfb..23170113cc8 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 28c394a62a5..474de9ec647 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 2274aae2556..51d40efaac7 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -29,7 +29,7 @@ static const char * const git_stash_usage[] = {\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n \tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n@@ -73,13 +73,13 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [-m|--message <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n \tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [-m|--message <message>]\\n\"\n+\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464839","messageId":"patch-v5-08.34-e029f1303af-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 08/34] doc txt & -h consistency: word-wrap","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:02Z","receivedAt":"2022-10-13T15:40:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the documentation and -h output for those built-in commands\nwhere both the -h output and *.txt were lacking in word-wrapping.\n\nThere are many more built-ins that could use this treatment, this\nchange is narrowed to those where this whitespace change is needed to\nmake the -h and *.txt consistent in the end.\n\nIn the case of \"Documentation/git-hash-object.txt\" and\n\"builtin/hash-object.c\" this is not a \"doc txt & -h consistency\"\nchange, as we're changing both versions, doing so here makes a\nsubsequent change smaller.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-hash-object.txt | 3 ++-\n Documentation/git-worktree.txt    | 3 ++-\n builtin/bugreport.c               | 3 ++-\n builtin/commit-graph.c            | 8 ++++----\n builtin/commit-tree.c             | 4 ++--\n builtin/diagnose.c                | 3 ++-\n builtin/hash-object.c             | 3 ++-\n builtin/init-db.c                 | 3 ++-\n builtin/interpret-trailers.c      | 4 +++-\n builtin/read-tree.c               | 4 +++-\n builtin/show-branch.c             | 3 ++-\n builtin/show-ref.c                | 4 +++-\n 12 files changed, 29 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex df9e2c58bdb..58670ef12f7 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>...\n+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+\t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \n DESCRIPTION\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex ada30c86a7c..063d6eeb99d 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees\n SYNOPSIS\n --------\n [verse]\n-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]\n+'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n+\t\t   [-b <new-branch>] <path> [<commit-ish>]\n 'git worktree list' [-v | --porcelain [-z]]\n 'git worktree lock' [--reason <string>] <worktree>\n 'git worktree move' <worktree> <new-path>\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 530895be55f..faa268f3cfb 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,8 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>] [--diagnose[=<mode>]\"),\n+\tN_(\"git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\\n\"\n+\t   \"              [--diagnose[=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 51557fe786e..cd346f95f08 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -13,10 +13,10 @@\n \tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append] \" \\\n-\t   \"[--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits] \" \\\n-\t   \"[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] \" \\\n-\t   \"<split options>\")\n+\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n+\t   \"                       <split options>\")\n \n static const char * builtin_commit_graph_verify_usage[] = {\n \tBUILTIN_COMMIT_GRAPH_VERIFY_USAGE,\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 63ea3229333..e4b85d29d56 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,8 +15,8 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n-\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] \"\n-\t\t\"[(-F <file>)...] <tree>\"),\n+\tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n+\t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 576e0e8e385..28c394a62a5 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,8 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>] [--mode=<mode>]\"),\n+\tN_(\"git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\\n\"\n+\t   \"             [--mode=<mode>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex fbae878c2b9..f7c16802f0c 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -80,7 +80,8 @@ static void hash_stdin_paths(const char *type, int no_filters, unsigned flags,\n int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n-\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n+\t\t   \"                [--stdin] [--] <file>...\"),\n \t\t\"git hash-object  --stdin-paths\",\n \t\tNULL\n \t};\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 546f9c595e7..08ba006d55e 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -515,7 +515,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n }\n \n static const char *const init_db_usage[] = {\n-\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>] [--shared[=<permissions>]] [<directory>]\"),\n+\tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 84748eafc01..4cf0cf265dc 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -13,7 +13,9 @@\n #include \"config.h\"\n \n static const char * const git_interpret_trailers_usage[] = {\n-\tN_(\"git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]\"),\n+\tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n+\t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n+\t   \"                       [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex 9f1f33e9546..b3a389e1b1f 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -38,7 +38,9 @@ static int list_tree(struct object_id *oid)\n }\n \n static const char * const read_tree_usage[] = {\n-\tN_(\"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+\tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n+\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n \ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex d3f5715e3e3..c013abaf942 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -14,7 +14,8 @@ static const char* show_branch_usage[] = {\n     N_(\"git show-branch [-a | --all] [-r | --remotes] [--topo-order | --date-order]\\n\"\n        \"                [--current] [--color[=<when>] | --no-color] [--sparse]\\n\"\n        \"                [--more=<n> | --list | --independent | --merge-base]\\n\"\n-       \"                [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\"),\n+       \"                [--no-name | --sha1-name] [--topics]\\n\"\n+       \"                [(<rev> | <glob>)...]\"),\n     N_(\"git show-branch (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\"),\n     NULL\n };\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 48569061087..3af6a53ee97 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -9,7 +9,9 @@\n #include \"parse-options.h\"\n \n static const char * const show_ref_usage[] = {\n-\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]\"),\n+\tN_(\"git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference]\\n\"\n+\t   \"             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\\n\"\n+\t   \"             [--heads] [--] [<pattern>...]\"),\n \tN_(\"git show-ref --exclude-existing[=<pattern>]\"),\n \tNULL\n };\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464840","messageId":"patch-v5-13.34-83d53381165-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 13/34] stash doc SYNOPSIS & -h: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:07Z","receivedAt":"2022-10-13T15:40:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt | 12 ++++++------\n builtin/stash.c             | 28 ++++++++++++++--------------\n 2 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 4856f452511..ea16d2eae7c 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,17 +9,17 @@ SYNOPSIS\n --------\n [verse]\n 'git stash' list [<log-options>]\n-'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]\n-'git stash' drop [-q|--quiet] [<stash>]\n-'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]\n+'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n+'git stash' drop [-q | --quiet] [<stash>]\n+'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n-'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\n-\t     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\n+'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n 'git stash' clear\n 'git stash' create [<message>]\n-'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>\n+'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 51d40efaac7..d91cf5fd3e1 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -24,16 +24,16 @@\n static const char * const git_stash_usage[] = {\n \tN_(\"git stash list [<options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n-\tN_(\"git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash branch <branchname> [<stash>]\"),\n \t\"git stash clear\",\n-\tN_(\"git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n@@ -48,17 +48,17 @@ static const char * const git_stash_show_usage[] = {\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q|--quiet] [<stash>]\"),\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n \tNULL\n };\n \n@@ -73,20 +73,20 @@ static const char * const git_stash_clear_usage[] = {\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m|--message) <message>] [-q|--quiet] <commit>\"),\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"          [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]\\n\"\n+\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n \t   \"          [--] [<pathspec>...]]\"),\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]\\n\"\n-\t   \"               [-u|--include-untracked] [-a|--all] [<message>]\"),\n+\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n+\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464841","messageId":"patch-v5-15.34-00b4cc7dfcc-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 15/34] doc SYNOPSIS & -h: use \"-\" to separate words in labels, not \"_\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:09Z","receivedAt":"2022-10-13T15:40:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change \"builtin/credential-cache--daemon.c\" to use \"<socket-path>\" not\n\"<socket_path>\" in a placeholder label, almost all of our\ndocumentation uses this form.\n\nThis is now consistent with the \"If a placeholder has multiple words,\nthey are separated by dashes\" guideline added in\n9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's\nadd a now-passing test to assert that that's the case.\n\nTo do this we need to introduce a very sed-powered parser to extract\nthe SYNOPSIS from the *.txt, and handle not all commands with \"-h\"\nhaving a corresponding *.txt (e.g. \"bisect--helper\"). We'll still want\nto handle syntax edge cases in the *.txt in subsequent commits for\nother checks, but let's do that then.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/credential-cache--daemon.c |  2 +-\n t/t0450-txt-doc-vs-help.sh         | 46 ++++++++++++++++++++++++++++++\n 2 files changed, 47 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex 4c6c89ab0de..ca672a6a619 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket_path>\",\n+\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex c8820bdd38f..efd00cfc51a 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -30,6 +30,35 @@ help_to_synopsis () {\n \techo \"$out\"\n }\n \n+builtin_to_txt () {\n+       echo \"$GIT_BUILD_DIR/Documentation/git-$1.txt\"\n+}\n+\n+txt_to_synopsis () {\n+\tbuiltin=\"$1\" &&\n+\tout_dir=\"out/$builtin\" &&\n+\tout=\"$out_dir/txt.synopsis\" &&\n+\tif test -f \"$out\"\n+\tthen\n+\t\techo \"$out\" &&\n+\t\treturn 0\n+\tfi &&\n+\tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tsed -n \\\n+\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t\t/^$/d;\n+\t\t\t/^\\[verse\\]$/d;\n+\n+\t\t\tp;\n+\t\t}' \\\n+\t\t<\"$b2t\" >\"$out\" &&\n+\techo \"$out\"\n+}\n+\n+check_dashed_labels () {\n+\t! grep -E \"<[^>_-]+_\" \"$1\"\n+}\n+\n HT=\"\t\"\n \n while read builtin\n@@ -39,6 +68,23 @@ do\n \t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n \t\t! grep \"$HT\" \"$h2s\"\n \t'\n+\n+\ttest_expect_success \"$builtin -h output has dashed labels\" '\n+\t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n+\t'\n+\n+\ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n+\tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n+\n+\tif test -f \"$txt\"\n+\tthen\n+\t\ttest_set_prereq \"$preq\"\n+\tfi &&\n+\n+\t# *.txt output assertions\n+\ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n+\t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n+\t'\n done <builtins\n \n test_done\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464842","messageId":"patch-v5-11.34-84a81046a95-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 11/34] doc txt & -h consistency: balance unbalanced \"[\" and \"]\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:05Z","receivedAt":"2022-10-13T15:40:26Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a \"-h\" output syntax issue introduced when \"--diagnose\" was added\nin aac0e8ffeee (builtin/bugreport.c: create '--diagnose' option,\n2022-08-12): We need to close the \"[\" we opened. The\ncorresponding *.txt change did not have the same issue.\n\nThe \"help -h\" output then had one \"]\" too many, which is an issue\nintroduced in b40845293b5 (help: correct the usage string in -h and\ndocumentation, 2021-09-10).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bugreport.c | 2 +-\n builtin/help.c      | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 23170113cc8..bb138161943 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -61,7 +61,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n \n static const char * const bugreport_usage[] = {\n \tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n-\t   \"              [--diagnose[=<mode>]\"),\n+\t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\n \ndiff --git a/builtin/help.c b/builtin/help.c\nindex 6f2796f211e..53f2812dfb1 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -88,7 +88,7 @@ static struct option builtin_help_options[] = {\n };\n \n static const char * const builtin_help_usage[] = {\n-\t\"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]\",\n+\t\"git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]\",\n \tN_(\"git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]\"),\n \t\"git help [-g|--guides]\",\n \t\"git help [-c|--config]\",\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464843","messageId":"patch-v5-10.34-323afb78f75-20221013T153625Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 10/34] doc txt & -h consistency: add \"-z\" to cat-file \"-h\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:04Z","receivedAt":"2022-10-13T15:40:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix a bug in db9d67f2e9c (builtin/cat-file.c: support NUL-delimited\ninput with `-z`, 2022-07-22), before that change the SYNOPSIS and \"-h\"\noutput were the same, but not afterwards.\n\nThat change followed a similar earlier divergence in\n473fa2df08d (Documentation: add --batch-command to cat-file synopsis,\n2022-04-07). Subsequent commits will fix this sort of thing more\nsystematically, but let's fix this one as a one-off.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/cat-file.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/cat-file.c b/builtin/cat-file.c\nindex 989eee0bb4c..fa7bd891692 100644\n--- a/builtin/cat-file.c\n+++ b/builtin/cat-file.c\n@@ -893,7 +893,7 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)\n \t\tN_(\"git cat-file (-t | -s) [--allow-unknown-type] <object>\"),\n \t\tN_(\"git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]\\n\"\n \t\t   \"             [--buffer] [--follow-symlinks] [--unordered]\\n\"\n-\t\t   \"             [--textconv | --filters]\"),\n+\t\t   \"             [--textconv | --filters] [-z]\"),\n \t\tN_(\"git cat-file (--textconv | --filters)\\n\"\n \t\t   \"             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]\"),\n \t\tNULL\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464844","messageId":"patch-v5-12.34-f5bd52cb103-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 12/34] doc txt & -h consistency: correct padding around \"[]()\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:06Z","receivedAt":"2022-10-13T15:40:30Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The whitespace padding of alternatives should be of the form \"[-f |\n--force]\" not \"[-f|--force]\". Likewise we should not have padding\nbefore the first option, so \"(--all | <pack-filename>...)\" is correct,\nnot \"( --all | <pack-filename>... )\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-diff-files.txt     | 2 +-\n Documentation/git-hash-object.txt    | 2 +-\n Documentation/git-merge-base.txt     | 4 ++--\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/git-prune-packed.txt   | 2 +-\n Documentation/git-rerere.txt         | 2 +-\n Documentation/git-send-pack.txt      | 2 +-\n Documentation/git-show-branch.txt    | 4 ++--\n Documentation/git-show-ref.txt       | 4 ++--\n Documentation/git-var.txt            | 2 +-\n Documentation/git-verify-pack.txt    | 2 +-\n builtin/bugreport.c                  | 2 +-\n builtin/commit-graph.c               | 2 +-\n builtin/diagnose.c                   | 2 +-\n builtin/sparse-checkout.c            | 2 +-\n 15 files changed, 18 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex bf1febb9ae7..591e3801b7b 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n+'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt\nindex 58670ef12f7..472b5bb995b 100644\n--- a/Documentation/git-hash-object.txt\n+++ b/Documentation/git-hash-object.txt\n@@ -9,7 +9,7 @@ git-hash-object - Compute object ID and optionally creates a blob from a file\n SYNOPSIS\n --------\n [verse]\n-'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters]\n+'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters]\n \t\t[--stdin [--literally]] [--] <file>...\n 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters]\n \ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b01ba3d3565 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n+'git merge-base' [-a | --all] <commit> <commit>...\n+'git merge-base' [-a | --all] --octopus <commit>...\n 'git merge-base' --is-ancestor <commit> <commit>\n 'git merge-base' --independent <commit>...\n 'git merge-base' --fork-point <ref> [<commit>]\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e52..dda80a740c8 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n+'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt\nindex 9fed59a3172..844d6f808a0 100644\n--- a/Documentation/git-prune-packed.txt\n+++ b/Documentation/git-prune-packed.txt\n@@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files\n SYNOPSIS\n --------\n [verse]\n-'git prune-packed' [-n|--dry-run] [-q|--quiet]\n+'git prune-packed' [-n | --dry-run] [-q | --quiet]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 4b613d4140c..9d0e6f53e7e 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear|forget <pathspec>|diff|remaining|status|gc]\n+'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex be41f119740..e0c71623432 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n-\t\t[--[no-]signed|--signed=(true|false|if-asked)]\n+\t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\n \n DESCRIPTION\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex e5ec6b467f9..71f608b1ff1 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits\n SYNOPSIS\n --------\n [verse]\n-'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order]\n+'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order]\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n \t\t[(<rev> | <glob>)...]\n-'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n+'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ab4d271925d..d1d56f68b43 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -8,8 +8,8 @@ git-show-ref - List references in a local repository\n SYNOPSIS\n --------\n [verse]\n-'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference]\n-\t     [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags]\n+'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference]\n+\t     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n \t     [--heads] [--] [<pattern>...]\n 'git show-ref' --exclude-existing[=<pattern>]\n \ndiff --git a/Documentation/git-var.txt b/Documentation/git-var.txt\nindex 387cc1b9142..6aa521fab23 100644\n--- a/Documentation/git-var.txt\n+++ b/Documentation/git-var.txt\n@@ -9,7 +9,7 @@ git-var - Show a Git logical variable\n SYNOPSIS\n --------\n [verse]\n-'git var' ( -l | <variable> )\n+'git var' (-l | <variable>)\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c20..b8720dce8ab 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files\n SYNOPSIS\n --------\n [verse]\n-'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ...\n+'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\n \n \n DESCRIPTION\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex bb138161943..61d93383f51 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex cd346f95f08..13cbb75ca28 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -14,7 +14,7 @@\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n \tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n-\t   \"                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]\\n\" \\\n+\t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\n \ndiff --git a/builtin/diagnose.c b/builtin/diagnose.c\nindex 474de9ec647..d52015c67a4 100644\n--- a/builtin/diagnose.c\n+++ b/builtin/diagnose.c\n@@ -3,7 +3,7 @@\n #include \"diagnose.h\"\n \n static const char * const diagnose_usage[] = {\n-\tN_(\"git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\\n\"\n+\tN_(\"git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"             [--mode=<mode>]\"),\n \tNULL\n };\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 287716db68e..aac0f708e42 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init|list|set|add|reapply|disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464845","messageId":"patch-v5-14.34-760bc0a6727-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 14/34] doc txt & -h consistency: use \"<options>\", not \"<options>...\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:08Z","receivedAt":"2022-10-13T15:40:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"It's arguably more correct to say \"[<option>...]\" than either of these\nforms, but the vast majority of our documentation uses the\n\"[<options>]\" form to indicate an arbitrary number of options, let's\ndo the same in these cases, which were the odd ones out.\n\nIn the case of \"mv\" and \"sparse-checkout\" let's add the missing \"[]\"\nto indicate that these are optional.\n\nIn the case of \"t/helper/test-proc-receive.c\" there is no *.txt\nversion, making it the only hunk in this commit that's not a \"doc txt\n& -h consistency\" change.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-mv.txt     | 2 +-\n Documentation/git-status.txt | 2 +-\n builtin/pack-objects.c       | 4 ++--\n builtin/sparse-checkout.c    | 2 +-\n t/helper/test-proc-receive.c | 2 +-\n 5 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 79449bf98fe..972a055fbd8 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' <options>... <args>...\n+'git mv' [<options>] <args>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 54a4b29b473..5e438a7fdc1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -9,7 +9,7 @@ git-status - Show the working tree status\n SYNOPSIS\n --------\n [verse]\n-'git status' [<options>...] [--] [<pathspec>...]\n+'git status' [<options>] [--] [<pathspec>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3658c05cafc..573d0b20b76 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -180,8 +180,8 @@ static inline void oe_set_delta_size(struct packing_data *pack,\n #define SET_DELTA_SIBLING(obj, val) oe_set_delta_sibling(&to_pack, obj, val)\n \n static const char *pack_usage[] = {\n-\tN_(\"git pack-objects --stdout [<options>...] [< <ref-list> | < <object-list>]\"),\n-\tN_(\"git pack-objects [<options>...] <base-name> [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects --stdout [<options>] [< <ref-list> | < <object-list>]\"),\n+\tN_(\"git pack-objects [<options>] <base-name> [< <ref-list> | < <object-list>]\"),\n \tNULL\n };\n \ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex aac0f708e42..58a22503f04 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -20,7 +20,7 @@\n static const char *empty_base = \"\";\n \n static char const * const builtin_sparse_checkout_usage[] = {\n-\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) <options>\"),\n+\tN_(\"git sparse-checkout (init | list | set | add | reapply | disable) [<options>]\"),\n \tNULL\n };\n \ndiff --git a/t/helper/test-proc-receive.c b/t/helper/test-proc-receive.c\nindex cc08506cf0b..a4b305f4947 100644\n--- a/t/helper/test-proc-receive.c\n+++ b/t/helper/test-proc-receive.c\n@@ -6,7 +6,7 @@\n #include \"test-tool.h\"\n \n static const char *proc_receive_usage[] = {\n-\t\"test-tool proc-receive [<options>...]\",\n+\t\"test-tool proc-receive [<options>]\",\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464846","messageId":"patch-v5-16.34-503bd076a6b-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 16/34] doc txt & -h consistency: fix mismatching labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:10Z","receivedAt":"2022-10-13T15:40:50Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various inconsistencies between command SYNOPSIS and the\ncorresponding -h output where our translatable labels didn't match\nup.\n\nIn some cases we need to adjust the prose that follows the SYNOPSIS\naccordingly, as it refers back to the changed label.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt                    | 10 +++++-----\n Documentation/git-credential-cache--daemon.txt |  4 ++--\n Documentation/git-mv.txt                       |  4 ++--\n Documentation/git-receive-pack.txt             |  4 ++--\n Documentation/git-tag.txt                      | 18 +++++++++---------\n Documentation/git-upload-archive.txt           |  4 ++--\n builtin/bugreport.c                            |  2 +-\n builtin/clean.c                                |  2 +-\n builtin/commit-graph.c                         |  4 ++--\n builtin/for-each-repo.c                        |  2 +-\n builtin/pack-redundant.c                       |  2 +-\n builtin/rerere.c                               |  2 +-\n builtin/rev-list.c                             |  2 +-\n builtin/stash.c                                |  2 +-\n builtin/unpack-file.c                          |  2 +-\n builtin/upload-archive.c                       |  2 +-\n builtin/verify-pack.c                          |  2 +-\n builtin/worktree.c                             |  2 +-\n 18 files changed, 35 insertions(+), 35 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 91742633fa8..8347c6eed79 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\n-'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n+'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\n \n DESCRIPTION\n -----------\n@@ -20,16 +20,16 @@ Normally, only files unknown to Git are removed, but if the `-x`\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n \n-If any optional `<path>...` arguments are given, only those paths\n-are affected.\n+If any optional `<pathspec>...` arguments are given, only those paths\n+that match the pathspec are affected.\n \n OPTIONS\n -------\n -d::\n-\tNormally, when no <path> is specified, git clean will not\n+\tNormally, when no <pathspec> is specified, git clean will not\n \trecurse into untracked directories to avoid removing too much.\n \tSpecify -d to have it recurse into such directories as well.\n-\tIf any paths are specified, -d is irrelevant; all untracked\n+\tIf a <pathspec> is specified, -d is irrelevant; all untracked\n \tfiles matching the specified paths (with exceptions for nested\n \tgit directories mentioned under `--force`) will be removed.\n \ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 01e1c214dd8..650a15a7edf 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\n@@ -16,7 +16,7 @@ DESCRIPTION\n NOTE: You probably don't want to invoke this command yourself; it is\n started automatically when you use linkgit:git-credential-cache[1].\n \n-This command listens on the Unix domain socket specified by `<socket>`\n+This command listens on the Unix domain socket specified by `<socket-path>`\n for `git-credential-cache` clients. Clients may store and retrieve\n credentials. Each credential is held for a timeout specified by the\n client; once no credentials are held, the daemon exits.\ndiff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt\nindex 972a055fbd8..fb0220fd18d 100644\n--- a/Documentation/git-mv.txt\n+++ b/Documentation/git-mv.txt\n@@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [<options>] <args>...\n+'git mv' [<options>] <source>... <destination>\n \n DESCRIPTION\n -----------\n@@ -30,7 +30,7 @@ OPTIONS\n -------\n -f::\n --force::\n-\tForce renaming or moving of a file even if the target exists\n+\tForce renaming or moving of a file even if the <destination> exists.\n -k::\n \tSkip move or rename actions which would lead to an error\n \tcondition. An error happens when a source is neither existing nor\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 014a78409b9..5c297db1a4b 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\n@@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1].\n \n OPTIONS\n -------\n-<directory>::\n+<git-dir>::\n \tThe repository to sync into.\n \n --http-backend-info-refs::\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31a97a1b6c5..fdc72b5875a 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]\n+'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\n \t<tagname> [<commit> | <object>]\n 'git tag' -d <tagname>...\n 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\n@@ -26,19 +26,19 @@ to delete, list or verify tags.\n \n Unless `-f` is given, the named tag must not yet exist.\n \n-If one of `-a`, `-s`, or `-u <keyid>` is passed, the command\n+If one of `-a`, `-s`, or `-u <key-id>` is passed, the command\n creates a 'tag' object, and requires a tag message.  Unless\n `-m <msg>` or `-F <file>` is given, an editor is started for the user to type\n in the tag message.\n \n-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`\n+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`\n are absent, `-a` is implied.\n \n Otherwise, a tag reference that points directly at the given object\n (i.e., a lightweight tag) is created.\n \n A GnuPG signed tag object will be created when `-s` or `-u\n-<keyid>` is used.  When `-u <keyid>` is not used, the\n+<key-id>` is used.  When `-u <key-id>` is not used, the\n committer identity for the current user is used to find the\n GnuPG key for signing. \tThe configuration variable `gpg.program`\n is used to specify custom GnuPG binary.\n@@ -72,8 +72,8 @@ OPTIONS\n \tOverride `tag.gpgSign` configuration variable that is\n \tset to force each and every tag to be signed.\n \n--u <keyid>::\n---local-user=<keyid>::\n+-u <key-id>::\n+--local-user=<key-id>::\n \tMake a GPG-signed tag, using the given key.\n \n -f::\n@@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines.\n \tUse the given tag message (instead of prompting).\n \tIf multiple `-m` options are given, their values are\n \tconcatenated as separate paragraphs.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n+\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n \tis given.\n \n -F <file>::\n --file=<file>::\n \tTake the tag message from the given file.  Use '-' to\n \tread the message from the standard input.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u <keyid>`\n+\tImplies `-a` if none of `-a`, `-s`, or `-u <key-id>`\n \tis given.\n \n -e::\n@@ -220,7 +220,7 @@ it in the repository configuration as follows:\n \n -------------------------------------\n [user]\n-    signingKey = <gpg-keyid>\n+    signingKey = <gpg-key_id>\n -------------------------------------\n \n `pager.tag` is only respected when listing tags, i.e., when `-l` is\ndiff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt\nindex fba0f1c1b27..e8eb10baad7 100644\n--- a/Documentation/git-upload-archive.txt\n+++ b/Documentation/git-upload-archive.txt\n@@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive\n SYNOPSIS\n --------\n [verse]\n-'git upload-archive' <directory>\n+'git upload-archive' <repository>\n \n DESCRIPTION\n -----------\n@@ -54,7 +54,7 @@ access via non-smart-http.\n \n OPTIONS\n -------\n-<directory>::\n+<repository>::\n \tThe repository to get a tar archive from.\n \n GIT\ndiff --git a/builtin/bugreport.c b/builtin/bugreport.c\nindex 61d93383f51..96052541cbf 100644\n--- a/builtin/bugreport.c\n+++ b/builtin/bugreport.c\n@@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)\n }\n \n static const char * const bugreport_usage[] = {\n-\tN_(\"git bugreport [(-o | --output-directory) <file>] [(-s | --suffix) <format>]\\n\"\n+\tN_(\"git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]\\n\"\n \t   \"              [--diagnose[=<mode>]]\"),\n \tNULL\n };\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 5466636e666..6f039f555b2 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <paths>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit-graph.c b/builtin/commit-graph.c\nindex 13cbb75ca28..e8f77f535f3 100644\n--- a/builtin/commit-graph.c\n+++ b/builtin/commit-graph.c\n@@ -10,10 +10,10 @@\n #include \"tag.h\"\n \n #define BUILTIN_COMMIT_GRAPH_VERIFY_USAGE \\\n-\tN_(\"git commit-graph verify [--object-dir <objdir>] [--shallow] [--[no-]progress]\")\n+\tN_(\"git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]\")\n \n #define BUILTIN_COMMIT_GRAPH_WRITE_USAGE \\\n-\tN_(\"git commit-graph write [--object-dir <objdir>] [--append]\\n\" \\\n+\tN_(\"git commit-graph write [--object-dir <dir>] [--append]\\n\" \\\n \t   \"                       [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\\n\" \\\n \t   \"                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\\n\" \\\n \t   \"                       <split options>\")\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex fd86e5a8619..c6379b783c8 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <command-args>\"),\n+\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/pack-redundant.c b/builtin/pack-redundant.c\nindex ed9b9013a5f..ecd49ca268f 100644\n--- a/builtin/pack-redundant.c\n+++ b/builtin/pack-redundant.c\n@@ -14,7 +14,7 @@\n #define BLKSIZE 512\n \n static const char pack_redundant_usage[] =\n-\"git pack-redundant [--verbose] [--alt-odb] (--all | <filename.pack>...)\";\n+\"git pack-redundant [--verbose] [--alt-odb] (--all | <pack-filename>...)\";\n \n static int load_all_packs, verbose, alt_odb;\n \ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 83d7a778e37..12570537d37 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <path>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n \tNULL,\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex f67e2b33555..ada68a4af5e 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit-id>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex d91cf5fd3e1..83c9591ea6d 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -22,7 +22,7 @@\n #define INCLUDE_ALL_FILES 2\n \n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tN_(\"git stash list [<log-options>]\"),\n \tN_(\"git stash show [<options>] [<stash>]\"),\n \tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n \tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\ndiff --git a/builtin/unpack-file.c b/builtin/unpack-file.c\nindex 58652229f27..9e8119dd354 100644\n--- a/builtin/unpack-file.c\n+++ b/builtin/unpack-file.c\n@@ -27,7 +27,7 @@ int cmd_unpack_file(int argc, const char **argv, const char *prefix)\n \tstruct object_id oid;\n \n \tif (argc != 2 || !strcmp(argv[1], \"-h\"))\n-\t\tusage(\"git unpack-file <sha1>\");\n+\t\tusage(\"git unpack-file <blob>\");\n \tif (get_oid(argv[1], &oid))\n \t\tdie(\"Not a valid object name %s\", argv[1]);\n \ndiff --git a/builtin/upload-archive.c b/builtin/upload-archive.c\nindex 98d028dae67..945ee2b4126 100644\n--- a/builtin/upload-archive.c\n+++ b/builtin/upload-archive.c\n@@ -10,7 +10,7 @@\n #include \"strvec.h\"\n \n static const char upload_archive_usage[] =\n-\t\"git upload-archive <repo>\";\n+\t\"git upload-archive <repository>\";\n \n static const char deadchild[] =\n \"git upload-archive: archiver died with error\";\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex 05c52135946..db9ac5c4606 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n \tNULL\n };\n \ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex c6710b25520..5bfc18e5a24 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -23,7 +23,7 @@ static const char * const worktree_usage[] = {\n \tN_(\"git worktree prune [<options>]\"),\n \tN_(\"git worktree remove [<options>] <worktree>\"),\n \tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <path>\"),\n+\tN_(\"git worktree unlock <worktree>\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464847","messageId":"patch-v5-17.34-a27ce91d9b3-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 17/34] doc txt & -h consistency: add or fix optional \"--\" syntax","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:11Z","receivedAt":"2022-10-13T15:40:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add the \"[--]\" for those cases where the *.txt and -h were\ninconsistent, or where we incorrectly stated in one but not the other\nthat the \"--\" was mandatory.\n\nIn the case of \"rev-list\" both sides were wrong, as we we don't\nrequire one or more paths if \"--\" is used, e.g. this is OK:\n\n\tgit rev-list HEAD --\n\nThat part of this change is not a \"doc txt & -h consistency\" change,\nas we're changing both versions, doing so here makes both sides\nconsistent.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rev-list.txt | 2 +-\n builtin/for-each-repo.c        | 2 +-\n builtin/rev-list.c             | 2 +-\n builtin/verify-pack.c          | 2 +-\n 4 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 20bb8e82176..51029a22715 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order\n SYNOPSIS\n --------\n [verse]\n-'git rev-list' [<options>] <commit>... [[--] <path>...]\n+'git rev-list' [<options>] <commit>... [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/for-each-repo.c b/builtin/for-each-repo.c\nindex c6379b783c8..d45d873f579 100644\n--- a/builtin/for-each-repo.c\n+++ b/builtin/for-each-repo.c\n@@ -6,7 +6,7 @@\n #include \"string-list.h\"\n \n static const char * const for_each_repo_usage[] = {\n-\tN_(\"git for-each-repo --config=<config> <arguments>\"),\n+\tN_(\"git for-each-repo --config=<config> [--] <arguments>\"),\n \tNULL\n };\n \ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex ada68a4af5e..3acd93f71e1 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -20,7 +20,7 @@\n #include \"packfile.h\"\n \n static const char rev_list_usage[] =\n-\"git rev-list [<options>] <commit>... [-- <path>...]\\n\"\n+\"git rev-list [<options>] <commit>... [--] [<path>...]\\n\"\n \"\\n\"\n \"  limiting output:\\n\"\n \"    --max-count=<n>\\n\"\ndiff --git a/builtin/verify-pack.c b/builtin/verify-pack.c\nindex db9ac5c4606..27d6f75fd8a 100644\n--- a/builtin/verify-pack.c\n+++ b/builtin/verify-pack.c\n@@ -56,7 +56,7 @@ static int verify_one_pack(const char *path, unsigned int flags, const char *has\n }\n \n static const char * const verify_pack_usage[] = {\n-\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] <pack>.idx...\"),\n+\tN_(\"git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464848","messageId":"patch-v5-19.34-f5ad5f0a87f-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 19/34] doc txt & -h consistency: add missing options and labels","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:13Z","receivedAt":"2022-10-13T15:41:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix various issues of SYNOPSIS and -h output syntax where:\n\n * Options such as --force were missing entirely\n * ...or the short option, such as -f\n\n * We said \"opts\" or \"options\", but could instead enumerate\n   the (small) set of supported options\n\n * Options that were missing entirely (ls-remote's --sort=<key>)\n\n   As we can specify \"--sort\" multiple times (it's backed by a\n   string-list\" it should really be \"[(--sort=<key>)...]\", which is\n   what \"git for-each-ref\" lists it as, but let's leave that issue for\n   a subsequent cleanup, and stop at making these consistent. Other\n   \"ref-filter.h\" users share the same issue, e.g. \"git-branch.txt\".\n\n * For \"verify-tag\" and \"verify-commit\" we were missing the \"--raw\"\n   option.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-send-pack.txt          |  3 ++-\n Documentation/git-sparse-checkout.txt    |  2 +-\n Documentation/git-update-server-info.txt |  8 +++++++-\n Documentation/git-verify-commit.txt      |  2 +-\n Documentation/git-verify-tag.txt         |  2 +-\n builtin/credential-cache--daemon.c       |  2 +-\n builtin/describe.c                       |  5 +++--\n builtin/diff-index.c                     |  2 +-\n builtin/ls-remote.c                      |  2 +-\n builtin/pack-refs.c                      |  2 +-\n builtin/revert.c                         |  9 +++++----\n builtin/send-pack.c                      |  1 +\n builtin/symbolic-ref.c                   |  5 +++--\n builtin/tag.c                            | 10 ++++++----\n builtin/update-server-info.c             |  2 +-\n builtin/upload-pack.c                    |  3 ++-\n builtin/verify-commit.c                  |  2 +-\n builtin/verify-tag.c                     |  2 +-\n help.c                                   |  2 +-\n 19 files changed, 40 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex e0c71623432..595b002152f 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,8 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]\n+'git send-pack' [--mirror] [--dry-run] [--force]\n+\t\t[--receive-pack=<git-receive-pack>]\n \t\t[--verbose] [--thin] [--atomic]\n \t\t[--[no-]signed | --signed=(true|false|if-asked)]\n \t\t[<host>:]<directory> (--all | <ref>...)\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 872436d7426..68392d2a56e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout' <subcommand> [<options>]\n+'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt\nindex 969bb2e15f1..17e429dbd09 100644\n--- a/Documentation/git-update-server-info.txt\n+++ b/Documentation/git-update-server-info.txt\n@@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers\n SYNOPSIS\n --------\n [verse]\n-'git update-server-info'\n+'git update-server-info' [-f | --force]\n \n DESCRIPTION\n -----------\n@@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover\n what references and packs the server has.  This command\n generates such auxiliary files.\n \n+OPTIONS\n+-------\n+-f::\n+--force::\n+\tupdate the info files from scratch.\n+\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt\nindex 92097f6673d..aee4c40eac4 100644\n--- a/Documentation/git-verify-commit.txt\n+++ b/Documentation/git-verify-commit.txt\n@@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits\n SYNOPSIS\n --------\n [verse]\n-'git verify-commit' <commit>...\n+'git verify-commit' [-v | --verbose] [--raw] <commit>...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt\nindex 0b8075dad96..81d50ecc4c6 100644\n--- a/Documentation/git-verify-tag.txt\n+++ b/Documentation/git-verify-tag.txt\n@@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags\n SYNOPSIS\n --------\n [verse]\n-'git verify-tag' [--format=<format>] <tag>...\n+'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex ca672a6a619..d4eb0097d24 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [opts] <socket-path>\",\n+\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\ndiff --git a/builtin/describe.c b/builtin/describe.c\nindex e17c4b4c69b..23e3f05fb10 100644\n--- a/builtin/describe.c\n+++ b/builtin/describe.c\n@@ -23,8 +23,9 @@\n define_commit_slab(commit_names, struct commit_name *);\n \n static const char * const describe_usage[] = {\n-\tN_(\"git describe [<options>] [<commit-ish>...]\"),\n-\tN_(\"git describe [<options>] --dirty\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\"),\n+\tN_(\"git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\"),\n+\tN_(\"git describe <blob>\"),\n \tNULL\n };\n \ndiff --git a/builtin/diff-index.c b/builtin/diff-index.c\nindex e667cf52e7d..aea139b9d8f 100644\n--- a/builtin/diff-index.c\n+++ b/builtin/diff-index.c\n@@ -9,7 +9,7 @@\n #include \"submodule.h\"\n \n static const char diff_cache_usage[] =\n-\"git diff-index [-m] [--cached] \"\n+\"git diff-index [-m] [--cached] [--merge-base] \"\n \"[<common-diff-options>] <tree-ish> [<path>...]\"\n \"\\n\"\n COMMON_DIFF_OPTIONS_HELP;\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex df44e5cc0d1..5d5ac038716 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -7,7 +7,7 @@\n \n static const char * const ls_remote_usage[] = {\n \tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\\n\"\n-\t   \"              [-q | --quiet] [--exit-code] [--get-url]\\n\"\n+\t   \"              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\\n\"\n \t   \"              [--symref] [<repository> [<refs>...]]\"),\n \tNULL\n };\ndiff --git a/builtin/pack-refs.c b/builtin/pack-refs.c\nindex cfbd5c36c76..27c2ca06acb 100644\n--- a/builtin/pack-refs.c\n+++ b/builtin/pack-refs.c\n@@ -5,7 +5,7 @@\n #include \"repository.h\"\n \n static char const * const pack_refs_usage[] = {\n-\tN_(\"git pack-refs [<options>]\"),\n+\tN_(\"git pack-refs [--all] [--no-prune]\"),\n \tNULL\n };\n \ndiff --git a/builtin/revert.c b/builtin/revert.c\nindex ee2a0807f01..ee32c714a76 100644\n--- a/builtin/revert.c\n+++ b/builtin/revert.c\n@@ -21,14 +21,15 @@\n  */\n \n static const char * const revert_usage[] = {\n-\tN_(\"git revert [<options>] <commit-ish>...\"),\n-\tN_(\"git revert <subcommand>\"),\n+\tN_(\"git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git revert (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \n static const char * const cherry_pick_usage[] = {\n-\tN_(\"git cherry-pick [<options>] <commit-ish>...\"),\n-\tN_(\"git cherry-pick <subcommand>\"),\n+\tN_(\"git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\\n\"\n+\t   \"                [-S[<keyid>]] <commit>...\"),\n+\tN_(\"git cherry-pick (--continue | --skip | --abort | --quit)\"),\n \tNULL\n };\n \ndiff --git a/builtin/send-pack.c b/builtin/send-pack.c\nindex 64962be0168..4c5d125fa0a 100644\n--- a/builtin/send-pack.c\n+++ b/builtin/send-pack.c\n@@ -20,6 +20,7 @@ static const char * const send_pack_usage[] = {\n \tN_(\"git send-pack [--mirror] [--dry-run] [--force]\\n\"\n \t   \"              [--receive-pack=<git-receive-pack>]\\n\"\n \t   \"              [--verbose] [--thin] [--atomic]\\n\"\n+\t   \"              [--[no-]signed | --signed=(true|false|if-asked)]\\n\"\n \t   \"              [<host>:]<directory> (--all | <ref>...)\"),\n \tNULL,\n };\ndiff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c\nindex 1b0f10225f0..50b6df78df0 100644\n--- a/builtin/symbolic-ref.c\n+++ b/builtin/symbolic-ref.c\n@@ -5,8 +5,9 @@\n #include \"parse-options.h\"\n \n static const char * const git_symbolic_ref_usage[] = {\n-\tN_(\"git symbolic-ref [<options>] <name> [<ref>]\"),\n-\tN_(\"git symbolic-ref -d [-q] <name>\"),\n+\tN_(\"git symbolic-ref [-m <reason>] <name> <ref>\"),\n+\tN_(\"git symbolic-ref [-q] [--short] <name>\"),\n+\tN_(\"git symbolic-ref --delete [-q] <name>\"),\n \tNULL\n };\n \ndiff --git a/builtin/tag.c b/builtin/tag.c\nindex 75dece0e4f1..d428c45dc8d 100644\n--- a/builtin/tag.c\n+++ b/builtin/tag.c\n@@ -23,11 +23,13 @@\n #include \"date.h\"\n \n static const char * const git_tag_usage[] = {\n-\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]\\n\"\n-\t   \"        <tagname> [<head>]\"),\n+\tN_(\"git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]\\n\"\n+\t   \"        <tagname> [<commit> | <object>]\"),\n \tN_(\"git tag -d <tagname>...\"),\n-\tN_(\"git tag -l [-n[<num>]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>]\\n\"\n-\t   \"        [--format=<format>] [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n+\tN_(\"git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]\\n\"\n+\t   \"        [--points-at <object>] [--column[=<options>] | --no-column]\\n\"\n+\t   \"        [--create-reflog] [--sort=<key>] [--format=<format>]\\n\"\n+\t   \"        [--merged <commit>] [--no-merged <commit>] [<pattern>...]\"),\n \tN_(\"git tag -v [--format=<format>] <tagname>...\"),\n \tNULL\n };\ndiff --git a/builtin/update-server-info.c b/builtin/update-server-info.c\nindex 880fffec587..d2239c9ef4d 100644\n--- a/builtin/update-server-info.c\n+++ b/builtin/update-server-info.c\n@@ -4,7 +4,7 @@\n #include \"parse-options.h\"\n \n static const char * const update_server_info_usage[] = {\n-\t\"git update-server-info [--force]\",\n+\t\"git update-server-info [-f | --force]\",\n \tNULL\n };\n \ndiff --git a/builtin/upload-pack.c b/builtin/upload-pack.c\nindex 125af53885f..25b69da2bf2 100644\n--- a/builtin/upload-pack.c\n+++ b/builtin/upload-pack.c\n@@ -8,7 +8,8 @@\n #include \"serve.h\"\n \n static const char * const upload_pack_usage[] = {\n-\tN_(\"git upload-pack [<options>] <dir>\"),\n+\tN_(\"git-upload-pack [--[no-]strict] [--timeout=<n>] [--stateless-rpc]\\n\"\n+\t   \"                [--advertise-refs] <directory>\"),\n \tNULL\n };\n \ndiff --git a/builtin/verify-commit.c b/builtin/verify-commit.c\nindex 40c69a0bedd..3ebad32b0f1 100644\n--- a/builtin/verify-commit.c\n+++ b/builtin/verify-commit.c\n@@ -16,7 +16,7 @@\n #include \"gpg-interface.h\"\n \n static const char * const verify_commit_usage[] = {\n-\t\tN_(\"git verify-commit [-v | --verbose] <commit>...\"),\n+\t\tN_(\"git verify-commit [-v | --verbose] [--raw] <commit>...\"),\n \t\tNULL\n };\n \ndiff --git a/builtin/verify-tag.c b/builtin/verify-tag.c\nindex f45136a06ba..217566952d8 100644\n--- a/builtin/verify-tag.c\n+++ b/builtin/verify-tag.c\n@@ -15,7 +15,7 @@\n #include \"ref-filter.h\"\n \n static const char * const verify_tag_usage[] = {\n-\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] <tag>...\"),\n+\t\tN_(\"git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...\"),\n \t\tNULL\n };\n \ndiff --git a/help.c b/help.c\nindex d04542d8261..f1e090a4428 100644\n--- a/help.c\n+++ b/help.c\n@@ -757,7 +757,7 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \tstruct strbuf buf = STRBUF_INIT;\n \tint build_options = 0;\n \tconst char * const usage[] = {\n-\t\tN_(\"git version [<options>]\"),\n+\t\tN_(\"git version [--build-options]\"),\n \t\tNULL\n \t};\n \tstruct option options[] = {\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464849","messageId":"patch-v5-20.34-058b22e22f7-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 20/34] doc txt & -h consistency: make \"rerere\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:14Z","receivedAt":"2022-10-13T15:41:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"For \"rerere\" say \"pathspec\" consistently, and list the subcommands in\nthe order that they're discussed in the \"COMMANDS\" section of the\ndocumentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-rerere.txt | 2 +-\n builtin/rerere.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex 9d0e6f53e7e..992b469270c 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' [clear | forget <pathspec> | diff | remaining | status | gc]\n+'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/rerere.c b/builtin/rerere.c\nindex 12570537d37..8b7392d5b44 100644\n--- a/builtin/rerere.c\n+++ b/builtin/rerere.c\n@@ -10,7 +10,7 @@\n #include \"pathspec.h\"\n \n static const char * const rerere_usage[] = {\n-\tN_(\"git rerere [clear | forget <pathspec>... | status | remaining | diff | gc]\"),\n+\tN_(\"git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]\"),\n \tNULL,\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464850","messageId":"patch-v5-24.34-bacce14d438-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 24/34] doc txt & -h consistency: add missing options","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:18Z","receivedAt":"2022-10-13T15:41:07Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change those built-in commands that were attempting to exhaustively\nlist the options in the \"-h\" output to actually do so, and always\nhave *.txt documentation know about the exhaustive list of options.\n\nLet's also fix the documentation and -h output for those built-in\ncommands where the *.txt and -h output was a mismatch of missing\noptions on both sides.\n\nIn the case of \"interpret-trailers\" fixing the missing options reveals\nthat the *.txt version was implicitly claiming that the command had\ntwo operating modes, which a look at the -h version (and studying the\ndocumentation) will show is not the case.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-commit-graph.txt       | 5 ++++-\n Documentation/git-interpret-trailers.txt | 5 +++--\n builtin/commit-tree.c                    | 1 +\n builtin/fsck.c                           | 5 ++++-\n builtin/hash-object.c                    | 4 ++--\n builtin/init-db.c                        | 2 ++\n builtin/interpret-trailers.c             | 2 +-\n builtin/rm.c                             | 4 +++-\n 8 files changed, 20 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 36fe56c2c71..c8dbceba014 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -10,7 +10,10 @@ SYNOPSIS\n --------\n [verse]\n 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]\n-'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]\n+'git commit-graph write' [--object-dir <dir>] [--append]\n+\t\t\t[--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]\n+\t\t\t[--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]\n+\t\t\t<split options>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 6d6197cd0a4..22ff3a603e0 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [<options>] [--parse] [<file>...]\n+'git interpret-trailers' [--in-place] [--trim-empty]\n+\t\t\t[(--trailer <token>[(=|:)<value>])...]\n+\t\t\t[--parse] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex e4b85d29d56..cc8d584be2f 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -15,6 +15,7 @@\n #include \"parse-options.h\"\n \n static const char * const commit_tree_usage[] = {\n+\tN_(\"git commit-tree <tree> [(-p <parent>)...]\"),\n \tN_(\"git commit-tree [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]\\n\"\n \t   \"                [(-F <file>)...] <tree>\"),\n \tNULL\ndiff --git a/builtin/fsck.c b/builtin/fsck.c\nindex 41acbc229e4..7436e1a68ef 100644\n--- a/builtin/fsck.c\n+++ b/builtin/fsck.c\n@@ -820,7 +820,10 @@ static int mark_packed_for_connectivity(const struct object_id *oid,\n }\n \n static char const * const fsck_usage[] = {\n-\tN_(\"git fsck [<options>] [<object>...]\"),\n+\tN_(\"git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\\n\"\n+\t   \"         [--[no-]full] [--strict] [--verbose] [--lost-found]\\n\"\n+\t   \"         [--[no-]dangling] [--[no-]progress] [--connectivity-only]\\n\"\n+\t   \"         [--[no-]name-objects] [<object>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/hash-object.c b/builtin/hash-object.c\nindex f7c16802f0c..b5063815020 100644\n--- a/builtin/hash-object.c\n+++ b/builtin/hash-object.c\n@@ -81,8 +81,8 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)\n {\n \tstatic const char * const hash_object_usage[] = {\n \t\tN_(\"git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]\\n\"\n-\t\t   \"                [--stdin] [--] <file>...\"),\n-\t\t\"git hash-object  --stdin-paths\",\n+\t\t   \"                [--stdin [--literally]] [--] <file>...\"),\n+\t\tN_(\"git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]\"),\n \t\tNULL\n \t};\n \tconst char *type = blob_type;\ndiff --git a/builtin/init-db.c b/builtin/init-db.c\nindex 08ba006d55e..dcaaf102eaf 100644\n--- a/builtin/init-db.c\n+++ b/builtin/init-db.c\n@@ -516,6 +516,8 @@ static int shared_callback(const struct option *opt, const char *arg, int unset)\n \n static const char *const init_db_usage[] = {\n \tN_(\"git init [-q | --quiet] [--bare] [--template=<template-directory>]\\n\"\n+\t   \"         [--separate-git-dir <git-dir>] [--object-format=<format>]\\n\"\n+\t   \"         [-b <branch-name> | --initial-branch=<branch-name>]\\n\"\n \t   \"         [--shared[=<permissions>]] [<directory>]\"),\n \tNULL\n };\ndiff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c\nindex 4cf0cf265dc..e58627c72a9 100644\n--- a/builtin/interpret-trailers.c\n+++ b/builtin/interpret-trailers.c\n@@ -15,7 +15,7 @@\n static const char * const git_interpret_trailers_usage[] = {\n \tN_(\"git interpret-trailers [--in-place] [--trim-empty]\\n\"\n \t   \"                       [(--trailer <token>[(=|:)<value>])...]\\n\"\n-\t   \"                       [<file>...]\"),\n+\t   \"                       [--parse] [<file>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/rm.c b/builtin/rm.c\nindex b6ba859fe42..f0d025a4e23 100644\n--- a/builtin/rm.c\n+++ b/builtin/rm.c\n@@ -17,7 +17,9 @@\n #include \"pathspec.h\"\n \n static const char * const builtin_rm_usage[] = {\n-\tN_(\"git rm [<options>] [--] <file>...\"),\n+\tN_(\"git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\\n\"\n+\t   \"       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"       [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464851","messageId":"patch-v5-21.34-2c4c48792b3-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 21/34] doc txt & -h consistency: make \"read-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:15Z","receivedAt":"2022-10-13T15:41:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The C version was right to use \"()\" in place of \"[]\" around the option\nlisting, let's update the *.txt version accordingly, and furthermore\nlist the *.c options in the same order as the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-read-tree.txt | 2 +-\n builtin/read-tree.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex b9bfdc0a319..7567955bad8 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index\n SYNOPSIS\n --------\n [verse]\n-'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]\n+'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\n \t\t[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\n \t\t(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\n \ndiff --git a/builtin/read-tree.c b/builtin/read-tree.c\nindex b3a389e1b1f..f4cbe460b97 100644\n--- a/builtin/read-tree.c\n+++ b/builtin/read-tree.c\n@@ -39,7 +39,7 @@ static int list_tree(struct object_id *oid)\n \n static const char * const read_tree_usage[] = {\n \tN_(\"git read-tree [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>)\\n\"\n-\t   \"              [-u | -i]] [--no-sparse-checkout] [--index-output=<file>]\\n\"\n+\t   \"              [-u | -i]] [--index-output=<file>] [--no-sparse-checkout]\\n\"\n \t   \"              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])\"),\n \tNULL\n };\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464852","messageId":"patch-v5-18.34-517ff5a4565-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 18/34] doc txt & -h consistency: make output order consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:12Z","receivedAt":"2022-10-13T15:41:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Fix cases where the SYNOPSIS and -h output was presented in a\ndifferent order.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/merge-base.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex a11f8c6e4bb..6f3941f2a49 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -31,8 +31,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n static const char * const merge_base_usage[] = {\n \tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n \tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n+\tN_(\"git merge-base --independent <commit>...\"),\n \tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n \tNULL\n };\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464853","messageId":"patch-v5-22.34-c616f2e9129-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 22/34] doc txt & -h consistency: make \"bundle\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:16Z","receivedAt":"2022-10-13T15:41:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend the -h output to match that of the *.txt output, the differences\nwere fairly small. In the case of \"[<options>]\" we only have a few of\nthem, so let's exhaustively list them as in the *.txt.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/bundle.c | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 1b08700bf9e..544c78a5f3a 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,13 +12,14 @@\n  */\n \n #define BUILTIN_BUNDLE_CREATE_USAGE \\\n-\tN_(\"git bundle create [<options>] <file> <git-rev-list args>\")\n+\tN_(\"git bundle create [-q | --quiet | --progress | --all-progress] [--all-progress-implied]\\n\" \\\n+\t   \"                  [--version=<version>] <file> <git-rev-list-args>\")\n #define BUILTIN_BUNDLE_VERIFY_USAGE \\\n-\tN_(\"git bundle verify [<options>] <file>\")\n+\tN_(\"git bundle verify [-q | --quiet] <file>\")\n #define BUILTIN_BUNDLE_LIST_HEADS_USAGE \\\n \tN_(\"git bundle list-heads <file> [<refname>...]\")\n #define BUILTIN_BUNDLE_UNBUNDLE_USAGE \\\n-\tN_(\"git bundle unbundle <file> [<refname>...]\")\n+\tN_(\"git bundle unbundle [--progress] <file> [<refname>...]\")\n \n static char const * const builtin_bundle_usage[] = {\n \tBUILTIN_BUNDLE_CREATE_USAGE,\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464854","messageId":"patch-v5-23.34-1a49bbd1f6a-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 23/34] doc txt & -h consistency: use \"git foo\" form, not \"git-foo\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:17Z","receivedAt":"2022-10-13T15:41:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Use the \"git cmd\" form instead of \"git-cmd\" for both \"git\nreceive-pack\" and \"git credential-cache--daemon\".\n\nFor \"git-receive-pack\" we do have a binary with that name, even when\ninstalled with SKIP_DASHED_BUILT_INS=YesPlease, but for the purposes\nof the SYNOPSIS let's use the \"git cmd\" form like everywhere else. It\ncan be invoked like that (and our tests do so), the parts of our\ndocumentation that explain when you need to use the dashed form do so,\nand use it.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-receive-pack.txt | 2 +-\n builtin/credential-cache--daemon.c | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex 5c297db1a4b..65ff518ccff 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <git-dir>\n+'git receive-pack' <git-dir>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c\nindex d4eb0097d24..f3c89831d4a 100644\n--- a/builtin/credential-cache--daemon.c\n+++ b/builtin/credential-cache--daemon.c\n@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n \tconst char *socket_path;\n \tint ignore_sighup = 0;\n \tstatic const char *usage[] = {\n-\t\t\"git-credential-cache--daemon [--debug] <socket-path>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\tNULL\n \t};\n \tint debug = 0;\n@@ -305,7 +305,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)\n {\n \tconst char * const usage[] = {\n-\t\t\"git credential-cache--daemon [options] <action>\",\n+\t\t\"git credential-cache--daemon [--debug] <socket-path>\",\n \t\t\"\",\n \t\t\"credential-cache--daemon is disabled in this build of Git\",\n \t\tNULL\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464855","messageId":"patch-v5-26.34-a7762e82f71-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 26/34] doc txt & -h consistency: make \"annotate\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:20Z","receivedAt":"2022-10-13T15:41:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cmd_blame() already detected whether it was processing \"blame\" or\n\"annotate\", but it didn't adjust its usage output accordingly. Let's\ndo that.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-annotate.txt |  2 +-\n builtin/blame.c                | 22 ++++++++++++++++------\n 2 files changed, 17 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex e44a831339d..5ae8aabe0f8 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [<options>] <file> [<revision>]\n+'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file>\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/blame.c b/builtin/blame.c\nindex a9fe8cf7a68..71f925e456c 100644\n--- a/builtin/blame.c\n+++ b/builtin/blame.c\n@@ -30,6 +30,7 @@\n #include \"tag.h\"\n \n static char blame_usage[] = N_(\"git blame [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n+static char annotate_usage[] = N_(\"git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>\");\n \n static const char *blame_opt_usage[] = {\n \tblame_usage,\n@@ -38,6 +39,13 @@ static const char *blame_opt_usage[] = {\n \tNULL\n };\n \n+static const char *annotate_opt_usage[] = {\n+\tannotate_usage,\n+\t\"\",\n+\tN_(\"<rev-opts> are documented in git-rev-list(1)\"),\n+\tNULL\n+};\n+\n static int longest_file;\n static int longest_author;\n static int max_orig_digits;\n@@ -899,6 +907,8 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tlong anchor;\n \tconst int hexsz = the_hash_algo->hexsz;\n \tlong num_lines = 0;\n+\tconst char *str_usage = cmd_is_annotate ? annotate_usage : blame_usage;\n+\tconst char **opt_usage = cmd_is_annotate ? annotate_opt_usage : blame_opt_usage;\n \n \tsetup_default_color_by_age();\n \tgit_config(git_blame_config, &output_option);\n@@ -914,7 +924,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \tparse_options_start(&ctx, argc, argv, prefix, options,\n \t\t\t    PARSE_OPT_KEEP_DASHDASH | PARSE_OPT_KEEP_ARGV0);\n \tfor (;;) {\n-\t\tswitch (parse_options_step(&ctx, options, blame_opt_usage)) {\n+\t\tswitch (parse_options_step(&ctx, options, opt_usage)) {\n \t\tcase PARSE_OPT_NON_OPTION:\n \t\tcase PARSE_OPT_UNKNOWN:\n \t\t\tbreak;\n@@ -934,7 +944,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\tctx.argv[0] = \"--children\";\n \t\t\treverse = 1;\n \t\t}\n-\t\tparse_revision_opt(&revs, &ctx, options, blame_opt_usage);\n+\t\tparse_revision_opt(&revs, &ctx, options, opt_usage);\n \t}\n parse_done:\n \trevision_opts_finish(&revs);\n@@ -1040,7 +1050,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\tswitch (argc - dashdash_pos - 1) {\n \t\tcase 2: /* (1b) */\n \t\t\tif (argc != 4)\n-\t\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\t\tusage_with_options(opt_usage, options);\n \t\t\t/* reorder for the new way: <rev> -- <path> */\n \t\t\targv[1] = argv[3];\n \t\t\targv[3] = argv[2];\n@@ -1051,11 +1061,11 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\targv[argc] = NULL;\n \t\t\tbreak;\n \t\tdefault:\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(opt_usage, options);\n \t\t}\n \t} else {\n \t\tif (argc < 2)\n-\t\t\tusage_with_options(blame_opt_usage, options);\n+\t\t\tusage_with_options(opt_usage, options);\n \t\tif (argc == 3 && is_a_rev(argv[argc - 1])) { /* (2b) */\n \t\t\tpath = add_prefix(prefix, argv[1]);\n \t\t\targv[1] = argv[2];\n@@ -1113,7 +1123,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)\n \t\t\t\t    nth_line_cb, &sb, lno, anchor,\n \t\t\t\t    &bottom, &top, sb.path,\n \t\t\t\t    the_repository->index))\n-\t\t\tusage(blame_usage);\n+\t\t\tusage(str_usage);\n \t\tif ((!lno && (top || bottom)) || lno < bottom)\n \t\t\tdie(Q_(\"file %s has only %lu line\",\n \t\t\t       \"file %s has only %lu lines\",\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464856","messageId":"patch-v5-32.34-48c1bb97a91-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 32/34] doc txt & -h consistency: make \"worktree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:26Z","receivedAt":"2022-10-13T15:41:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"worktree\" -h output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex ba6846c3788..4a24d53be15 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -16,17 +16,18 @@\n #include \"quote.h\"\n \n #define BUILTIN_WORKTREE_ADD_USAGE \\\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+\tN_(\"git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\\n\" \\\n+\t   \"                 [-b <new-branch>] <path> [<commit-ish>]\")\n #define BUILTIN_WORKTREE_LIST_USAGE \\\n-\tN_(\"git worktree list [<options>]\")\n+\tN_(\"git worktree list [-v | --porcelain [-z]]\")\n #define BUILTIN_WORKTREE_LOCK_USAGE \\\n-\tN_(\"git worktree lock [<options>] <path>\")\n+\tN_(\"git worktree lock [--reason <string>] <worktree>\")\n #define BUILTIN_WORKTREE_MOVE_USAGE \\\n \tN_(\"git worktree move <worktree> <new-path>\")\n #define BUILTIN_WORKTREE_PRUNE_USAGE \\\n-\tN_(\"git worktree prune [<options>]\")\n+\tN_(\"git worktree prune [-n] [-v] [--expire <expire>]\")\n #define BUILTIN_WORKTREE_REMOVE_USAGE \\\n-\tN_(\"git worktree remove [<options>] <worktree>\")\n+\tN_(\"git worktree remove [-f] <worktree>\")\n #define BUILTIN_WORKTREE_REPAIR_USAGE \\\n \tN_(\"git worktree repair [<path>...]\")\n #define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464857","messageId":"patch-v5-27.34-6c68125f191-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 27/34] doc txt & -h consistency: use \"[<label>...]\" for \"zero or more\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:21Z","receivedAt":"2022-10-13T15:41:40Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Correct uses of \"<label>...\" where we really meant to say\n\"[<label>...]\", i.e. the command in question taken an optional set of\n\"<label>\". As the CodingGuidelines notes \"[o]ptional parts [should be]\nenclosed in square brackets\".\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-clean.txt | 2 +-\n builtin/clean.c             | 2 +-\n builtin/commit.c            | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 8347c6eed79..160d08b86bb 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree\n SYNOPSIS\n --------\n [verse]\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>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/clean.c b/builtin/clean.c\nindex 6f039f555b2..40ff2c578de 100644\n--- a/builtin/clean.c\n+++ b/builtin/clean.c\n@@ -26,7 +26,7 @@ static struct string_list del_list = STRING_LIST_INIT_DUP;\n static unsigned int colopts;\n \n static const char *const builtin_clean_usage[] = {\n-\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <pathspec>...\"),\n+\tN_(\"git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...]\"),\n \tNULL\n };\n \ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex fcf9c85947e..21ad4ccbf87 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -45,7 +45,7 @@ static const char * const builtin_commit_usage[] = {\n };\n \n static const char * const builtin_status_usage[] = {\n-\tN_(\"git status [<options>] [--] <pathspec>...\"),\n+\tN_(\"git status [<options>] [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464858","messageId":"patch-v5-31.34-fd2d358fc05-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 31/34] worktree: define subcommand -h in terms of command -h","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:25Z","receivedAt":"2022-10-13T15:41:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Avoid repeating the \"-h\" output for the \"git worktree\" command, and\ninstead define the usage of each subcommand with macros, so that the\n\"-h\" output for the command itself can re-use those definitions. See\n[1], [2] and [3] for prior art using the same pattern.\n\n1. b25b727494f (builtin/multi-pack-index.c: define common usage with a\n   macro, 2021-03-30)\n2. 8757b35d443 (commit-graph: define common usage with a macro,\n   2021-08-23)\n3. 1e91d3faf6c (reflog: move \"usage\" variables and use macros,\n   2022-03-17)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/worktree.c | 109 ++++++++++++++++++++++++++++++++++-----------\n 1 file changed, 84 insertions(+), 25 deletions(-)\n\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 5bfc18e5a24..ba6846c3788 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -15,15 +15,72 @@\n #include \"worktree.h\"\n #include \"quote.h\"\n \n-static const char * const worktree_usage[] = {\n-\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\"),\n-\tN_(\"git worktree list [<options>]\"),\n-\tN_(\"git worktree lock [<options>] <path>\"),\n-\tN_(\"git worktree move <worktree> <new-path>\"),\n-\tN_(\"git worktree prune [<options>]\"),\n-\tN_(\"git worktree remove [<options>] <worktree>\"),\n-\tN_(\"git worktree repair [<path>...]\"),\n-\tN_(\"git worktree unlock <worktree>\"),\n+#define BUILTIN_WORKTREE_ADD_USAGE \\\n+\tN_(\"git worktree add [<options>] <path> [<commit-ish>]\")\n+#define BUILTIN_WORKTREE_LIST_USAGE \\\n+\tN_(\"git worktree list [<options>]\")\n+#define BUILTIN_WORKTREE_LOCK_USAGE \\\n+\tN_(\"git worktree lock [<options>] <path>\")\n+#define BUILTIN_WORKTREE_MOVE_USAGE \\\n+\tN_(\"git worktree move <worktree> <new-path>\")\n+#define BUILTIN_WORKTREE_PRUNE_USAGE \\\n+\tN_(\"git worktree prune [<options>]\")\n+#define BUILTIN_WORKTREE_REMOVE_USAGE \\\n+\tN_(\"git worktree remove [<options>] <worktree>\")\n+#define BUILTIN_WORKTREE_REPAIR_USAGE \\\n+\tN_(\"git worktree repair [<path>...]\")\n+#define BUILTIN_WORKTREE_UNLOCK_USAGE \\\n+\tN_(\"git worktree unlock <worktree>\")\n+\n+static const char * const git_worktree_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_add_usage[] = {\n+\tBUILTIN_WORKTREE_ADD_USAGE,\n+\tNULL,\n+};\n+\n+static const char * const git_worktree_list_usage[] = {\n+\tBUILTIN_WORKTREE_LIST_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_lock_usage[] = {\n+\tBUILTIN_WORKTREE_LOCK_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_move_usage[] = {\n+\tBUILTIN_WORKTREE_MOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_prune_usage[] = {\n+\tBUILTIN_WORKTREE_PRUNE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_remove_usage[] = {\n+\tBUILTIN_WORKTREE_REMOVE_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_repair_usage[] = {\n+\tBUILTIN_WORKTREE_REPAIR_USAGE,\n+\tNULL\n+};\n+\n+static const char * const git_worktree_unlock_usage[] = {\n+\tBUILTIN_WORKTREE_UNLOCK_USAGE,\n \tNULL\n };\n \n@@ -153,9 +210,10 @@ static int prune(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_prune_usage,\n+\t\t\t   0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_prune_usage, options);\n \tprune_worktrees();\n \treturn 0;\n }\n@@ -573,7 +631,7 @@ static int add(int ac, const char **av, const char *prefix)\n \n \tmemset(&opts, 0, sizeof(opts));\n \topts.checkout = 1;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);\n \tif (!!opts.detach + !!new_branch + !!new_branch_force > 1)\n \t\tdie(_(\"options '%s', '%s', and '%s' cannot be used together\"), \"-b\", \"-B\", \"--detach\");\n \tif (lock_reason && !keep_locked)\n@@ -584,7 +642,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\topts.keep_locked = _(\"added with --lock\");\n \n \tif (ac < 1 || ac > 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_add_usage, options);\n \n \tpath = prefix_filename(prefix, av[0]);\n \tbranch = ac < 2 ? \"HEAD\" : av[1];\n@@ -772,9 +830,9 @@ static int list(int ac, const char **av, const char *prefix)\n \t};\n \n \texpire = TIME_MAX;\n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_list_usage, 0);\n \tif (ac)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_list_usage, options);\n \telse if (verbose && porcelain)\n \t\tdie(_(\"options '%s' and '%s' cannot be used together\"), \"--verbose\", \"--porcelain\");\n \telse if (!line_terminator && !porcelain)\n@@ -811,9 +869,9 @@ static int lock_worktree(int ac, const char **av, const char *prefix)\n \t};\n \tstruct worktree **worktrees, *wt;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_lock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_lock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -844,9 +902,9 @@ static int unlock_worktree(int ac, const char **av, const char *prefix)\n \tstruct worktree **worktrees, *wt;\n \tint ret;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_unlock_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_unlock_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -914,9 +972,10 @@ static int move_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tchar *path;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_move_usage,\n+\t\t\t   0);\n \tif (ac != 2)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_move_usage, options);\n \n \tpath = prefix_filename(prefix, av[1]);\n \tstrbuf_addstr(&dst, path);\n@@ -1042,9 +1101,9 @@ static int remove_worktree(int ac, const char **av, const char *prefix)\n \tconst char *reason = NULL;\n \tint ret = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_remove_usage, 0);\n \tif (ac != 1)\n-\t\tusage_with_options(worktree_usage, options);\n+\t\tusage_with_options(git_worktree_remove_usage, options);\n \n \tworktrees = get_worktrees();\n \twt = find_worktree(worktrees, prefix, av[0]);\n@@ -1102,7 +1161,7 @@ static int repair(int ac, const char **av, const char *prefix)\n \t};\n \tint rc = 0;\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_repair_usage, 0);\n \tp = ac > 0 ? av : self;\n \tfor (; *p; p++)\n \t\trepair_worktree_at_path(*p, report_repair, &rc);\n@@ -1130,6 +1189,6 @@ int cmd_worktree(int ac, const char **av, const char *prefix)\n \tif (!prefix)\n \t\tprefix = \"\";\n \n-\tac = parse_options(ac, av, prefix, options, worktree_usage, 0);\n+\tac = parse_options(ac, av, prefix, options, git_worktree_usage, 0);\n \treturn fn(ac, av, prefix);\n }\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464859","messageId":"patch-v5-33.34-099998e8cba-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 33/34] tests: start asserting that *.txt SYNOPSIS matches -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:27Z","receivedAt":"2022-10-13T15:41:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's been a lot of incremental effort to make the SYNOPSIS output\nin our documentation consistent with the -h output,\ne.g. cbe485298bf (git reflog [expire|delete]: make -h output\nconsistent with SYNOPSIS, 2022-03-17) is one recent example, but that\neffort has been an uphill battle due to the lack of regression\ntesting.\n\nThis adds such regression testing, we can parse out the SYNOPSIS\noutput with \"sed\", and it turns out it's relatively easy to normalize\nit and the \"-h\" output to match on another.\n\nWe now ensure that we won't have regressions when it comes to the list\nof commands in \"expect_help_to_match_txt\" below, and in subsequent\ncommits we'll make more of them consistent.\n\nThe naïve parser here gets quite a few things wrong, but it doesn't\nneed to be perfect, just good enough that we can compare /some/ of\nthis help output. There's no cases where the output would match except\nfor the parser's stupidity, it's all cases of e.g. comparing the *.txt\nto non-parse_options() output.\n\nSince that output is wildly different than the *.txt anyway let's\nleave this for now, we can fix the parser some other time, or it won't\nbecome necessary as we'll e.g. convert more things to using\nparse_options().\n\nHaving a special-case for \"merge-tree\"'s 1f0c3a29da3 (merge-tree:\nimplement real merges, 2022-06-18) is a bit ugly, but preferred to\nblessing that \" (deprecated)\" pattern for other commands. We'd\nprobably want to add some other way of marking deprecated commands in\nthe SYNOPSIS syntax. Syntactically 1f0c3a29da3's way of doing it is\nindistinguishable from the command taking an optional literal\n\"deprecated\" string as an argument.\n\nSome of the issues that are left:\n\n * \"git show -h\", \"git whatchanged -h\" and \"git reflog --oneline -h\"\n   all showing \"git log\" and \"git show\" usage output. I.e. the\n   \"builtin_log_usage\" in builtin/log.c doesn't take into account what\n   command we're running.\n\n * Commands which implement subcommands such as like\n   \"multi-pack-index\", \"notes\", \"remote\" etc. having their subcommands\n   in a very different order in the *.txt and *.c. Fixing it would\n   require some verbose diffs, so it's been left alone for now.\n\n * Commands such as \"format-patch\" have a very long argument list in\n   the *.txt, but just \"[<options>]\" in the *.c.\n\n   What to do about these has been left out of this series, except to\n   the extent that preceding commits changed \"[<options>]\" (or\n   equivalent) to the list of options in cases where that list of\n   options was tiny, or we clearly meant to exhaustively list the\n   options in both *.txt and *.c.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh  | 69 ++++++++++++++++++++++++++++++++++++-\n t/t0450/txt-help-mismatches | 58 +++++++++++++++++++++++++++++++\n 2 files changed, 126 insertions(+), 1 deletion(-)\n create mode 100644 t/t0450/txt-help-mismatches\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex efd00cfc51a..8fd20b6dba6 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -1,6 +1,9 @@\n #!/bin/sh\n \n-test_description='assert (unbuilt) Documentation/*.txt and -h output'\n+test_description='assert (unbuilt) Documentation/*.txt and -h output\n+\n+Run this with --debug to see a summary of where we still fail to make\n+the two versions consistent with one another.'\n \n TEST_PASSES_SANITIZE_LEAK=true\n . ./test-lib.sh\n@@ -9,6 +12,14 @@ test_expect_success 'setup: list of builtins' '\n \tgit --list-cmds=builtins >builtins\n '\n \n+test_expect_success 'list of txt and help mismatches is sorted' '\n+\tsort -u \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches >expect &&\n+\tif ! test_cmp expect \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tBUG \"please keep the list of txt and help mismatches sorted\"\n+\tfi\n+'\n+\n help_to_synopsis () {\n \tbuiltin=\"$1\" &&\n \tout_dir=\"out/$builtin\" &&\n@@ -49,6 +60,9 @@ txt_to_synopsis () {\n \t\t\t/^$/d;\n \t\t\t/^\\[verse\\]$/d;\n \n+\t\t\ts/{litdd}/--/g;\n+\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\n \t\t\tp;\n \t\t}' \\\n \t\t<\"$b2t\" >\"$out\" &&\n@@ -61,6 +75,15 @@ check_dashed_labels () {\n \n HT=\"\t\"\n \n+align_after_nl () {\n+\tbuiltin=\"$1\" &&\n+\tlen=$(printf \"git %s \" \"$builtin\" | wc -c) &&\n+\tpad=$(printf \"%${len}s\" \"\") &&\n+\n+\tsed \"s/^[ $HT][ $HT]*/$pad/\"\n+}\n+\n+test_debug '>failing'\n while read builtin\n do\n \t# -h output assertions\n@@ -85,6 +108,50 @@ do\n \ttest_expect_success \"$preq\" \"$builtin *.txt SYNOPSIS has dashed labels\" '\n \t\tcheck_dashed_labels \"$(txt_to_synopsis \"$builtin\")\"\n \t'\n+\n+\t# *.txt output consistency assertions\n+\tresult=\n+\tif grep -q \"^$builtin$\" \"$TEST_DIRECTORY\"/t0450/txt-help-mismatches\n+\tthen\n+\t\tresult=failure\n+\telse\n+\t\tresult=success\n+\tfi &&\n+\ttest_expect_$result \"$preq\" \"$builtin -h output and SYNOPSIS agree\" '\n+\t\tt2s=\"$(txt_to_synopsis \"$builtin\")\" &&\n+\t\tif test \"$builtin\" = \"merge-tree\"\n+\t\tthen\n+\t\t\ttest_when_finished \"rm -f t2s.new\" &&\n+\t\t\tsed -e '\\''s/ (deprecated)$//g'\\'' <\"$t2s\" >t2s.new\n+\t\t\tt2s=t2s.new\n+\t\tfi &&\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\n+\t\t# The *.txt and -h use different spacing for the\n+\t\t# alignment of continued usage output, normalize it.\n+\t\talign_after_nl \"$builtin\" <\"$t2s\" >txt &&\n+\t\talign_after_nl \"$builtin\" <\"$h2s\" >help &&\n+\t\ttest_cmp txt help\n+\t'\n+\n+\tif test_have_prereq \"$preq\" && test -e txt && test -e help\n+\tthen\n+\t\ttest_debug '\n+\t\t\tif test_cmp txt help >cmp 2>/dev/null\n+\t\t\tthen\n+\t\t\t\techo \"=== DONE: $builtin ===\"\n+\t\t\telse\n+\t\t\t\techo \"=== TODO: $builtin ===\" &&\n+\t\t\t\tcat cmp\n+\t\t\tfi >>failing\n+\t\t'\n+\n+\t\t# Not in test_expect_success in case --run is being\n+\t\t# used with --debug\n+\t\trm -f txt help tmp 2>/dev/null\n+\tfi\n done <builtins\n \n+test_debug 'say \"$(cat failing)\"'\n+\n test_done\ndiff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches\nnew file mode 100644\nindex 00000000000..a0777acd667\n--- /dev/null\n+++ b/t/t0450/txt-help-mismatches\n@@ -0,0 +1,58 @@\n+add\n+am\n+apply\n+archive\n+bisect\n+blame\n+branch\n+check-ref-format\n+checkout\n+checkout-index\n+clone\n+column\n+config\n+credential\n+credential-cache\n+credential-store\n+fast-export\n+fast-import\n+fetch-pack\n+fmt-merge-msg\n+for-each-ref\n+format-patch\n+fsck-objects\n+fsmonitor--daemon\n+gc\n+grep\n+index-pack\n+init-db\n+log\n+ls-files\n+ls-tree\n+mailinfo\n+mailsplit\n+maintenance\n+merge\n+merge-file\n+merge-index\n+merge-one-file\n+multi-pack-index\n+name-rev\n+notes\n+pack-objects\n+push\n+range-diff\n+rebase\n+remote\n+remote-ext\n+remote-fd\n+repack\n+reset\n+restore\n+rev-parse\n+show\n+stage\n+switch\n+update-index\n+update-ref\n+whatchanged\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464860","messageId":"patch-v5-29.34-65cd6340726-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 29/34] doc txt & -h consistency: make \"commit\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:23Z","receivedAt":"2022-10-13T15:41:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"-h\" output of \"git commit\" consistent with the *.txt version\nby exhaustively listing the options that it takes.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/commit.c | 9 ++++++++-\n 1 file changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex 21ad4ccbf87..64f420bcbf6 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -40,7 +40,14 @@\n #include \"pretty.h\"\n \n static const char * const builtin_commit_usage[] = {\n-\tN_(\"git commit [<options>] [--] <pathspec>...\"),\n+\tN_(\"git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\\n\"\n+\t   \"           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]\\n\"\n+\t   \"           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\\n\"\n+\t   \"           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\\n\"\n+\t   \"           [--date=<date>] [--cleanup=<mode>] [--[no-]status]\\n\"\n+\t   \"           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n+\t   \"           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]\\n\"\n+\t   \"           [--] [<pathspec>...]\"),\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464861","messageId":"patch-v5-30.34-f8f716e6ff5-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 30/34] reflog doc: list real subcommands up-front","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:24Z","receivedAt":"2022-10-13T15:41:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"git reflog\" documentation to exhaustively list the\nsubcommands it accepts in the SYNOPSIS, as opposed to leaving that for\na \"[verse]\" in the DESCRIPTION section. This documentation style was\nadded in cf39f54efc6 (git reflog show, 2007-02-08), but isn't how\nother commands which take subcommands are documented.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-reflog.txt | 15 ++++++---------\n 1 file changed, 6 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 0537d4645be..ec64cbff4c6 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -8,14 +8,6 @@ git-reflog - Manage reflog information\n \n SYNOPSIS\n --------\n-[verse]\n-'git reflog' <subcommand> <options>\n-\n-DESCRIPTION\n------------\n-The command takes various subcommands, and different options\n-depending on the subcommand:\n-\n [verse]\n 'git reflog' [show] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n@@ -25,6 +17,10 @@ depending on the subcommand:\n \t[--dry-run | -n] [--verbose] <ref>@{<specifier>}...\n 'git reflog exists' <ref>\n \n+DESCRIPTION\n+-----------\n+This command manages the information recorded in the reflogs.\n+\n Reference logs, or \"reflogs\", record when the tips of branches and\n other references were updated in the local repository. Reflogs are\n useful in various Git commands, to specify the old value of a\n@@ -33,7 +29,8 @@ moves ago\", `master@{one.week.ago}` means \"where master used to point\n to one week ago in this local repository\", and so on. See\n linkgit:gitrevisions[7] for more details.\n \n-This command manages the information recorded in the reflogs.\n+The command takes various subcommands, and different options\n+depending on the subcommand:\n \n The \"show\" subcommand (which is also the default, in the absence of\n any subcommands) shows the log of the reference provided in the\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464862","messageId":"patch-v5-25.34-89ad801409d-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 25/34] doc txt & -h consistency: make \"stash\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:19Z","receivedAt":"2022-10-13T15:41:48Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend both the -h output and *.txt to match one another. In this case\nthe *.txt didn't list the \"save\" subcommand, and the \"-h\" was\nsimilarly missing some commands.\n\nLet's also convert the *.c code to use a macro definition, similar to\nthat used in preceding commits. This avoids duplication.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-stash.txt |  5 ++-\n builtin/stash.c             | 73 ++++++++++++++++++++++++-------------\n 2 files changed, 52 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex ea16d2eae7c..f4bb6114d91 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -11,12 +11,15 @@ SYNOPSIS\n 'git stash' list [<log-options>]\n 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\n 'git stash' drop [-q | --quiet] [<stash>]\n-'git stash' (pop | apply) [--index] [-q | --quiet] [<stash>]\n+'git stash' pop [--index] [-q | --quiet] [<stash>]\n+'git stash' apply [--index] [-q | --quiet] [<stash>]\n 'git stash' branch <branchname> [<stash>]\n 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n \t     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\n \t     [--pathspec-from-file=<file> [--pathspec-file-nul]]\n \t     [--] [<pathspec>...]]\n+'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\n+\t     [-u | --include-untracked] [-a | --all] [<message>]\n 'git stash' clear\n 'git stash' create [<message>]\n 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>\ndiff --git a/builtin/stash.c b/builtin/stash.c\nindex 83c9591ea6d..bb5485b4095 100644\n--- a/builtin/stash.c\n+++ b/builtin/stash.c\n@@ -21,72 +21,95 @@\n \n #define INCLUDE_ALL_FILES 2\n \n+#define BUILTIN_STASH_LIST_USAGE \\\n+\tN_(\"git stash list [<log-options>]\")\n+#define BUILTIN_STASH_SHOW_USAGE \\\n+\tN_(\"git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]\")\n+#define BUILTIN_STASH_DROP_USAGE \\\n+\tN_(\"git stash drop [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_POP_USAGE \\\n+\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_APPLY_USAGE \\\n+\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\")\n+#define BUILTIN_STASH_BRANCH_USAGE \\\n+\tN_(\"git stash branch <branchname> [<stash>]\")\n+#define BUILTIN_STASH_STORE_USAGE \\\n+\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\")\n+#define BUILTIN_STASH_PUSH_USAGE \\\n+\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\" \\\n+\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\" \\\n+\t   \"          [--] [<pathspec>...]]\")\n+#define BUILTIN_STASH_SAVE_USAGE \\\n+\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\" \\\n+\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\")\n+#define BUILTIN_STASH_CREATE_USAGE \\\n+\tN_(\"git stash create [<message>]\")\n+#define BUILTIN_STASH_CLEAR_USAGE \\\n+\t\"git stash clear\"\n+\n static const char * const git_stash_usage[] = {\n-\tN_(\"git stash list [<log-options>]\"),\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash (pop | apply) [--index] [-q | --quiet] [<stash>]\"),\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n-\t\"git stash clear\",\n-\tN_(\"git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--pathspec-from-file=<file> [--pathspec-file-nul]]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n-\tN_(\"git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n+\tBUILTIN_STASH_SHOW_USAGE,\n+\tBUILTIN_STASH_DROP_USAGE,\n+\tBUILTIN_STASH_POP_USAGE,\n+\tBUILTIN_STASH_APPLY_USAGE,\n+\tBUILTIN_STASH_BRANCH_USAGE,\n+\tBUILTIN_STASH_PUSH_USAGE,\n+\tBUILTIN_STASH_SAVE_USAGE,\n+\tBUILTIN_STASH_CLEAR_USAGE,\n+\tBUILTIN_STASH_CREATE_USAGE,\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_list_usage[] = {\n-\tN_(\"git stash list [<options>]\"),\n+\tBUILTIN_STASH_LIST_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_show_usage[] = {\n-\tN_(\"git stash show [<options>] [<stash>]\"),\n+\tBUILTIN_STASH_SHOW_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_drop_usage[] = {\n-\tN_(\"git stash drop [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_DROP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_pop_usage[] = {\n-\tN_(\"git stash pop [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_POP_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_apply_usage[] = {\n-\tN_(\"git stash apply [--index] [-q | --quiet] [<stash>]\"),\n+\tBUILTIN_STASH_APPLY_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_branch_usage[] = {\n-\tN_(\"git stash branch <branchname> [<stash>]\"),\n+\tBUILTIN_STASH_BRANCH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_clear_usage[] = {\n-\t\"git stash clear\",\n+\tBUILTIN_STASH_CLEAR_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_store_usage[] = {\n-\tN_(\"git stash store [(-m | --message) <message>] [-q | --quiet] <commit>\"),\n+\tBUILTIN_STASH_STORE_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_push_usage[] = {\n-\tN_(\"git stash [push [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"          [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]\\n\"\n-\t   \"          [--] [<pathspec>...]]\"),\n+\tBUILTIN_STASH_PUSH_USAGE,\n \tNULL\n };\n \n static const char * const git_stash_save_usage[] = {\n-\tN_(\"git stash save [-p | --patch] [-k | --[no-]keep-index] [-q | --quiet]\\n\"\n-\t   \"               [-u | --include-untracked] [-a | --all] [<message>]\"),\n+\tBUILTIN_STASH_SAVE_USAGE,\n \tNULL\n };\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464863","messageId":"patch-v5-28.34-abaffb0b0df-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 28/34] doc txt & -h consistency: make \"diff-tree\" consistent","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:22Z","receivedAt":"2022-10-13T15:41:50Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Make the \"diff-tree -h\" output consistent with the *.txt version.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n builtin/diff-tree.c | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/diff-tree.c b/builtin/diff-tree.c\nindex 23f58702fa0..85e8c81e594 100644\n--- a/builtin/diff-tree.c\n+++ b/builtin/diff-tree.c\n@@ -83,8 +83,9 @@ static int diff_tree_stdin(char *line)\n }\n \n static const char diff_tree_usage[] =\n-\"git diff-tree [--stdin] [-m] [-c | --cc] [-s] [-v] [--pretty] [-t] [-r] [--root] \"\n-\"[<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n+\"git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\\n\"\n+\"              [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\\n\"\n+\"              [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\\n\"\n \"\\n\"\n \"  -r            diff recursively\\n\"\n \"  -c            show combined diff for merge commits\\n\"\n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464864","messageId":"patch-v5-34.34-4de83d3d89a-20221013T153626Z-avarab@gmail.com","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"[PATCH v5 34/34] tests: assert consistent whitespace in -h output","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-10-13T15:39:28Z","receivedAt":"2022-10-13T15:42:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a test for the *.txt and *.c output assertions which asserts that\nfor \"-h\" lines that aren't the \"usage: \" or \" or: \" lines they start\nwith the same amount of whitespace. This ensures that we won't have\nbuggy output like:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n       [--create-reflog] [...]\n\nWhich should instead be like this, i.e. the options lines should be\naligned:\n\n   [...]\n   or: git tag [-n[<num>]]\n               [...]\n               [--create-reflog] [...]\n\nIt would be better to be able to use \"test_cmp\" here, i.e. to\nconstruct the output we expect, and compare it against the actual\noutput.\n\nFor most built-in commands this would be rather straightforward. In\n\"t0450-txt-doc-vs-help.sh\" we already compute the whitespace that a\n\"git-$builtin\" needs, and strip away \"usage: \" or \" or: \" from the\nstart of lines. The problem is:\n\n * For commands that implement subcommands, such as \"git bundle\", we\n   don't know whether e.g. \"git bundle create\" is the subcommand\n   \"create\", or the argument \"create\" to \"bundle\" for the purposes of\n   alignment.\n\n   We *do* have that information from the *.txt version, since the\n   part within the ''-quotes should be the command & subcommand, but\n   that isn't consistent (e.g. see \"git bundle\" and \"git\n   commit-graph\", only the latter is correct), and parsing that out\n   would be non-trivial.\n\n * If we were to make this stricter we have various\n   non-parse_options() users (e.g. \"git diff-tree\") that don't have the\n   nicely aligned output which we've had since\n   4631cfc20bd (parse-options: properly align continued usage output,\n   2021-09-21).\n\nSo rather than make perfect the enemy of the good let's assert that\nfor those lines that are indented they should all use the same\nindentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 8fd20b6dba6..cd3969e852b 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -96,6 +96,21 @@ do\n \t\tcheck_dashed_labels \"$(help_to_synopsis \"$builtin\")\"\n \t'\n \n+\ttest_expect_success \"$builtin -h output has consistent spacing\" '\n+\t\th2s=\"$(help_to_synopsis \"$builtin\")\" &&\n+\t\tsed -n \\\n+\t\t\t-e \"/^ / {\n+\t\t\t\ts/[^ ].*//;\n+\t\t\t\tp;\n+\t\t\t}\" \\\n+\t\t\t<\"$h2s\" >help &&\n+\t\tsort -u help >help.ws &&\n+\t\tif test -s help.ws\n+\t\tthen\n+\t\t\ttest_line_count = 1 help.ws\n+\t\tfi\n+\t'\n+\n \ttxt=\"$(builtin_to_txt \"$builtin\")\" &&\n \tpreq=\"$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')\" &&\n \n-- \n2.38.0.1085.gb7e61c3016c\n\n"},{"id":"464866","messageId":"xmqqpmevhedz.fsf@gitster.g","threadId":"58397","inReplyTo":"cover-v5-00.34-00000000000-20221013T153625Z-avarab@gmail.com","subject":"Re: [PATCH v5 00/34] doc/UX: make txt & -h output more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-13T16:33:44Z","receivedAt":"2022-10-13T16:33:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> We are currently wildly inconsistent in whether the SYNOPSIS in the\n> manual page matches the first line of the -h output, and as we add new\n> options we routinely forget to add them to one or the other (or both).\n>\n> Without a more complex approach it's hard to do something about the\n> \"or both\" case. But we can rather easily test whether the -h output\n> matches the *.txt version, and report differences.\n\nNice.\n"}]}