Re: [PATCH] replay: drop rev-list formatting options from manual

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 20, 2026, 02:19 UTC
Message-ID: <xmqqldht2fgd.fsf@gitster.g>
In-Reply-To: <01a7acfaf87494419b3766da57d4c05cf99c79bb.1768873599.git.ben.knoble+github@gmail.com>

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

Show 14 quoted lines

> The rev-list options in our manuals are quite long; git-replay's manual
> is no exception. Since replay doesn't use the formatting options at all
> (it has its own output format), drop them.
>
> Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
> ---
>
> Notes (benknoble/commits):
>     I noticed this while reading. It took me a minute to find the
>     Asciidoc reference on multiple attributes [1] since it's not used
>     elsewhere in the rev-list include :) I'm not sure it needs to be
>     included in the commit message, though normally I would, personally.
>
>     [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/

Indeed. Not just rev-list, but ifdef:: or ifndef:: anywhere do not check multiple attributes in existing docs.

"ifndef::git-shortlog,git-replay[]" is rather hard to follow, as it is unclear if they are ANDed or ORed, and it does not help to have it with negation X-<. I guess there always is the first instance, and we need to get used to it ;-)

As long as the construct is understood correctly with AsciiDoc and Asciidoctor (two renderers we depend on), it is OK, but I do agree with you it deserves to be said in the log message that you noticed this is the first time we use the syntax.

Thanks.

Show 37 quoted lines

>  Documentation/git-replay.adoc       | 1 +
>  Documentation/rev-list-options.adoc | 4 ++--
>  2 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index 4c61f3aa1f..c3b214ec69 100644
> --- a/Documentation/git-replay.adoc
> +++ b/Documentation/git-replay.adoc
> @@ -64,6 +64,7 @@ The default mode can be configured via the `replay.refAction` configuration vari
>  	range should have a single tip, so that it's clear to which tip the
>  	advanced <branch> should point.
>  
> +:git-replay: 1
>  include::rev-list-options.adoc[]
>  
>  [[output]]
> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> index 453ec59057..c4d7a6b989 100644
> --- a/Documentation/rev-list-options.adoc
> +++ b/Documentation/rev-list-options.adoc
> @@ -1096,7 +1096,7 @@ endif::git-rev-list[]
>  	Overrides a previous `--no-walk`.
>  endif::git-shortlog[]
>  
> -ifndef::git-shortlog[]
> +ifndef::git-shortlog,git-replay[]
>  Commit Formatting
>  ~~~~~~~~~~~~~~~~~
>  
> @@ -1265,4 +1265,4 @@ ifdef::git-rev-list[]
>  	counts and print the count for equivalent commits separated
>  	by a tab.
>  endif::git-rev-list[]
> -endif::git-shortlog[]
> +endif::git-shortlog,git-replay[]
>
> base-commit: b5c409c40f1595e3e590760c6f14a16b6683e22c