[PATCH 0/3] doc lint fixes for pack-refs and refs

[PATCH 0/3] doc lint fixes for pack-refs and refs

[Todd Zullinger]

I was reading git-refs(1) after noticing it learned some new tricks in the
2.56.0 release notes.  The formatting stood out because the first two commands,
migrate and verify are bold (in the man pages) but subsequent commands are not.
The HTML is similarly affected, with those commands colored differently than
the rest in our online documentation:

    https://git-scm.com/docs/git-refs

This is due to inconsistent backtick-quotes.

This led me to the lint check, which I think might benefit from the small
change here to match commands as well as options.  Running something like this
reports a number of files which could also use some tweaks:

    cd Documentation && for i in *.adoc; do
        output=$(perl lint-documentation-style.perl <$i 2>&1)
        [[ -n $output ]] && printf '\n%s:\n%s\n' $i "$output"
    done

I _think_ we want to backtick-quote those when using the synopsis style.  (If
not, then the change is wrong and we should remove the backticks from the two
commands in git-refs.adoc and other places.)

As git-refs.adoc includes pack-refs-options.adoc, I updated it to consistently
use backtick quoting and converted the only other file which includes it,
git-pack-refs.adoc.

Todd Zullinger (3):
  doc lint: match commands as well as options for synopsis style check
  doc/pack-refs: convert synopsis and options to new style
  doc/refs: backtick-quote commands and options consistently

 Documentation/git-pack-refs.adoc            |  8 ++++----
 Documentation/git-refs.adoc                 | 14 +++++++-------
 Documentation/lint-documentation-style.perl |  4 ++--
 Documentation/pack-refs-options.adoc        | 10 +++++-----
 4 files changed, 18 insertions(+), 18 deletions(-)

-- 
2.56.0.rc0

[PATCH 1/3] doc lint: match commands as well as options for synopsis style check

[Todd Zullinger]

Both `--option::` and `command::` should be backtick-quoted with the new
synopsis style.  Remove the requirement for a leading `-` from the regex
which scans for these patterns.

Avoid matching lines like `linkgit:git-diff[1]::` by replacing `.*` with
`[^:]*` in the regex.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/lint-documentation-style.perl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl
index d7ab732293..6eece11bdc 100755
--- a/Documentation/lint-documentation-style.perl
+++ b/Documentation/lint-documentation-style.perl
@@ -24,8 +24,8 @@ sub report {
 	if ($line =~ /^\[synopsis\]$/) {
 		$synopsis_style = 1;
 	}
-	if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) {
-			report($line, "synopsis style and definition list item not backquoted");
+	if (($line =~ /^([-a-z][^:]*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) {
+		report($line, "synopsis style and definition list item not backquoted");
 	}
 }
 
-- 
2.56.0.rc0

[PATCH 2/3] doc/pack-refs: convert synopsis and options to new style

[Todd Zullinger]

Replace [verse] with [synopsis] in the SYNOPSIS block and remove
single-quote formatting from the command name.

Backtick-quote all option terms in the OPTIONS section and convert
the standalone placeholder _<branch>_ in prose.

Update the included pack-refs-options.adoc to backtick-quote all
configuration key terms.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/git-pack-refs.adoc     |  8 ++++----
 Documentation/pack-refs-options.adoc | 10 +++++-----
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc
index fde9f2f294..69e018d07e 100644
--- a/Documentation/git-pack-refs.adoc
+++ b/Documentation/git-pack-refs.adoc
@@ -7,8 +7,8 @@ git-pack-refs - Pack heads and tags for efficient repository access
 
 SYNOPSIS
 --------
-[verse]
-'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
+[synopsis]
+git pack-refs [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
 
 DESCRIPTION
 -----------
@@ -52,8 +52,8 @@ BUGS
 ----
 
 Older documentation written before the packed-refs mechanism was
-introduced may still say things like ".git/refs/heads/<branch> file
-exists" when it means "branch <branch> exists".
+introduced may still say things like ".git/refs/heads/_<branch>_ file
+exists" when it means "branch _<branch>_ exists".
 
 
 GIT
diff --git a/Documentation/pack-refs-options.adoc b/Documentation/pack-refs-options.adoc
index 0b11282941..2263648b39 100644
--- a/Documentation/pack-refs-options.adoc
+++ b/Documentation/pack-refs-options.adoc
@@ -1,4 +1,4 @@
---all::
+`--all`::
 
 The command by default packs all tags and refs that are already
 packed, and leaves other refs
@@ -8,12 +8,12 @@ This option causes all refs to be packed as well, with the exception
 of hidden refs, broken refs, and symbolic refs. Useful for a repository
 with many branches of historical interests.
 
---no-prune::
+`--no-prune`::
 
 The command usually removes loose refs under `$GIT_DIR/refs`
 hierarchy after packing them.  This option tells it not to.
 
---auto::
+`--auto`::
 
 Pack refs as needed depending on the current state of the ref database. The
 behavior depends on the ref format used by the repository and may change in the
@@ -29,7 +29,7 @@ future.
 	  maintains the property that N is at least twice as big as N+1. Only
 	  tables that violate this property are compacted.
 
---include <pattern>::
+`--include <pattern>`::
 
 Pack refs based on a `glob(7)` pattern. Repetitions of this option
 accumulate inclusion patterns. If a ref is both included in `--include` and
@@ -38,7 +38,7 @@ tags from being included by default. Symbolic refs and broken refs will never
 be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
 and reset the list of patterns.
 
---exclude <pattern>::
+`--exclude <pattern>`::
 
 Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
 accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
-- 
2.56.0.rc0

[PATCH 3/3] doc/refs: backtick-quote commands and options consistently

[Todd Zullinger]

The git-refs doc was converted to the synopsis style in 89be7d2774
(builtin/refs: add '--no-reflog' flag to drop reflogs, 2025-02-21).  The
commands and options were not backtick-quoted at that time.  84f3d6e11e
(doc lint: check that synopsis manpages have synopsis inlines,
2025-08-11) applied backtick-quotes to the existing commands and
options.

Subsequently, a number of commands and options were added without such
quoting, leaving the documentation rendered inconsistently.  Apply
backtick-quotes to all entries.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/git-refs.adoc | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 9063892651..9dc08cbca9 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -54,40 +54,40 @@ These limitations may eventually be lifted.
 `verify`::
 	Verify reference database consistency.
 
-list::
+`list`::
 	List references in the repository with support for filtering,
 	formatting, and sorting. This subcommand is an alias for
 	linkgit:git-for-each-ref[1] and offers identical functionality.
 
-exists::
+`exists`::
 	Check whether the given reference exists. Returns an exit code of 0 if
 	it does, 2 if it is missing, and 1 in case looking up the reference
 	failed with an error other than the reference being missing. This does
 	not verify whether the reference resolves to an actual object.
 
-optimize::
+`optimize`::
 	Optimizes references to improve repository performance and reduce disk
 	usage. This subcommand is an alias for linkgit:git-pack-refs[1] and
 	offers identical functionality.
 
-create::
+`create`::
 	Create the given reference, which must not already exist, pointing at
 	`<new-value>`.
 
-delete::
+`delete`::
 	Delete the given reference. This subcommand mirrors `git update-ref -d`
 	(see linkgit:git-update-ref[1]). When `<old-value>` is given, the
 	reference is only deleted after verifying that it currently contains
 	`<old-value>`.
 
-update::
+`update`::
 	Update the given reference to point at `<new-value>`. If `<old-value>`
 	is given, the reference is only updated after verifying that it
 	currently contains `<old-value>`. As a special case, an all-zeroes
 	`<new-value>` deletes the branch, whereas an all-zeroes `<old-value>`
 	ensures that the branch does not yet exist.
 
-rename::
+`rename`::
 	Rename the reference `<oldref>` to `<newref>`. The old reference must
 	exist and the new reference must not yet exist, and both must have a
 	well-formed name (see linkgit:git-check-ref-format[1]).
-- 
2.56.0.rc0

Re: [PATCH 0/3] doc lint fixes for pack-refs and refs

[Jean-Noël AVILA]

On Saturday, 12 September 2026 21:14:59 CEST Todd Zullinger wrote:
> I was reading git-refs(1) after noticing it learned some new tricks in the
> 2.56.0 release notes.  The formatting stood out because the first two 
commands,
> migrate and verify are bold (in the man pages) but subsequent commands are 
not.
> The HTML is similarly affected, with those commands colored differently than
> the rest in our online documentation:
> 
>     https://git-scm.com/docs/git-refs
> 
> This is due to inconsistent backtick-quotes.
> 
> This led me to the lint check, which I think might benefit from the small
> change here to match commands as well as options.  Running something like 
this
> reports a number of files which could also use some tweaks:
> 
>     cd Documentation && for i in *.adoc; do
>         output=$(perl lint-documentation-style.perl <$i 2>&1)
>         [[ -n $output ]] && printf '\n%s:\n%s\n' $i "$output"
>     done
> 
> I _think_ we want to backtick-quote those when using the synopsis style.  
(If
> not, then the change is wrong and we should remove the backticks from the 
two
> commands in git-refs.adoc and other places.)
> 
> As git-refs.adoc includes pack-refs-options.adoc, I updated it to 
consistently
> use backtick quoting and converted the only other file which includes it,
> git-pack-refs.adoc.
> 
> Todd Zullinger (3):
>   doc lint: match commands as well as options for synopsis style check
>   doc/pack-refs: convert synopsis and options to new style
>   doc/refs: backtick-quote commands and options consistently
> 
>  Documentation/git-pack-refs.adoc            |  8 ++++----
>  Documentation/git-refs.adoc                 | 14 +++++++-------
>  Documentation/lint-documentation-style.perl |  4 ++--
>  Documentation/pack-refs-options.adoc        | 10 +++++-----
>  4 files changed, 18 insertions(+), 18 deletions(-)

When I put this linting in place, I was specifically targeting the options. 
The other cases of use of definition list could range from commands to real 
definitions of words (see gitglossary.adoc and git-add.adoc), and extending 
the match can trigger false positives. Backticked terms are supposed to be 
immutable for translators, so this formatting should not be used for real 
definitions. 
For this reason, the regex is restricted on purpose, but selecting the files 
to check to allow to extend the range of checks.
, 
FWIW, the proposed change triggers false positives for git-add.adoc, git-
push.adoc, git-difftool.adoc, git-daemon.adoc and git-fetch.adoc.

Re: [PATCH 0/3] doc lint fixes for pack-refs and refs

[Todd Zullinger]

Hi,

Jean-Noël AVILA wrote:
> When I put this linting in place, I was specifically targeting the options. 
> The other cases of use of definition list could range from commands to real 
> definitions of words (see gitglossary.adoc and git-add.adoc), and extending 
> the match can trigger false positives. Backticked terms are supposed to be 
> immutable for translators, so this formatting should not be used for real 
> definitions. 
> For this reason, the regex is restricted on purpose, but selecting the files 
> to check to allow to extend the range of checks.
> , 
> FWIW, the proposed change triggers false positives for git-add.adoc, git-
> push.adoc, git-difftool.adoc, git-daemon.adoc and git-fetch.adoc.

That's fine, I don't mind dropping that patch if the false
positives will be more annoying than skipping the checks for
commands and missing some of them.

I'll wait a little before sending a re-roll with that
dropped, in case anyone spots issues in the main patches to
the pack-refs and refs docs.

Thanks,

-- 
Todd