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

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.