Re: [PATCH] doc:git-for-each-ref: fix styling and typos

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 30, 2025, 15:48 UTC
Message-ID: <xmqqjz4t44ei.fsf@gitster.g>
In-Reply-To: <20250629110652.123890-1-jn.avila@free.fr>

Jean-Noël Avila <jn.avila@free.fr> writes:

Show 7 quoted lines

> This commit fixes the synopsis syntax writing and changes the wording of a few
> descriptions to be more consistent with the rest of the documentation.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/git-for-each-ref.adoc | 30 ++++++++++++++---------------
>  1 file changed, 14 insertions(+), 16 deletions(-)

It is not making anything worse and all the changes I see here (except for a stray SP slipped in) are for the better, but it is curious that this stops halfway. Things I noticed:

Show 8 quoted lines

> diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
> index 5ef89fc0fe..c2b2660771 100644
> --- a/Documentation/git-for-each-ref.adoc
> +++ b/Documentation/git-for-each-ref.adoc
> @@ -8,13 +8,13 @@ git-for-each-ref - Output information on each ref
>  SYNOPSIS
>  --------
>  [verse]

Eventually we would switch to [synopsis] I presume?

Show 28 quoted lines

> -'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
> -		   [(--sort=<key>)...] [--format=<format>]
> -		   [--include-root-refs] [ --stdin | <pattern>... ]
> +'git for-each-ref' [--count=<count>] [--shell | --perl | --python | --tcl]
> +		   [(--sort=<key>)...] [--format[=<format>]]
> +		   [--include-root-refs] [--stdin | <pattern>...]
>  		   [--points-at=<object>]
>  		   [--merged[=<object>]] [--no-merged[=<object>]]
>  		   [--contains[=<object>]] [--no-contains[=<object>]]
> -		   [--exclude=<pattern> ...]
> +		   [(--exclude=<excluded-pattern>)...]
>  
>  DESCRIPTION
>  -----------
> @@ -35,13 +35,11 @@ OPTIONS
>  	beginning up to a slash.
>  
>  --stdin::
> -	If `--stdin` is supplied, then the list of patterns is read from
> -	standard input instead of from the argument list.
> +	The list of patterns is read from standard input instead of from
> +	the argument list.
>  
>  --count=<count>::
> -	By default the command shows all refs that match
> -	`<pattern>`.  This option makes it stop after showing
> -	that many refs.
> +	Stop after showing <count> refs.

This patch would have changed this to _<count>_, judging from what it did elsewhere.

Show 6 quoted lines

> @@ -50,7 +48,7 @@ OPTIONS
>  	multiple times, in which case the last key becomes the primary
>  	key.
>  
> ---format=<format>::
> + --format[=<format>]::

Stray SP in the front?

Show 12 quoted lines

> @@ -100,10 +98,10 @@ TAB %(refname)`.
>  	Do not print a newline after formatted refs where the format expands
>  	to the empty string.
>  
> ---exclude=<pattern>::
> -	If one or more patterns are given, only refs which do not match
> -	any excluded pattern(s) are shown. Matching is done using the
> -	same rules as `<pattern>` above.
> +--exclude=<excluded-pattern>::
> +	If one or more --exclude options are given, only refs which do not
> +	match any _<excluded-pattern>_ parameters are shown. Matching is done
> +	using the same rules as _<pattern>_ above.

OK. Doing the literal `--exclude` for options in the description is left for future patches would not make it any worse, and adopting _<placeholder>_ convention makes it better.

Show 12 quoted lines

>  --include-root-refs::
>  	List root refs (HEAD and pseudorefs) apart from regular refs.
> @@ -131,8 +129,8 @@ refname::
>  	`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
>  	turns `refs/tags/foo` into `refs`). When the ref does not have
>  	enough components, the result becomes an empty string if
> -	stripping with positive <N>, or it becomes the full refname if
> -	stripping with negative <N>.  Neither is an error.
> +	stripping with positive _<N>_, or it becomes the full refname if
> +	stripping with negative _<N>_.  Neither is an error.
>  +
>  `strip` can be used as a synonym to `lstrip`.