{"thread":{"id":"64831","subject":"[PATCH] replay: drop rev-list formatting options from manual","startedAt":"2026-01-20T01:48:00Z","lastAt":"2026-01-27T18:48:56Z","messageCount":11,"participants":["D. Ben Knoble","Junio C Hamano","Jean-Noël Avila"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"534203","messageId":"01a7acfaf87494419b3766da57d4c05cf99c79bb.1768873599.git.ben.knoble+github@gmail.com","threadId":"64831","inReplyTo":null,"subject":"[PATCH] replay: drop rev-list formatting options from manual","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-20T01:47:29Z","receivedAt":"2026-01-20T01:48:00Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"The rev-list options in our manuals are quite long; git-replay's manual\nis no exception. Since replay doesn't use the formatting options at all\n(it has its own output format), drop them.\n\nSigned-off-by: D. Ben Knoble \n---\n\nNotes (benknoble/commits):\n I noticed this while reading. It took me a minute to find the\n Asciidoc reference on multiple attributes [1] since it's not used\n elsewhere in the rev-list include :) I'm not sure it needs to be\n included in the commit message, though normally I would, personally.\n \n [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/\n\n Documentation/git-replay.adoc | 1 +\n Documentation/rev-list-options.adoc | 4 ++--\n 2 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4c61f3aa1f..c3b214ec69 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -64,6 +64,7 @@ The default mode can be configured via the `replay.refAction` configuration vari\n \trange should have a single tip, so that it's clear to which tip the\n \tadvanced should point.\n \n+:git-replay: 1\n include::rev-list-options.adoc[]\n \n [[output]]\ndiff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\nindex 453ec59057..c4d7a6b989 100644\n--- a/Documentation/rev-list-options.adoc\n+++ b/Documentation/rev-list-options.adoc\n@@ -1096,7 +1096,7 @@ endif::git-rev-list[]\n \tOverrides a previous `--no-walk`.\n endif::git-shortlog[]\n \n-ifndef::git-shortlog[]\n+ifndef::git-shortlog,git-replay[]\n Commit Formatting\n ~~~~~~~~~~~~~~~~~\n \n@@ -1265,4 +1265,4 @@ ifdef::git-rev-list[]\n \tcounts and print the count for equivalent commits separated\n \tby a tab.\n endif::git-rev-list[]\n-endif::git-shortlog[]\n+endif::git-shortlog,git-replay[]\n\nbase-commit: b5c409c40f1595e3e590760c6f14a16b6683e22c\n-- \n2.52.0.rc0.569.g0e1cb519e9.dirty\n\n"},{"id":"534204","messageId":"xmqqldht2fgd.fsf@gitster.g","threadId":"64831","inReplyTo":"01a7acfaf87494419b3766da57d4c05cf99c79bb.1768873599.git.ben.knoble+github@gmail.com","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-20T02:19:46Z","receivedAt":"2026-01-20T02:19:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> The rev-list options in our manuals are quite long; git-replay's manual\n> is no exception. Since replay doesn't use the formatting options at all\n> (it has its own output format), drop them.\n>\n> Signed-off-by: D. Ben Knoble \n> ---\n>\n> Notes (benknoble/commits):\n> I noticed this while reading. It took me a minute to find the\n> Asciidoc reference on multiple attributes [1] since it's not used\n> elsewhere in the rev-list include :) I'm not sure it needs to be\n> included in the commit message, though normally I would, personally.\n>\n> [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/\n\n\nIndeed. Not just rev-list, but ifdef:: or ifndef:: anywhere do not\ncheck multiple attributes in existing docs.\n\n\"ifndef::git-shortlog,git-replay[]\" is rather hard to follow, as it\nis unclear if they are ANDed or ORed, and it does not help to have\nit with negation X-<. I guess there always is the first instance,\nand we need to get used to it ;-)\n\nAs long as the construct is understood correctly with AsciiDoc and\nAsciidoctor (two renderers we depend on), it is OK, but I do agree\nwith you it deserves to be said in the log message that you noticed\nthis is the first time we use the syntax.\n\nThanks.\n\n> Documentation/git-replay.adoc | 1 +\n> Documentation/rev-list-options.adoc | 4 ++--\n> 2 files changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index 4c61f3aa1f..c3b214ec69 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -64,6 +64,7 @@ The default mode can be configured via the `replay.refAction` configuration vari\n> \trange should have a single tip, so that it's clear to which tip the\n> \tadvanced should point.\n> \n> +:git-replay: 1\n> include::rev-list-options.adoc[]\n> \n> [[output]]\n> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\n> index 453ec59057..c4d7a6b989 100644\n> --- a/Documentation/rev-list-options.adoc\n> +++ b/Documentation/rev-list-options.adoc\n> @@ -1096,7 +1096,7 @@ endif::git-rev-list[]\n> \tOverrides a previous `--no-walk`.\n> endif::git-shortlog[]\n> \n> -ifndef::git-shortlog[]\n> +ifndef::git-shortlog,git-replay[]\n> Commit Formatting\n> ~~~~~~~~~~~~~~~~~\n> \n> @@ -1265,4 +1265,4 @@ ifdef::git-rev-list[]\n> \tcounts and print the count for equivalent commits separated\n> \tby a tab.\n> endif::git-rev-list[]\n> -endif::git-shortlog[]\n> +endif::git-shortlog,git-replay[]\n>\n> base-commit: b5c409c40f1595e3e590760c6f14a16b6683e22c\n"},{"id":"534234","messageId":"CALnO6CCaVdJQ2xSPfvxQzVCfPsjbWHhMFUiLoiPQtVn9MeKFOw@mail.gmail.com","threadId":"64831","inReplyTo":"xmqqldht2fgd.fsf@gitster.g","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-20T14:04:25Z","receivedAt":"2026-01-20T14:04:38Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Jan 19, 2026 at 9:19 PM Junio C Hamano wrote:\n>\n> \"D. Ben Knoble\" writes:\n>\n> > The rev-list options in our manuals are quite long; git-replay's manual\n> > is no exception. Since replay doesn't use the formatting options at all\n> > (it has its own output format), drop them.\n> >\n> > Signed-off-by: D. Ben Knoble \n> > ---\n> >\n> > Notes (benknoble/commits):\n> > I noticed this while reading. It took me a minute to find the\n> > Asciidoc reference on multiple attributes [1] since it's not used\n> > elsewhere in the rev-list include :) I'm not sure it needs to be\n> > included in the commit message, though normally I would, personally.\n> >\n> > [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/\n>\n>\n> Indeed. Not just rev-list, but ifdef:: or ifndef:: anywhere do not\n> check multiple attributes in existing docs.\n>\n> \"ifndef::git-shortlog,git-replay[]\" is rather hard to follow, as it\n> is unclear if they are ANDed or ORed, and it does not help to have\n> it with negation X-<. I guess there always is the first instance,\n> and we need to get used to it ;-)\n>\n> As long as the construct is understood correctly with AsciiDoc and\n> Asciidoctor (two renderers we depend on), it is OK, but I do agree\n> with you it deserves to be said in the log message that you noticed\n> this is the first time we use the syntax.\n>\n> Thanks.\n\nExtra sentences coming in v2 then ;)\n\nRE: AsciiDoc vs. Asciidoctor, it was a bit difficult for me to\nuntangle https://docs.asciidoctor.org/ and https://asciidoc.org/\n(which points quite a bit at the former for specs/docs). It seems that\nby AsciiDoc you refer to the legacy Python processor\n(https://github.com/asciidoc-py/asciidoc-py/), and then Asciidoctor is\npresumably the Ruby processor\n(https://github.com/asciidoctor/asciidoctor)?\n\nIf I've understood all that correctly, then I have the Python version\ninstalled for building Git and it understood the syntax. Given that\nthe Ruby version is newer, I think it should also work against the\nspec.\n"},{"id":"534235","messageId":"97ae3ba465511d1ff73b11efb55d393ac5a4d9d0.1768917929.git.ben.knoble+github@gmail.com","threadId":"64831","inReplyTo":"01a7acfaf87494419b3766da57d4c05cf99c79bb.1768873599.git.ben.knoble+github@gmail.com","subject":"[PATCH v2] replay: drop rev-list formatting options from manual","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-20T14:05:57Z","receivedAt":"2026-01-20T14:06:25Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"The rev-list options in our manuals are quite long; git-replay's manual\nis no exception. Since replay doesn't use the formatting options at all\n(it has its own output format), drop them.\n\nThis is the first time we have needed compound tests [1] for if[n]def in\nour documentation:\n\n git grep '^ifn\\?def::' Documentation | grep '[,+]'\n\n[1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/\n\nFor both ifdef and ifndef, the \",\" takes on the intuitive meaning:\n- ifdef: if any of the listed attributes are set…\n- ifndef: unless any of the listed attributes are set\n\n(Use \"+\" for \"all\".)\n\nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-replay.adoc | 1 +\n Documentation/rev-list-options.adoc | 4 ++--\n 2 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4c61f3aa1f..c3b214ec69 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -64,6 +64,7 @@ The default mode can be configured via the `replay.refAction` configuration vari\n \trange should have a single tip, so that it's clear to which tip the\n \tadvanced should point.\n \n+:git-replay: 1\n include::rev-list-options.adoc[]\n \n [[output]]\ndiff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc\nindex 453ec59057..c4d7a6b989 100644\n--- a/Documentation/rev-list-options.adoc\n+++ b/Documentation/rev-list-options.adoc\n@@ -1096,7 +1096,7 @@ endif::git-rev-list[]\n \tOverrides a previous `--no-walk`.\n endif::git-shortlog[]\n \n-ifndef::git-shortlog[]\n+ifndef::git-shortlog,git-replay[]\n Commit Formatting\n ~~~~~~~~~~~~~~~~~\n \n@@ -1265,4 +1265,4 @@ ifdef::git-rev-list[]\n \tcounts and print the count for equivalent commits separated\n \tby a tab.\n endif::git-rev-list[]\n-endif::git-shortlog[]\n+endif::git-shortlog,git-replay[]\n\nDiff-intervalle contre v1 :\n1: 01a7acfaf8 ! 1: 97ae3ba465 replay: drop rev-list formatting options from manual\n @@ Commit message\n is no exception. Since replay doesn't use the formatting options at all\n (it has its own output format), drop them.\n \n + This is the first time we have needed compound tests [1] for if[n]def in\n + our documentation:\n \n - ## Notes (benknoble/commits) ##\n - I noticed this while reading. It took me a minute to find the\n - Asciidoc reference on multiple attributes [1] since it's not used\n - elsewhere in the rev-list include :) I'm not sure it needs to be\n - included in the commit message, though normally I would, personally.\n + git grep '^ifn\\?def::' Documentation | grep '[,+]'\n \n [1]: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/\n \n + For both ifdef and ifndef, the \",\" takes on the intuitive meaning:\n + - ifdef: if any of the listed attributes are set…\n + - ifndef: unless any of the listed attributes are set\n +\n + (Use \"+\" for \"all\".)\n +\n ## Documentation/git-replay.adoc ##\n @@ Documentation/git-replay.adoc: The default mode can be configured via the `replay.refAction` configuration vari\n \trange should have a single tip, so that it's clear to which tip the\n\nbase-commit: b5c409c40f1595e3e590760c6f14a16b6683e22c\n-- \n2.52.0.rc0.569.g0e1cb519e9.dirty\n\n"},{"id":"534264","messageId":"xmqq5x8w2t3o.fsf@gitster.g","threadId":"64831","inReplyTo":"CALnO6CCaVdJQ2xSPfvxQzVCfPsjbWHhMFUiLoiPQtVn9MeKFOw@mail.gmail.com","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-20T15:37:15Z","receivedAt":"2026-01-20T15:37:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> If I've understood all that correctly, then I have the Python version\n> installed for building Git and it understood the syntax. Given that\n> the Ruby version is newer, I think it should also work against the\n> spec.\n\nWe have CI jobs to catch the differences so hopefully we know soon\nenough if one is so badly broken ;-)\n\nThanks.\n"},{"id":"534301","messageId":"xmqq3440x8da.fsf@gitster.g","threadId":"64831","inReplyTo":"xmqq5x8w2t3o.fsf@gitster.g","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-20T21:49:21Z","receivedAt":"2026-01-20T21:49:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> \"D. Ben Knoble\" writes:\n>\n>> If I've understood all that correctly, then I have the Python version\n>> installed for building Git and it understood the syntax. Given that\n>> the Ruby version is newer, I think it should also work against the\n>> spec.\n>\n> We have CI jobs to catch the differences so hopefully we know soon\n> enough if one is so badly broken ;-)\n>\n> Thanks.\n\nWe didn't have to wait for CI jobs. You can try\n\n\tmake -C Documentation lint-docs\n\nwhich reveals that somebody is not expecting these multiple things\nthere. I think Documentation/lint-gitlink.perl needs updating.\n\n\n\n"},{"id":"534304","messageId":"xmqqy0lrx4l2.fsf@gitster.g","threadId":"64831","inReplyTo":"xmqq3440x8da.fsf@gitster.g","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-20T23:11:05Z","receivedAt":"2026-01-20T23:11:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> \"D. Ben Knoble\" writes:\n>>\n>>> If I've understood all that correctly, then I have the Python version\n>>> installed for building Git and it understood the syntax. Given that\n>>> the Ruby version is newer, I think it should also work against the\n>>> spec.\n>>\n>> We have CI jobs to catch the differences so hopefully we know soon\n>> enough if one is so badly broken ;-)\n>>\n>> Thanks.\n>\n> We didn't have to wait for CI jobs. You can try\n>\n> \tmake -C Documentation lint-docs\n>\n> which reveals that somebody is not expecting these multiple things\n> there. I think Documentation/lint-gitlink.perl needs updating.\n\nPerhaps something like this. Haven't thought things through to spot\nnegative ramifications, though.\n\nThe original comes from f81a574f (doc: test linkgit macros for\nwell-formedness, 2025-08-11); its author Cc'ed for better ideas.\n\n----- >8 -----\nSubject: [PATCH] lint-gitlink: do not get confused by overly long ifdef directive\n\nThe old pattern, when encountered \"ifndef::git-shortlog,git-bar[]\",\ncomplained that \"hortlog,\" (i.e., a substring that is up to 8 bytes\nlong, that comes before \"git-bar[]\") is not \"linkgit:\", which was a\nnonsense.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/lint-gitlink.perl | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex f183a18df2..91621f9db1 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -41,7 +41,7 @@ sub report {\n @ARGV = $to_check;\n while (<>) {\n \tmy $line = $_;\n-\twhile ($line =~ m/(.{,8})((git[-a-z]+|scalar)\\[(\\d)*\\])/g) {\n+\twhile ($line =~ m/([a-z]{,8}:+)((git[-a-z]+|scalar)\\[(\\d)*\\])/g) {\n \t my $pos = pos $line;\n \t my ($macro, $target, $page, $section) = ($1, $2, $3, $4);\n \t\tif ( $macro ne \"linkgit:\" && $macro !~ \"ifn?def::\" && $macro ne \"endif::\" ) {\n-- \n2.53.0-rc0-249-g60c15f3eb8\n\n"},{"id":"534350","messageId":"adfdcc47-470a-4424-9268-31699decee16@free.fr","threadId":"64831","inReplyTo":"xmqqy0lrx4l2.fsf@gitster.g","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2026-01-21T13:27:05Z","receivedAt":"2026-01-21T13:27:28Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 21/01/2026 à 00:11, Junio C Hamano a écrit :\n> Junio C Hamano writes:\n> \n>> Junio C Hamano writes:\n>>\n>>> \"D. Ben Knoble\" writes:\n>>>\n>>>> If I've understood all that correctly, then I have the Python version\n>>>> installed for building Git and it understood the syntax. Given that\n>>>> the Ruby version is newer, I think it should also work against the\n>>>> spec.\n>>>\n>>> We have CI jobs to catch the differences so hopefully we know soon\n>>> enough if one is so badly broken ;-)\n>>>\n>>> Thanks.\n>>\n>> We didn't have to wait for CI jobs. You can try\n>>\n>> \tmake -C Documentation lint-docs\n>>\n>> which reveals that somebody is not expecting these multiple things\n>> there. I think Documentation/lint-gitlink.perl needs updating.\n> \n> Perhaps something like this. Haven't thought things through to spot\n> negative ramifications, though.\n> \n> The original comes from f81a574f (doc: test linkgit macros for\n> well-formedness, 2025-08-11); its author Cc'ed for better ideas.\n> \n\nThe initial motive for this script was to catch malformed linkgit\noccurrences that were present in the docs: stray git-foo[1], without\nthe linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what\nwould come next, the regex was coined very broad, with the assumed risk\nof raising false positives.\n\nThe issue here is in handling the ifdef macros which are block macros\nand are more easily detected as such. I would reject preemtively lines\nwith '^ifn?def::' instead.\n\n\n----- >8 -----\nSubject: [PATCH] lint-gitlink: preemptively ignore all /ifn?def|endif/ macros\n\nInstead of testing if the macro name is ifn?def:: as if it were a inline\nmacro, it is faster and safer to just ignore such block macro lines before\nhand.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/lint-gitlink.perl | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex f183a18df..b5d982e8e 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -41,10 +41,11 @@ sub report {\n @ARGV = $to_check;\n while (<>) {\n \tmy $line = $_;\n+\tnext if $line =~ /^\\s*(ifn?def|endif)::/;\n \twhile ($line =~ m/(.{,8})((git[-a-z]+|scalar)\\[(\\d)*\\])/g) {\n \t my $pos = pos $line;\n \t my ($macro, $target, $page, $section) = ($1, $2, $3, $4);\n-\t\tif ( $macro ne \"linkgit:\" && $macro !~ \"ifn?def::\" && $macro ne \"endif::\" ) {\n+\t\tif ( $macro ne \"linkgit:\" ) {\n \t\t\treport($pos, $line, $target, \"linkgit: macro expected\");\n \t\t}\n \t}\n\n\n\n\n\n"},{"id":"534361","messageId":"xmqq8qdrvsnj.fsf@gitster.g","threadId":"64831","inReplyTo":"adfdcc47-470a-4424-9268-31699decee16@free.fr","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-21T16:26:24Z","receivedAt":"2026-01-21T16:26:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila writes:\n\n>> The original comes from f81a574f (doc: test linkgit macros for\n>> well-formedness, 2025-08-11); its author Cc'ed for better ideas.\n>> \n>\n> The initial motive for this script was to catch malformed linkgit\n> occurrences that were present in the docs: stray git-foo[1], without\n> the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what\n> would come next, the regex was coined very broad, with the assumed risk\n> of raising false positives.\n>\n> The issue here is in handling the ifdef macros which are block macros\n> and are more easily detected as such. I would reject preemtively lines\n> with '^ifn?def::' instead.\n\nYup, that is much cleaner. Thanks!\n\n> ----- >8 -----\n> Subject: [PATCH] lint-gitlink: preemptively ignore all /ifn?def|endif/ macros\n>\n> Instead of testing if the macro name is ifn?def:: as if it were a inline\n> macro, it is faster and safer to just ignore such block macro lines before\n> hand.\n>\n> Signed-off-by: Jean-Noël Avila \n> ---\n> Documentation/lint-gitlink.perl | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\n> index f183a18df..b5d982e8e 100755\n> --- a/Documentation/lint-gitlink.perl\n> +++ b/Documentation/lint-gitlink.perl\n> @@ -41,10 +41,11 @@ sub report {\n> @ARGV = $to_check;\n> while (<>) {\n> \tmy $line = $_;\n> +\tnext if $line =~ /^\\s*(ifn?def|endif)::/;\n> \twhile ($line =~ m/(.{,8})((git[-a-z]+|scalar)\\[(\\d)*\\])/g) {\n> \t my $pos = pos $line;\n> \t my ($macro, $target, $page, $section) = ($1, $2, $3, $4);\n> -\t\tif ( $macro ne \"linkgit:\" && $macro !~ \"ifn?def::\" && $macro ne \"endif::\" ) {\n> +\t\tif ( $macro ne \"linkgit:\" ) {\n> \t\t\treport($pos, $line, $target, \"linkgit: macro expected\");\n> \t\t}\n> \t}\n"},{"id":"534381","messageId":"CALnO6CDGan9k7pfrHcNG09hVLCrvGrJv5=G2O3Wgp4AT2i6reg@mail.gmail.com","threadId":"64831","inReplyTo":"xmqq8qdrvsnj.fsf@gitster.g","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-21T20:03:02Z","receivedAt":"2026-01-21T20:03:14Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Wed, Jan 21, 2026 at 11:26 AM Junio C Hamano wrote:\n>\n> Jean-Noël Avila writes:\n>\n> >> The original comes from f81a574f (doc: test linkgit macros for\n> >> well-formedness, 2025-08-11); its author Cc'ed for better ideas.\n> >>\n> >\n> > The initial motive for this script was to catch malformed linkgit\n> > occurrences that were present in the docs: stray git-foo[1], without\n> > the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what\n> > would come next, the regex was coined very broad, with the assumed risk\n> > of raising false positives.\n> >\n> > The issue here is in handling the ifdef macros which are block macros\n> > and are more easily detected as such. I would reject preemtively lines\n> > with '^ifn?def::' instead.\n>\n> Yup, that is much cleaner. Thanks!\n\nThanks all. I always forget the documentation lint target. I'll try to\nsend a v3 this weekend, but travelling, so responses may be delayed.\n"},{"id":"534720","messageId":"CALnO6CC9HZw96EHVpLyaekSUe744zTwHzN0ZH2UhW42sxUDU3A@mail.gmail.com","threadId":"64831","inReplyTo":"CALnO6CDGan9k7pfrHcNG09hVLCrvGrJv5=G2O3Wgp4AT2i6reg@mail.gmail.com","subject":"Re: [PATCH] replay: drop rev-list formatting options from manual","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-27T18:48:44Z","receivedAt":"2026-01-27T18:48:56Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Wed, Jan 21, 2026 at 3:03 PM D. Ben Knoble\n wrote:\n>\n> On Wed, Jan 21, 2026 at 11:26 AM Junio C Hamano wrote:\n> >\n> > Jean-Noël Avila writes:\n> >\n> > >> The original comes from f81a574f (doc: test linkgit macros for\n> > >> well-formedness, 2025-08-11); its author Cc'ed for better ideas.\n> > >>\n> > >\n> > > The initial motive for this script was to catch malformed linkgit\n> > > occurrences that were present in the docs: stray git-foo[1], without\n> > > the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what\n> > > would come next, the regex was coined very broad, with the assumed risk\n> > > of raising false positives.\n> > >\n> > > The issue here is in handling the ifdef macros which are block macros\n> > > and are more easily detected as such. I would reject preemtively lines\n> > > with '^ifn?def::' instead.\n> >\n> > Yup, that is much cleaner. Thanks!\n>\n> Thanks all. I always forget the documentation lint target. I'll try to\n> send a v3 this weekend, but travelling, so responses may be delayed.\n\nLooks like this was queued and merged. Thanks both!\n"}]}