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

["Jean-Noël AVILA" <jn.avila@free.fr>]

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.