{"thread":{"id":"66318","subject":"[PATCH 0/3] doc lint fixes for pack-refs and refs","startedAt":"2026-09-12T19:15:34Z","lastAt":"2026-09-15T16:25:35Z","messageCount":16,"participants":["Todd Zullinger","Jean-Noël AVILA","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"552627","messageId":"20260912191509.844954-1-tmz@pobox.com","threadId":"66318","inReplyTo":null,"subject":"[PATCH 0/3] doc lint fixes for pack-refs and refs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-12T19:14:59Z","receivedAt":"2026-09-12T19:15:34Z","isPatch":true,"body":"I was reading git-refs(1) after noticing it learned some new tricks in the\n2.56.0 release notes. The formatting stood out because the first two commands,\nmigrate and verify are bold (in the man pages) but subsequent commands are not.\nThe HTML is similarly affected, with those commands colored differently than\nthe rest in our online documentation:\n\n https://git-scm.com/docs/git-refs\n\nThis is due to inconsistent backtick-quotes.\n\nThis led me to the lint check, which I think might benefit from the small\nchange here to match commands as well as options. Running something like this\nreports a number of files which could also use some tweaks:\n\n cd Documentation && for i in *.adoc; do\n output=$(perl lint-documentation-style.perl <$i 2>&1)\n [[ -n $output ]] && printf '\\n%s:\\n%s\\n' $i \"$output\"\n done\n\nI _think_ we want to backtick-quote those when using the synopsis style. (If\nnot, then the change is wrong and we should remove the backticks from the two\ncommands in git-refs.adoc and other places.)\n\nAs git-refs.adoc includes pack-refs-options.adoc, I updated it to consistently\nuse backtick quoting and converted the only other file which includes it,\ngit-pack-refs.adoc.\n\nTodd Zullinger (3):\n doc lint: match commands as well as options for synopsis style check\n doc/pack-refs: convert synopsis and options to new style\n doc/refs: backtick-quote commands and options consistently\n\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/git-refs.adoc | 14 +++++++-------\n Documentation/lint-documentation-style.perl | 4 ++--\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 4 files changed, 18 insertions(+), 18 deletions(-)\n\n-- \n2.56.0.rc0\n\n"},{"id":"552628","messageId":"20260912191509.844954-2-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH 1/3] doc lint: match commands as well as options for synopsis style check","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-12T19:15:00Z","receivedAt":"2026-09-12T19:15:35Z","isPatch":true,"body":"Both `--option::` and `command::` should be backtick-quoted with the new\nsynopsis style. Remove the requirement for a leading `-` from the regex\nwhich scans for these patterns.\n\nAvoid matching lines like `linkgit:git-diff[1]::` by replacing `.*` with\n`[^:]*` in the regex.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/lint-documentation-style.perl | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl\nindex d7ab732293..6eece11bdc 100755\n--- a/Documentation/lint-documentation-style.perl\n+++ b/Documentation/lint-documentation-style.perl\n@@ -24,8 +24,8 @@ sub report {\n \tif ($line =~ /^\\[synopsis\\]$/) {\n \t\t$synopsis_style = 1;\n \t}\n-\tif (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\\.{3})?)(::|;;)$/) && ($synopsis_style)) {\n-\t\t\treport($line, \"synopsis style and definition list item not backquoted\");\n+\tif (($line =~ /^([-a-z][^:]*|<[-a-z0-9]+>(\\.{3})?)(::|;;)$/) && ($synopsis_style)) {\n+\t\treport($line, \"synopsis style and definition list item not backquoted\");\n \t}\n }\n \n-- \n2.56.0.rc0\n\n"},{"id":"552629","messageId":"20260912191509.844954-3-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH 2/3] doc/pack-refs: convert synopsis and options to new style","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-12T19:15:01Z","receivedAt":"2026-09-12T19:15:36Z","isPatch":true,"body":"Replace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section and convert\nthe standalone placeholder __ in prose.\n\nUpdate the included pack-refs-options.adoc to backtick-quote all\nconfiguration key terms.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 2 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\nindex fde9f2f294..69e018d07e 100644\n--- a/Documentation/git-pack-refs.adoc\n+++ b/Documentation/git-pack-refs.adoc\n@@ -7,8 +7,8 @@ git-pack-refs - Pack heads and tags for efficient repository access\n \n SYNOPSIS\n --------\n-[verse]\n-'git pack-refs' [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n+[synopsis]\n+git pack-refs [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n \n DESCRIPTION\n -----------\n@@ -52,8 +52,8 @@ BUGS\n ----\n \n Older documentation written before the packed-refs mechanism was\n-introduced may still say things like \".git/refs/heads/ file\n-exists\" when it means \"branch exists\".\n+introduced may still say things like \".git/refs/heads/__ file\n+exists\" when it means \"branch __ exists\".\n \n \n GIT\ndiff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc\nindex 0b11282941..2263648b39 100644\n--- a/Documentation/pack-refs-options.adoc\n+++ b/Documentation/pack-refs-options.adoc\n@@ -1,4 +1,4 @@\n---all::\n+`--all`::\n \n The command by default packs all tags and refs that are already\n packed, and leaves other refs\n@@ -8,12 +8,12 @@ This option causes all refs to be packed as well, with the exception\n of hidden refs, broken refs, and symbolic refs. Useful for a repository\n with many branches of historical interests.\n \n---no-prune::\n+`--no-prune`::\n \n The command usually removes loose refs under `$GIT_DIR/refs`\n hierarchy after packing them. This option tells it not to.\n \n---auto::\n+`--auto`::\n \n Pack refs as needed depending on the current state of the ref database. The\n behavior depends on the ref format used by the repository and may change in the\n@@ -29,7 +29,7 @@ future.\n \t maintains the property that N is at least twice as big as N+1. Only\n \t tables that violate this property are compacted.\n \n---include ::\n+`--include `::\n \n Pack refs based on a `glob(7)` pattern. Repetitions of this option\n accumulate inclusion patterns. If a ref is both included in `--include` and\n@@ -38,7 +38,7 @@ tags from being included by default. Symbolic refs and broken refs will never\n be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear\n and reset the list of patterns.\n \n---exclude ::\n+`--exclude `::\n \n Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option\n accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of\n-- \n2.56.0.rc0\n\n"},{"id":"552630","messageId":"20260912191509.844954-4-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH 3/3] doc/refs: backtick-quote commands and options consistently","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-12T19:15:02Z","receivedAt":"2026-09-12T19:15:36Z","isPatch":true,"body":"The git-refs doc was converted to the synopsis style in 89be7d2774\n(builtin/refs: add '--no-reflog' flag to drop reflogs, 2025-02-21). The\ncommands and options were not backtick-quoted at that time. 84f3d6e11e\n(doc lint: check that synopsis manpages have synopsis inlines,\n2025-08-11) applied backtick-quotes to the existing commands and\noptions.\n\nSubsequently, a number of commands and options were added without such\nquoting, leaving the documentation rendered inconsistently. Apply\nbacktick-quotes to all entries.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-refs.adoc | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 9063892651..9dc08cbca9 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -54,40 +54,40 @@ These limitations may eventually be lifted.\n `verify`::\n \tVerify reference database consistency.\n \n-list::\n+`list`::\n \tList references in the repository with support for filtering,\n \tformatting, and sorting. This subcommand is an alias for\n \tlinkgit:git-for-each-ref[1] and offers identical functionality.\n \n-exists::\n+`exists`::\n \tCheck whether the given reference exists. Returns an exit code of 0 if\n \tit does, 2 if it is missing, and 1 in case looking up the reference\n \tfailed with an error other than the reference being missing. This does\n \tnot verify whether the reference resolves to an actual object.\n \n-optimize::\n+`optimize`::\n \tOptimizes references to improve repository performance and reduce disk\n \tusage. This subcommand is an alias for linkgit:git-pack-refs[1] and\n \toffers identical functionality.\n \n-create::\n+`create`::\n \tCreate the given reference, which must not already exist, pointing at\n \t``.\n \n-delete::\n+`delete`::\n \tDelete the given reference. This subcommand mirrors `git update-ref -d`\n \t(see linkgit:git-update-ref[1]). When `` is given, the\n \treference is only deleted after verifying that it currently contains\n \t``.\n \n-update::\n+`update`::\n \tUpdate the given reference to point at ``. If ``\n \tis given, the reference is only updated after verifying that it\n \tcurrently contains ``. As a special case, an all-zeroes\n \t`` deletes the branch, whereas an all-zeroes ``\n \tensures that the branch does not yet exist.\n \n-rename::\n+`rename`::\n \tRename the reference `` to ``. The old reference must\n \texist and the new reference must not yet exist, and both must have a\n \twell-formed name (see linkgit:git-check-ref-format[1]).\n-- \n2.56.0.rc0\n\n"},{"id":"552635","messageId":"Uds1uZlUTZi1p6vFK4zhWg@free.fr","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"Re: [PATCH 0/3] doc lint fixes for pack-refs and refs","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-09-13T10:26:39Z","receivedAt":"2026-09-13T10:26:44Z","isPatch":true,"body":"On Saturday, 12 September 2026 21:14:59 CEST Todd Zullinger wrote:\n> I was reading git-refs(1) after noticing it learned some new tricks in the\n> 2.56.0 release notes. The formatting stood out because the first two \ncommands,\n> migrate and verify are bold (in the man pages) but subsequent commands are \nnot.\n> The HTML is similarly affected, with those commands colored differently than\n> the rest in our online documentation:\n> \n> https://git-scm.com/docs/git-refs\n> \n> This is due to inconsistent backtick-quotes.\n> \n> This led me to the lint check, which I think might benefit from the small\n> change here to match commands as well as options. Running something like \nthis\n> reports a number of files which could also use some tweaks:\n> \n> cd Documentation && for i in *.adoc; do\n> output=$(perl lint-documentation-style.perl <$i 2>&1)\n> [[ -n $output ]] && printf '\\n%s:\\n%s\\n' $i \"$output\"\n> done\n> \n> I _think_ we want to backtick-quote those when using the synopsis style. \n(If\n> not, then the change is wrong and we should remove the backticks from the \ntwo\n> commands in git-refs.adoc and other places.)\n> \n> As git-refs.adoc includes pack-refs-options.adoc, I updated it to \nconsistently\n> use backtick quoting and converted the only other file which includes it,\n> git-pack-refs.adoc.\n> \n> Todd Zullinger (3):\n> doc lint: match commands as well as options for synopsis style check\n> doc/pack-refs: convert synopsis and options to new style\n> doc/refs: backtick-quote commands and options consistently\n> \n> Documentation/git-pack-refs.adoc | 8 ++++----\n> Documentation/git-refs.adoc | 14 +++++++-------\n> Documentation/lint-documentation-style.perl | 4 ++--\n> Documentation/pack-refs-options.adoc | 10 +++++-----\n> 4 files changed, 18 insertions(+), 18 deletions(-)\n\nWhen I put this linting in place, I was specifically targeting the options. \nThe other cases of use of definition list could range from commands to real \ndefinitions of words (see gitglossary.adoc and git-add.adoc), and extending \nthe match can trigger false positives. Backticked terms are supposed to be \nimmutable for translators, so this formatting should not be used for real \ndefinitions. \nFor this reason, the regex is restricted on purpose, but selecting the files \nto check to allow to extend the range of checks.\n, \nFWIW, the proposed change triggers false positives for git-add.adoc, git-\npush.adoc, git-difftool.adoc, git-daemon.adoc and git-fetch.adoc.\n\n\n\n\n"},{"id":"552641","messageId":"20260913141405.Dcx5xbe-@teonanacatl.net","threadId":"66318","inReplyTo":"Uds1uZlUTZi1p6vFK4zhWg@free.fr","subject":"Re: [PATCH 0/3] doc lint fixes for pack-refs and refs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-13T14:14:05Z","receivedAt":"2026-09-13T14:14:08Z","isPatch":true,"body":"Hi,\n\nJean-Noël AVILA wrote:\n> When I put this linting in place, I was specifically targeting the options. \n> The other cases of use of definition list could range from commands to real \n> definitions of words (see gitglossary.adoc and git-add.adoc), and extending \n> the match can trigger false positives. Backticked terms are supposed to be \n> immutable for translators, so this formatting should not be used for real \n> definitions. \n> For this reason, the regex is restricted on purpose, but selecting the files \n> to check to allow to extend the range of checks.\n> , \n> FWIW, the proposed change triggers false positives for git-add.adoc, git-\n> push.adoc, git-difftool.adoc, git-daemon.adoc and git-fetch.adoc.\n\nThat's fine, I don't mind dropping that patch if the false\npositives will be more annoying than skipping the checks for\ncommands and missing some of them.\n\nI'll wait a little before sending a re-roll with that\ndropped, in case anyone spots issues in the main patches to\nthe pack-refs and refs docs.\n\nThanks,\n\n-- \nTodd\n"},{"id":"552701","messageId":"20260914124630.154107-1-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v2 0/2] doc lint fixes for pack-refs and refs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-14T12:46:26Z","receivedAt":"2026-09-14T12:46:34Z","isPatch":true,"body":"I was reading git-refs(1) after noticing it learned some new tricks\nin the 2.56.0 release notes. The formatting stood out because the\nfirst two commands, migrate and verify are bold (in the man pages)\nbut subsequent commands are not. The HTML is similarly affected,\nwith those commands colored differently than the rest in our online\ndocumentation:\n\n https://git-scm.com/docs/git-refs\n\nThis is due to inconsistent backtick-quotes.\n\nAs git-refs.adoc includes pack-refs-options.adoc, I updated it to\nconsistently use backtick quoting and converted the only other file\nwhich includes it, git-pack-refs.adoc.\n\nChanges since v1:\n\n * Drop Documentation/lint-documentation-style.perl change. It\n is likely to cause more false positives than we want.\n\nTodd Zullinger (2):\n doc/pack-refs: convert synopsis and options to new style\n doc/refs: backtick-quote commands and options consistently\n\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/git-refs.adoc | 14 +++++++-------\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 3 files changed, 16 insertions(+), 16 deletions(-)\n\nRange-diff against v1:\n1: 03c1e8c073 < -: ---------- doc lint: match commands as well as options for synopsis style check\n2: eb3b95c7a7 = 1: 3de9d9a6bf doc/pack-refs: convert synopsis and options to new style\n3: 7af3718a71 = 2: b3789f7591 doc/refs: backtick-quote commands and options consistently\n\n-- \n2.56.0.rc0\n\n"},{"id":"552702","messageId":"20260914124630.154107-2-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v2 1/2] doc/pack-refs: convert synopsis and options to new style","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-14T12:46:27Z","receivedAt":"2026-09-14T12:46:35Z","isPatch":true,"body":"Replace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section and convert\nthe standalone placeholder __ in prose.\n\nUpdate the included pack-refs-options.adoc to backtick-quote all\nconfiguration key terms.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 2 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\nindex fde9f2f294..69e018d07e 100644\n--- a/Documentation/git-pack-refs.adoc\n+++ b/Documentation/git-pack-refs.adoc\n@@ -7,8 +7,8 @@ git-pack-refs - Pack heads and tags for efficient repository access\n \n SYNOPSIS\n --------\n-[verse]\n-'git pack-refs' [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n+[synopsis]\n+git pack-refs [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n \n DESCRIPTION\n -----------\n@@ -52,8 +52,8 @@ BUGS\n ----\n \n Older documentation written before the packed-refs mechanism was\n-introduced may still say things like \".git/refs/heads/ file\n-exists\" when it means \"branch exists\".\n+introduced may still say things like \".git/refs/heads/__ file\n+exists\" when it means \"branch __ exists\".\n \n \n GIT\ndiff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc\nindex 0b11282941..2263648b39 100644\n--- a/Documentation/pack-refs-options.adoc\n+++ b/Documentation/pack-refs-options.adoc\n@@ -1,4 +1,4 @@\n---all::\n+`--all`::\n \n The command by default packs all tags and refs that are already\n packed, and leaves other refs\n@@ -8,12 +8,12 @@ This option causes all refs to be packed as well, with the exception\n of hidden refs, broken refs, and symbolic refs. Useful for a repository\n with many branches of historical interests.\n \n---no-prune::\n+`--no-prune`::\n \n The command usually removes loose refs under `$GIT_DIR/refs`\n hierarchy after packing them. This option tells it not to.\n \n---auto::\n+`--auto`::\n \n Pack refs as needed depending on the current state of the ref database. The\n behavior depends on the ref format used by the repository and may change in the\n@@ -29,7 +29,7 @@ future.\n \t maintains the property that N is at least twice as big as N+1. Only\n \t tables that violate this property are compacted.\n \n---include ::\n+`--include `::\n \n Pack refs based on a `glob(7)` pattern. Repetitions of this option\n accumulate inclusion patterns. If a ref is both included in `--include` and\n@@ -38,7 +38,7 @@ tags from being included by default. Symbolic refs and broken refs will never\n be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear\n and reset the list of patterns.\n \n---exclude ::\n+`--exclude `::\n \n Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option\n accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of\n-- \n2.56.0.rc0\n\n"},{"id":"552703","messageId":"20260914124630.154107-3-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v2 2/2] doc/refs: backtick-quote commands and options consistently","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-14T12:46:28Z","receivedAt":"2026-09-14T12:46:36Z","isPatch":true,"body":"The git-refs doc was converted to the synopsis style in 89be7d2774\n(builtin/refs: add '--no-reflog' flag to drop reflogs, 2025-02-21). The\ncommands and options were not backtick-quoted at that time. 84f3d6e11e\n(doc lint: check that synopsis manpages have synopsis inlines,\n2025-08-11) applied backtick-quotes to the existing commands and\noptions.\n\nSubsequently, a number of commands and options were added without such\nquoting, leaving the documentation rendered inconsistently. Apply\nbacktick-quotes to all entries.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-refs.adoc | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 9063892651..9dc08cbca9 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -54,40 +54,40 @@ These limitations may eventually be lifted.\n `verify`::\n \tVerify reference database consistency.\n \n-list::\n+`list`::\n \tList references in the repository with support for filtering,\n \tformatting, and sorting. This subcommand is an alias for\n \tlinkgit:git-for-each-ref[1] and offers identical functionality.\n \n-exists::\n+`exists`::\n \tCheck whether the given reference exists. Returns an exit code of 0 if\n \tit does, 2 if it is missing, and 1 in case looking up the reference\n \tfailed with an error other than the reference being missing. This does\n \tnot verify whether the reference resolves to an actual object.\n \n-optimize::\n+`optimize`::\n \tOptimizes references to improve repository performance and reduce disk\n \tusage. This subcommand is an alias for linkgit:git-pack-refs[1] and\n \toffers identical functionality.\n \n-create::\n+`create`::\n \tCreate the given reference, which must not already exist, pointing at\n \t``.\n \n-delete::\n+`delete`::\n \tDelete the given reference. This subcommand mirrors `git update-ref -d`\n \t(see linkgit:git-update-ref[1]). When `` is given, the\n \treference is only deleted after verifying that it currently contains\n \t``.\n \n-update::\n+`update`::\n \tUpdate the given reference to point at ``. If ``\n \tis given, the reference is only updated after verifying that it\n \tcurrently contains ``. As a special case, an all-zeroes\n \t`` deletes the branch, whereas an all-zeroes ``\n \tensures that the branch does not yet exist.\n \n-rename::\n+`rename`::\n \tRename the reference `` to ``. The old reference must\n \texist and the new reference must not yet exist, and both must have a\n \twell-formed name (see linkgit:git-check-ref-format[1]).\n-- \n2.56.0.rc0\n\n"},{"id":"552713","messageId":"xmqqcxuf7svp.fsf@gitster.g","threadId":"66318","inReplyTo":"20260914124630.154107-2-tmz@pobox.com","subject":"Re: [PATCH v2 1/2] doc/pack-refs: convert synopsis and options to new style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-14T15:30:18Z","receivedAt":"2026-09-14T15:30:21Z","isPatch":true,"body":"Todd Zullinger writes:\n\n> Replace [verse] with [synopsis] in the SYNOPSIS block and remove\n> single-quote formatting from the command name.\n>\n> Backtick-quote all option terms in the OPTIONS section and convert\n> the standalone placeholder __ in prose.\n>\n> Update the included pack-refs-options.adoc to backtick-quote all\n> configuration key terms.\n\nMicronit. I think you backtick-quoted `--all`, `--no-prune`, and\nfriends, that are not configuration keyu terms but command line\noptions.\n\n> diff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc\n> index 0b11282941..2263648b39 100644\n> --- a/Documentation/pack-refs-options.adoc\n> +++ b/Documentation/pack-refs-options.adoc\n> @@ -1,4 +1,4 @@\n> ---all::\n> +`--all`::\n> \n> The command by default packs all tags and refs that are already\n> packed, and leaves other refs\n> @@ -8,12 +8,12 @@ This option causes all refs to be packed as well, with the exception\n> of hidden refs, broken refs, and symbolic refs. Useful for a repository\n> with many branches of historical interests.\n> \n> ---no-prune::\n> +`--no-prune`::\n> \n> The command usually removes loose refs under `$GIT_DIR/refs`\n> hierarchy after packing them. This option tells it not to.\n> \n> ---auto::\n> +`--auto`::\n> \n> Pack refs as needed depending on the current state of the ref database. The\n> behavior depends on the ref format used by the repository and may change in the\n> @@ -29,7 +29,7 @@ future.\n> \t maintains the property that N is at least twice as big as N+1. Only\n> \t tables that violate this property are compacted.\n> \n> ---include ::\n> +`--include `::\n> \n> Pack refs based on a `glob(7)` pattern. Repetitions of this option\n> accumulate inclusion patterns. If a ref is both included in `--include` and\n> @@ -38,7 +38,7 @@ tags from being included by default. Symbolic refs and broken refs will never\n> be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear\n> and reset the list of patterns.\n> \n> ---exclude ::\n> +`--exclude `::\n> \n> Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option\n> accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of\n"},{"id":"552715","messageId":"20260914154350.LjUwy8DF@teonanacatl.net","threadId":"66318","inReplyTo":"xmqqcxuf7svp.fsf@gitster.g","subject":"Re: [PATCH v2 1/2] doc/pack-refs: convert synopsis and options to new style","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-14T15:43:50Z","receivedAt":"2026-09-14T15:43:54Z","isPatch":true,"body":"Junio C Hamano wrote:\n> Todd Zullinger writes:\n> \n>> Replace [verse] with [synopsis] in the SYNOPSIS block and remove\n>> single-quote formatting from the command name.\n>>\n>> Backtick-quote all option terms in the OPTIONS section and convert\n>> the standalone placeholder __ in prose.\n>>\n>> Update the included pack-refs-options.adoc to backtick-quote all\n>> configuration key terms.\n> \n> Micronit. I think you backtick-quoted `--all`, `--no-prune`, and\n> friends, that are not configuration keyu terms but command line\n> options.\n\nAhh, right you are. That was due to my re-use of an earlier\nexample from Jean-Noël's work and an incomplete\nproof-reading. So I'll want to change \"configuration key\nterms\" to something like \"option terms\" to match what\nprevious commits have used for similar changes.\n\nThanks for spotting.\n\n-- \nTodd\n"},{"id":"552751","messageId":"20260915131036.393249-2-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v3 1/2] doc/pack-refs: convert synopsis and options to new style","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-15T13:10:31Z","receivedAt":"2026-09-15T13:10:40Z","isPatch":true,"body":"Replace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section via the included\npack-refs-options.adoc and convert the standalone placeholder __\nin prose.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 2 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\nindex fde9f2f294..69e018d07e 100644\n--- a/Documentation/git-pack-refs.adoc\n+++ b/Documentation/git-pack-refs.adoc\n@@ -7,8 +7,8 @@ git-pack-refs - Pack heads and tags for efficient repository access\n \n SYNOPSIS\n --------\n-[verse]\n-'git pack-refs' [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n+[synopsis]\n+git pack-refs [--all] [--no-prune] [--auto] [--include ] [--exclude ]\n \n DESCRIPTION\n -----------\n@@ -52,8 +52,8 @@ BUGS\n ----\n \n Older documentation written before the packed-refs mechanism was\n-introduced may still say things like \".git/refs/heads/ file\n-exists\" when it means \"branch exists\".\n+introduced may still say things like \".git/refs/heads/__ file\n+exists\" when it means \"branch __ exists\".\n \n \n GIT\ndiff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc\nindex 0b11282941..2263648b39 100644\n--- a/Documentation/pack-refs-options.adoc\n+++ b/Documentation/pack-refs-options.adoc\n@@ -1,4 +1,4 @@\n---all::\n+`--all`::\n \n The command by default packs all tags and refs that are already\n packed, and leaves other refs\n@@ -8,12 +8,12 @@ This option causes all refs to be packed as well, with the exception\n of hidden refs, broken refs, and symbolic refs. Useful for a repository\n with many branches of historical interests.\n \n---no-prune::\n+`--no-prune`::\n \n The command usually removes loose refs under `$GIT_DIR/refs`\n hierarchy after packing them. This option tells it not to.\n \n---auto::\n+`--auto`::\n \n Pack refs as needed depending on the current state of the ref database. The\n behavior depends on the ref format used by the repository and may change in the\n@@ -29,7 +29,7 @@ future.\n \t maintains the property that N is at least twice as big as N+1. Only\n \t tables that violate this property are compacted.\n \n---include ::\n+`--include `::\n \n Pack refs based on a `glob(7)` pattern. Repetitions of this option\n accumulate inclusion patterns. If a ref is both included in `--include` and\n@@ -38,7 +38,7 @@ tags from being included by default. Symbolic refs and broken refs will never\n be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear\n and reset the list of patterns.\n \n---exclude ::\n+`--exclude `::\n \n Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option\n accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of\n-- \n2.56.0.rc0\n\n"},{"id":"552752","messageId":"20260915131036.393249-1-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v2 0/2] doc lint fixes for pack-refs and refs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-15T13:10:30Z","receivedAt":"2026-09-15T13:10:40Z","isPatch":true,"body":"I was reading git-refs(1) after noticing it learned some new tricks\nin the 2.56.0 release notes. The formatting stood out because the\nfirst two commands, migrate and verify are bold (in the man pages)\nbut subsequent commands are not. The HTML is similarly affected,\nwith those commands colored differently than the rest in our online\ndocumentation:\n\n https://git-scm.com/docs/git-refs\n\nThis is due to inconsistent backtick-quotes.\n\nAs git-refs.adoc includes pack-refs-options.adoc, I updated it to\nconsistently use backtick quoting and converted the only other file\nwhich includes it, git-pack-refs.adoc.\n\nChanges since v2:\n\n * improve wording of pack-refs commit message and change\n \"configuration key\" to \"options\".\n\nChanges since v1:\n\n * Drop Documentation/lint-documentation-style.perl change. It\n is likely to cause more false positives than we want.\n\nTodd Zullinger (2):\n doc/pack-refs: convert synopsis and options to new style\n doc/refs: backtick-quote commands and options consistently\n\n Documentation/git-pack-refs.adoc | 8 ++++----\n Documentation/git-refs.adoc | 14 +++++++-------\n Documentation/pack-refs-options.adoc | 10 +++++-----\n 3 files changed, 16 insertions(+), 16 deletions(-)\n\nRange-diff against v2:\n1: 03c1e8c073 < -: ---------- doc lint: match commands as well as options for synopsis style check\n2: eb3b95c7a7 ! 1: 280a322df0 doc/pack-refs: convert synopsis and options to new style\n @@ Commit message\n Replace [verse] with [synopsis] in the SYNOPSIS block and remove\n single-quote formatting from the command name.\n \n - Backtick-quote all option terms in the OPTIONS section and convert\n - the standalone placeholder __ in prose.\n -\n - Update the included pack-refs-options.adoc to backtick-quote all\n - configuration key terms.\n + Backtick-quote all option terms in the OPTIONS section via the included\n + pack-refs-options.adoc and convert the standalone placeholder __\n + in prose.\n \n Signed-off-by: Todd Zullinger \n \n3: 7af3718a71 = 2: 9475c1c1bc doc/refs: backtick-quote commands and options consistently\n-- \n2.56.0.rc0\n\n"},{"id":"552753","messageId":"20260915131036.393249-3-tmz@pobox.com","threadId":"66318","inReplyTo":"20260912191509.844954-1-tmz@pobox.com","subject":"[PATCH v3 2/2] doc/refs: backtick-quote commands and options consistently","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-15T13:10:32Z","receivedAt":"2026-09-15T13:10:41Z","isPatch":true,"body":"The git-refs doc was converted to the synopsis style in 89be7d2774\n(builtin/refs: add '--no-reflog' flag to drop reflogs, 2025-02-21). The\ncommands and options were not backtick-quoted at that time. 84f3d6e11e\n(doc lint: check that synopsis manpages have synopsis inlines,\n2025-08-11) applied backtick-quotes to the existing commands and\noptions.\n\nSubsequently, a number of commands and options were added without such\nquoting, leaving the documentation rendered inconsistently. Apply\nbacktick-quotes to all entries.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-refs.adoc | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 9063892651..9dc08cbca9 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -54,40 +54,40 @@ These limitations may eventually be lifted.\n `verify`::\n \tVerify reference database consistency.\n \n-list::\n+`list`::\n \tList references in the repository with support for filtering,\n \tformatting, and sorting. This subcommand is an alias for\n \tlinkgit:git-for-each-ref[1] and offers identical functionality.\n \n-exists::\n+`exists`::\n \tCheck whether the given reference exists. Returns an exit code of 0 if\n \tit does, 2 if it is missing, and 1 in case looking up the reference\n \tfailed with an error other than the reference being missing. This does\n \tnot verify whether the reference resolves to an actual object.\n \n-optimize::\n+`optimize`::\n \tOptimizes references to improve repository performance and reduce disk\n \tusage. This subcommand is an alias for linkgit:git-pack-refs[1] and\n \toffers identical functionality.\n \n-create::\n+`create`::\n \tCreate the given reference, which must not already exist, pointing at\n \t``.\n \n-delete::\n+`delete`::\n \tDelete the given reference. This subcommand mirrors `git update-ref -d`\n \t(see linkgit:git-update-ref[1]). When `` is given, the\n \treference is only deleted after verifying that it currently contains\n \t``.\n \n-update::\n+`update`::\n \tUpdate the given reference to point at ``. If ``\n \tis given, the reference is only updated after verifying that it\n \tcurrently contains ``. As a special case, an all-zeroes\n \t`` deletes the branch, whereas an all-zeroes ``\n \tensures that the branch does not yet exist.\n \n-rename::\n+`rename`::\n \tRename the reference `` to ``. The old reference must\n \texist and the new reference must not yet exist, and both must have a\n \twell-formed name (see linkgit:git-check-ref-format[1]).\n-- \n2.56.0.rc0\n\n"},{"id":"552754","messageId":"20260915131509.EztJBORN@teonanacatl.net","threadId":"66318","inReplyTo":"20260914154350.LjUwy8DF@teonanacatl.net","subject":"Re: [PATCH v2 1/2] doc/pack-refs: convert synopsis and options to new style","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2026-09-15T13:15:09Z","receivedAt":"2026-09-15T13:15:11Z","isPatch":true,"body":"I wrote:\n> Junio C Hamano wrote:\n>> Todd Zullinger writes:\n>> \n>>> Replace [verse] with [synopsis] in the SYNOPSIS block and remove\n>>> single-quote formatting from the command name.\n>>>\n>>> Backtick-quote all option terms in the OPTIONS section and convert\n>>> the standalone placeholder __ in prose.\n>>>\n>>> Update the included pack-refs-options.adoc to backtick-quote all\n>>> configuration key terms.\n>> \n>> Micronit. I think you backtick-quoted `--all`, `--no-prune`, and\n>> friends, that are not configuration keyu terms but command line\n>> options.\n> \n> Ahh, right you are. That was due to my re-use of an earlier\n> example from Jean-Noël's work and an incomplete\n> proof-reading. So I'll want to change \"configuration key\n> terms\" to something like \"option terms\" to match what\n> previous commits have used for similar changes.\n\nIn looking at that commit message further, I update the\nwording slightly as there are no options in the OPTION\nsection which are not part of pack-refs-options.adoc. I\ncondensed that to a single, more accurate sentence.\n\nWith luck, v3 is now ready to go.\n\nThanks,\n\n-- \nTodd\n"},{"id":"552761","messageId":"xmqqpkye1nyb.fsf@gitster.g","threadId":"66318","inReplyTo":"20260915131036.393249-1-tmz@pobox.com","subject":"Re: [PATCH v2 0/2] doc lint fixes for pack-refs and refs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-15T16:25:32Z","receivedAt":"2026-09-15T16:25:35Z","isPatch":true,"body":"Todd Zullinger writes:\n\n> I was reading git-refs(1) after noticing it learned some new tricks\n> in the 2.56.0 release notes. The formatting stood out because the\n> first two commands, migrate and verify are bold (in the man pages)\n> but subsequent commands are not. The HTML is similarly affected,\n> with those commands colored differently than the rest in our online\n> documentation:\n>\n> https://git-scm.com/docs/git-refs\n>\n> This is due to inconsistent backtick-quotes.\n>\n> As git-refs.adoc includes pack-refs-options.adoc, I updated it to\n> consistently use backtick quoting and converted the only other file\n> which includes it, git-pack-refs.adoc.\n>\n> Changes since v2:\n>\n> * improve wording of pack-refs commit message and change\n> \"configuration key\" to \"options\".\n\nThanks, will replace.\n"}]}