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

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

[D. Ben Knoble]

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/

 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
-- 
2.52.0.rc0.569.g0e1cb519e9.dirty

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

[Junio C Hamano]

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

> 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.

>  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

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

[D. Ben Knoble]

On Mon, Jan 19, 2026 at 9:19 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble" <ben.knoble+github@gmail.com> writes:
>
> > 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.

Extra sentences coming in v2 then ;)

RE: AsciiDoc vs. Asciidoctor, it was a bit difficult for me to
untangle https://docs.asciidoctor.org/ and https://asciidoc.org/
(which points quite a bit at the former for specs/docs). It seems that
by AsciiDoc you refer to the legacy Python processor
(https://github.com/asciidoc-py/asciidoc-py/), and then Asciidoctor is
presumably the Ruby processor
(https://github.com/asciidoctor/asciidoctor)?

If I've understood all that correctly, then I have the Python version
installed for building Git and it understood the syntax. Given that
the Ruby version is newer, I think it should also work against the
spec.

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

[Junio C Hamano]

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

> If I've understood all that correctly, then I have the Python version
> installed for building Git and it understood the syntax. Given that
> the Ruby version is newer, I think it should also work against the
> spec.

We have CI jobs to catch the differences so hopefully we know soon
enough if one is so badly broken ;-)

Thanks.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> "D. Ben Knoble" <ben.knoble+github@gmail.com> writes:
>
>> If I've understood all that correctly, then I have the Python version
>> installed for building Git and it understood the syntax. Given that
>> the Ruby version is newer, I think it should also work against the
>> spec.
>
> We have CI jobs to catch the differences so hopefully we know soon
> enough if one is so badly broken ;-)
>
> Thanks.

We didn't have to wait for CI jobs.  You can try

	make -C Documentation lint-docs

which reveals that somebody is not expecting these multiple things
there.  I think Documentation/lint-gitlink.perl needs updating.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> "D. Ben Knoble" <ben.knoble+github@gmail.com> writes:
>>
>>> If I've understood all that correctly, then I have the Python version
>>> installed for building Git and it understood the syntax. Given that
>>> the Ruby version is newer, I think it should also work against the
>>> spec.
>>
>> We have CI jobs to catch the differences so hopefully we know soon
>> enough if one is so badly broken ;-)
>>
>> Thanks.
>
> We didn't have to wait for CI jobs.  You can try
>
> 	make -C Documentation lint-docs
>
> which reveals that somebody is not expecting these multiple things
> there.  I think Documentation/lint-gitlink.perl needs updating.

Perhaps something like this.  Haven't thought things through to spot
negative ramifications, though.

The original comes from f81a574f (doc: test linkgit macros for
well-formedness, 2025-08-11); its author Cc'ed for better ideas.

----- >8 -----
Subject: [PATCH] lint-gitlink: do not get confused by overly long ifdef directive

The old pattern, when encountered "ifndef::git-shortlog,git-bar[]",
complained that "hortlog," (i.e., a substring that is up to 8 bytes
long, that comes before "git-bar[]") is not "linkgit:", which was a
nonsense.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/lint-gitlink.perl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index f183a18df2..91621f9db1 100755
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -41,7 +41,7 @@ sub report {
 @ARGV = $to_check;
 while (<>) {
 	my $line = $_;
-	while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) {
+	while ($line =~ m/([a-z]{,8}:+)((git[-a-z]+|scalar)\[(\d)*\])/g) {
 	    my $pos = pos $line;
 	    my ($macro, $target, $page, $section) = ($1, $2, $3, $4);
 		if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) {
-- 
2.53.0-rc0-249-g60c15f3eb8

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

[Jean-Noël Avila]

Le 21/01/2026 à 00:11, Junio C Hamano a écrit :
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> "D. Ben Knoble" <ben.knoble+github@gmail.com> writes:
>>>
>>>> If I've understood all that correctly, then I have the Python version
>>>> installed for building Git and it understood the syntax. Given that
>>>> the Ruby version is newer, I think it should also work against the
>>>> spec.
>>>
>>> We have CI jobs to catch the differences so hopefully we know soon
>>> enough if one is so badly broken ;-)
>>>
>>> Thanks.
>>
>> We didn't have to wait for CI jobs.  You can try
>>
>> 	make -C Documentation lint-docs
>>
>> which reveals that somebody is not expecting these multiple things
>> there.  I think Documentation/lint-gitlink.perl needs updating.
> 
> Perhaps something like this.  Haven't thought things through to spot
> negative ramifications, though.
> 
> The original comes from f81a574f (doc: test linkgit macros for
> well-formedness, 2025-08-11); its author Cc'ed for better ideas.
> 

The initial motive for this script was to catch malformed linkgit
occurrences that were present in the docs: stray git-foo[1], without
the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what
would come next, the regex was coined very broad, with the assumed risk
of raising false positives.

The issue here is in handling the ifdef macros which are block macros
and are more easily detected as such. I would reject preemtively lines
with '^ifn?def::' instead.


----- >8 -----
Subject: [PATCH] lint-gitlink: preemptively ignore all /ifn?def|endif/ macros

Instead of testing if the macro name is ifn?def:: as if it were a inline
macro, it is faster and safer to just ignore such block macro lines before
hand.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/lint-gitlink.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index f183a18df..b5d982e8e 100755
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -41,10 +41,11 @@ sub report {
 @ARGV = $to_check;
 while (<>) {
 	my $line = $_;
+	next if $line =~ /^\s*(ifn?def|endif)::/;
 	while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) {
 	    my $pos = pos $line;
 	    my ($macro, $target, $page, $section) = ($1, $2, $3, $4);
-		if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) {
+		if ( $macro ne "linkgit:" ) {
 			report($pos, $line, $target, "linkgit: macro expected");
 		}
 	}

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

[Junio C Hamano]

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

>> The original comes from f81a574f (doc: test linkgit macros for
>> well-formedness, 2025-08-11); its author Cc'ed for better ideas.
>> 
>
> The initial motive for this script was to catch malformed linkgit
> occurrences that were present in the docs: stray git-foo[1], without
> the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what
> would come next, the regex was coined very broad, with the assumed risk
> of raising false positives.
>
> The issue here is in handling the ifdef macros which are block macros
> and are more easily detected as such. I would reject preemtively lines
> with '^ifn?def::' instead.

Yup, that is much cleaner.  Thanks!

> ----- >8 -----
> Subject: [PATCH] lint-gitlink: preemptively ignore all /ifn?def|endif/ macros
>
> Instead of testing if the macro name is ifn?def:: as if it were a inline
> macro, it is faster and safer to just ignore such block macro lines before
> hand.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/lint-gitlink.perl | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
> index f183a18df..b5d982e8e 100755
> --- a/Documentation/lint-gitlink.perl
> +++ b/Documentation/lint-gitlink.perl
> @@ -41,10 +41,11 @@ sub report {
>  @ARGV = $to_check;
>  while (<>) {
>  	my $line = $_;
> +	next if $line =~ /^\s*(ifn?def|endif)::/;
>  	while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) {
>  	    my $pos = pos $line;
>  	    my ($macro, $target, $page, $section) = ($1, $2, $3, $4);
> -		if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) {
> +		if ( $macro ne "linkgit:" ) {
>  			report($pos, $line, $target, "linkgit: macro expected");
>  		}
>  	}

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

[D. Ben Knoble]

On Wed, Jan 21, 2026 at 11:26 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Jean-Noël Avila <jn.avila@free.fr> writes:
>
> >> The original comes from f81a574f (doc: test linkgit macros for
> >> well-formedness, 2025-08-11); its author Cc'ed for better ideas.
> >>
> >
> > The initial motive for this script was to catch malformed linkgit
> > occurrences that were present in the docs: stray git-foo[1], without
> > the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what
> > would come next, the regex was coined very broad, with the assumed risk
> > of raising false positives.
> >
> > The issue here is in handling the ifdef macros which are block macros
> > and are more easily detected as such. I would reject preemtively lines
> > with '^ifn?def::' instead.
>
> Yup, that is much cleaner.  Thanks!

Thanks all. I always forget the documentation lint target. I'll try to
send a v3 this weekend, but travelling, so responses may be delayed.

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

[D. Ben Knoble]

On Wed, Jan 21, 2026 at 3:03 PM D. Ben Knoble
<ben.knoble+github@gmail.com> wrote:
>
> On Wed, Jan 21, 2026 at 11:26 AM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Jean-Noël Avila <jn.avila@free.fr> writes:
> >
> > >> The original comes from f81a574f (doc: test linkgit macros for
> > >> well-formedness, 2025-08-11); its author Cc'ed for better ideas.
> > >>
> > >
> > > The initial motive for this script was to catch malformed linkgit
> > > occurrences that were present in the docs: stray git-foo[1], without
> > > the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what
> > > would come next, the regex was coined very broad, with the assumed risk
> > > of raising false positives.
> > >
> > > The issue here is in handling the ifdef macros which are block macros
> > > and are more easily detected as such. I would reject preemtively lines
> > > with '^ifn?def::' instead.
> >
> > Yup, that is much cleaner.  Thanks!
>
> Thanks all. I always forget the documentation lint target. I'll try to
> send a v3 this weekend, but travelling, so responses may be delayed.

Looks like this was queued and merged. Thanks both!

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

[D. Ben Knoble]

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.

This is the first time we have needed compound tests [1] for if[n]def in
our documentation:

    git grep '^ifn\?def::' Documentation | grep '[,+]'

[1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/

For both ifdef and ifndef, the "," takes on the intuitive meaning:
- ifdef: if any of the listed attributes are set…
- ifndef: unless any of the listed attributes are set

(Use "+" for "all".)

Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 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[]

Diff-intervalle contre v1 :
1:  01a7acfaf8 ! 1:  97ae3ba465 replay: drop rev-list formatting options from manual
    @@ Commit message
         is no exception. Since replay doesn't use the formatting options at all
         (it has its own output format), drop them.
     
    +    This is the first time we have needed compound tests [1] for if[n]def in
    +    our documentation:
     
    - ## 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.
    +        git grep '^ifn\?def::' Documentation | grep '[,+]'
     
         [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/
     
    +    For both ifdef and ifndef, the "," takes on the intuitive meaning:
    +    - ifdef: if any of the listed attributes are set…
    +    - ifndef: unless any of the listed attributes are set
    +
    +    (Use "+" for "all".)
    +
      ## Documentation/git-replay.adoc ##
     @@ Documentation/git-replay.adoc: 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

base-commit: b5c409c40f1595e3e590760c6f14a16b6683e22c
-- 
2.52.0.rc0.569.g0e1cb519e9.dirty