[PATCH 0/3] doc: config: fix AsciiDoc glitches

[PATCH 0/3] doc: config: fix AsciiDoc glitches

[Tuomas Ahola]

Fix various markup shortcomings in git-config(1).

Based on 29bd7ed512 (The second batch, 2026-05-12).

Tuomas Ahola (3):
  doc: config: terminate runaway lists
  doc: config/sideband: fix typo in adoc markup
  doc: git-config: escape erroneous adoc markup

 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/config/sideband.adoc | 2 +-
 Documentation/git-config.adoc      | 6 ++++--
 5 files changed, 12 insertions(+), 4 deletions(-)


base-commit: 29bd7ed5127255713c1ac2f43b7c6f257d7b4594
-- 
2.30.2

[PATCH 1/3] doc: config: terminate runaway lists

[Tuomas Ahola]

There are many places in git-config(1) where paragraphs that should
logically come after a list are instead appended to the last item of
the list.  This is a well-documented quirk of AsciiDoc, and can be
mitigated by enclosing the list in an open block:

	--
	* first item
	* last item
	--
	+
	New paragraph after the list.

Fix the issue accordingly.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/git-config.adoc      | 2 ++
 4 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/config.adoc b/Documentation/config.adoc
index dcea3c0c15..fc48c1c461 100644
--- a/Documentation/config.adoc
+++ b/Documentation/config.adoc
@@ -276,13 +276,15 @@ boolean::
        When a variable is said to take a boolean value, many
        synonyms are accepted for 'true' and 'false'; these are all
        case-insensitive.
-
++
+--
 	true;; Boolean true literals are `yes`, `on`, `true`,
 		and `1`.  Also, a variable defined without `= <value>`
 		is taken as true.
 
 	false;; Boolean false literals are `no`, `off`, `false`,
 		`0` and the empty string.
+--
 +
 When converting a value to its canonical form using the `--type=bool` type
 specifier, 'git config' will ensure that the output is "true" or
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index b0fa43b839..39af63dcb8 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -63,11 +63,13 @@ If one of these field names (e.g., "token") is being checked for an
 advertised promisor remote (e.g., "foo"), three conditions must be met
 for the check of this specific field to pass:
 +
+--
 1. The corresponding local configuration (e.g., `remote.foo.token`)
    must be set.
 2. The server must advertise the "token" field for remote "foo".
 3. The value of the locally configured `remote.foo.token` must exactly
    match the value advertised by the server for the "token" field.
+--
 +
 If any of these conditions is not met for any field name listed in
 `promisor.checkFields`, the advertised remote "foo" is rejected.
diff --git a/Documentation/config/safe.adoc b/Documentation/config/safe.adoc
index 2d45c98b12..5ae4476b24 100644
--- a/Documentation/config/safe.adoc
+++ b/Documentation/config/safe.adoc
@@ -2,10 +2,12 @@ safe.bareRepository::
 	Specifies which bare repositories Git will work with. The currently
 	supported values are:
 +
+--
 * `all`: Git works with all bare repositories. This is the default.
 * `explicit`: Git only works with bare repositories specified via
   the top-level `--git-dir` command-line option, or the `GIT_DIR`
   environment variable (see linkgit:git[1]).
+--
 +
 If you do not use bare repositories in your workflow, then it may be
 beneficial to set `safe.bareRepository` to `explicit` in your global
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 00545b2054..8439ce97df 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -221,6 +221,7 @@ Use `--no-value` to unset _<pattern>_.
 +
 Valid `<type>`'s include:
 +
+--
 - 'bool': canonicalize values `true`, `yes`, `on`, and positive
   numbers as "true", and values `false`, `no`, `off` and `0` as
   "false".
@@ -239,6 +240,7 @@ Valid `<type>`'s include:
   escape sequence. When setting a value, a sanity-check is performed to ensure
   that the given value is canonicalize-able as an ANSI color, but it is written
   as-is.
+--
 +
 If the command is in `list` mode, then the `--type <type>` argument will apply
 to each listed config value. If the value does not successfully parse in that
-- 
2.30.2

[PATCH 2/3] doc: config/sideband: fix typo in adoc markup

[Tuomas Ahola]

Fix a simple typo in AsciiDoc markup.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/config/sideband.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/config/sideband.adoc b/Documentation/config/sideband.adoc
index 96fade7f5f..06de0d5c07 100644
--- a/Documentation/config/sideband.adoc
+++ b/Documentation/config/sideband.adoc
@@ -9,7 +9,7 @@ sideband.allowControlCharacters::
 	`color`::
 		Allow ANSI color sequences, line feeds and horizontal tabs,
 		but mask all other control characters. This is the default.
-	`cursor:`:
+	`cursor`::
 		Allow control sequences that move the cursor. This is
 		disabled by default.
 	`erase`::
-- 
2.30.2

Re: [PATCH 2/3] doc: config/sideband: fix typo in adoc markup

[Kristoffer Haugsbakk]

> doc: config/sideband: fix typo in adoc markup

You might be able to be more precise while using the same amount of
words or less. Like:

   _: fix description list delimiter

On Wed, Jun 10, 2026, at 20:51, Tuomas Ahola wrote:
> Fix a simple typo in AsciiDoc markup.

The subject of the commit might be enough here.

>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
>  Documentation/config/sideband.adoc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>[snip]
> @@ -9,7 +9,7 @@ sideband.allowControlCharacters::
>  	`color`::
>  		Allow ANSI color sequences, line feeds and horizontal tabs,
>  		but mask all other control characters. This is the default.
> -	`cursor:`:
> +	`cursor`::

Nice find!

>  		Allow control sequences that move the cursor. This is
>  		disabled by default.
>  	`erase`::
> --
> 2.30.2

[PATCH 3/3] doc: git-config: escape erroneous adoc markup

[Tuomas Ahola]

Paired octothorpes are used in AsciiDoc to mark highlighted text,
<mark> being the equivalent HTML tag.  To use the symbol as a literal
character, it can be escaped with a backslash.

Do so in git-config.adoc.

While at it, tweak the text slightly to make it scan better.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/git-config.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 8439ce97df..708e88cdeb 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -119,10 +119,10 @@ OPTIONS
 	Append a comment at the end of new or modified lines.
 +
 If _<message>_ begins with one or more whitespaces followed
-by "#", it is used as-is.  If it begins with "#", a space is
+by "\#", it is used as-is.  If it begins with "#", a space is
 prepended before it is used.  Otherwise, a string " # " (a
 space followed by a hash followed by a space) is prepended
-to it.  And the resulting string is placed immediately after
+to it.  The resulting string is placed immediately after
 the value defined for the variable.  The _<message>_ must
 not contain linefeed characters (no multi-line comments are
 permitted).
-- 
2.30.2

Re: [PATCH 3/3] doc: git-config: escape erroneous adoc markup

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

> Paired octothorpes are used in AsciiDoc to mark highlighted text,
> <mark> being the equivalent HTML tag.  To use the symbol as a literal
> character, it can be escaped with a backslash.
>
> Do so in git-config.adoc.
>
> While at it, tweak the text slightly to make it scan better.
>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
>  Documentation/git-config.adoc | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Thanks.  

What we see in
https://git-scm.com/docs/git-config#Documentation/git-config.txt---commentmessage
is rather embarrasing.  This would be a vast improvement ;-)

> diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
> index 8439ce97df..708e88cdeb 100644
> --- a/Documentation/git-config.adoc
> +++ b/Documentation/git-config.adoc
> @@ -119,10 +119,10 @@ OPTIONS
>  	Append a comment at the end of new or modified lines.
>  +
>  If _<message>_ begins with one or more whitespaces followed
> -by "#", it is used as-is.  If it begins with "#", a space is
> +by "\#", it is used as-is.  If it begins with "#", a space is
>  prepended before it is used.  Otherwise, a string " # " (a
>  space followed by a hash followed by a space) is prepended
> -to it.  And the resulting string is placed immediately after
> +to it.  The resulting string is placed immediately after
>  the value defined for the variable.  The _<message>_ must
>  not contain linefeed characters (no multi-line comments are
>  permitted).

Re: [PATCH 3/3] doc: git-config: escape erroneous adoc markup

[Junio C Hamano]

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

> Thanks.  
>
> What we see in
> https://git-scm.com/docs/git-config#Documentation/git-config.txt---commentmessage
> is rather embarrasing.  This would be a vast improvement ;-)
>
>> diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
>> index 8439ce97df..708e88cdeb 100644
>> --- a/Documentation/git-config.adoc
>> +++ b/Documentation/git-config.adoc
>> @@ -119,10 +119,10 @@ OPTIONS
>>  	Append a comment at the end of new or modified lines.
>>  +
>>  If _<message>_ begins with one or more whitespaces followed
>> -by "#", it is used as-is.  If it begins with "#", a space is
>> +by "\#", it is used as-is.  If it begins with "#", a space is
>>  prepended before it is used.  Otherwise, a string " # " (a

With this change, I wonder if this '#' on the next line gets paired
as the closing element that corresponds to the second one on the
previous line, which is not quoted hence can be taken as the opening
element?  Even if the one on the second line does not get taken as a
closing element now, if a future change adds some word with '#' that
does, the second "#" on the line left unquoted by this patch would
then require quoting, no?  IOW, would it be better to do this

>> -by "#", it is used as-is.  If it begins with "#", a space is
>> +by "\#", it is used as-is.  If it begins with "\#", a space is

so that we do not have to worry about "special cases" where it
becomes unnecessary to quote "#"s?


>>  space followed by a hash followed by a space) is prepended
>> -to it.  And the resulting string is placed immediately after
>> +to it.  The resulting string is placed immediately after
>>  the value defined for the variable.  The _<message>_ must
>>  not contain linefeed characters (no multi-line comments are
>>  permitted).

[PATCH v2 0/3] doc: config: fix AsciiDoc glitches

[Tuomas Ahola]

Fix various markup shortcomings in git-config(1).

Based on 29bd7ed512 (The second batch, 2026-05-12).

Tuomas Ahola (3):
  doc: config: terminate runaway lists
  doc: config/sideband: fix description list delimiter
  doc: git-config: escape erroneous highlight markup

 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/config/sideband.adoc | 2 +-
 Documentation/git-config.adoc      | 6 ++++--
 5 files changed, 12 insertions(+), 4 deletions(-)

Intervall-diff mot v1:
1:  224303c555 = 1:  c9131b23fd doc: config: terminate runaway lists
2:  a7e6b82c97 ! 2:  ca65211ea4 doc: config/sideband: fix typo in adoc markup
    @@ Metadata
     Author: Tuomas Ahola <taahol@utu.fi>
     
      ## Commit message ##
    -    doc: config/sideband: fix typo in adoc markup
    -
    -    Fix a simple typo in AsciiDoc markup.
    +    doc: config/sideband: fix description list delimiter
     
         Signed-off-by: Tuomas Ahola <taahol@utu.fi>
     
3:  7d0916a874 ! 3:  0341a4bde9 doc: git-config: escape erroneous adoc markup
    @@ Metadata
     Author: Tuomas Ahola <taahol@utu.fi>
     
      ## Commit message ##
    -    doc: git-config: escape erroneous adoc markup
    +    doc: git-config: escape erroneous highlight markup
     
         Paired octothorpes are used in AsciiDoc to mark highlighted text,
         <mark> being the equivalent HTML tag.  To use the symbol as a literal
    @@ Documentation/git-config.adoc: OPTIONS
      +
      If _<message>_ begins with one or more whitespaces followed
     -by "#", it is used as-is.  If it begins with "#", a space is
    -+by "\#", it is used as-is.  If it begins with "#", a space is
    ++by "\#", it is used as-is.  If it begins with "\#", a space is
      prepended before it is used.  Otherwise, a string " # " (a
      space followed by a hash followed by a space) is prepended
     -to it.  And the resulting string is placed immediately after

base-commit: 29bd7ed5127255713c1ac2f43b7c6f257d7b4594
-- 
2.30.2

[PATCH v2 1/3] doc: config: terminate runaway lists

[Tuomas Ahola]

There are many places in git-config(1) where paragraphs that should
logically come after a list are instead appended to the last item of
the list.  This is a well-documented quirk of AsciiDoc, and can be
mitigated by enclosing the list in an open block:

	--
	* first item
	* last item
	--
	+
	New paragraph after the list.

Fix the issue accordingly.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/git-config.adoc      | 2 ++
 4 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/config.adoc b/Documentation/config.adoc
index dcea3c0c15..fc48c1c461 100644
--- a/Documentation/config.adoc
+++ b/Documentation/config.adoc
@@ -276,13 +276,15 @@ boolean::
        When a variable is said to take a boolean value, many
        synonyms are accepted for 'true' and 'false'; these are all
        case-insensitive.
-
++
+--
 	true;; Boolean true literals are `yes`, `on`, `true`,
 		and `1`.  Also, a variable defined without `= <value>`
 		is taken as true.
 
 	false;; Boolean false literals are `no`, `off`, `false`,
 		`0` and the empty string.
+--
 +
 When converting a value to its canonical form using the `--type=bool` type
 specifier, 'git config' will ensure that the output is "true" or
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index b0fa43b839..39af63dcb8 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -63,11 +63,13 @@ If one of these field names (e.g., "token") is being checked for an
 advertised promisor remote (e.g., "foo"), three conditions must be met
 for the check of this specific field to pass:
 +
+--
 1. The corresponding local configuration (e.g., `remote.foo.token`)
    must be set.
 2. The server must advertise the "token" field for remote "foo".
 3. The value of the locally configured `remote.foo.token` must exactly
    match the value advertised by the server for the "token" field.
+--
 +
 If any of these conditions is not met for any field name listed in
 `promisor.checkFields`, the advertised remote "foo" is rejected.
diff --git a/Documentation/config/safe.adoc b/Documentation/config/safe.adoc
index 2d45c98b12..5ae4476b24 100644
--- a/Documentation/config/safe.adoc
+++ b/Documentation/config/safe.adoc
@@ -2,10 +2,12 @@ safe.bareRepository::
 	Specifies which bare repositories Git will work with. The currently
 	supported values are:
 +
+--
 * `all`: Git works with all bare repositories. This is the default.
 * `explicit`: Git only works with bare repositories specified via
   the top-level `--git-dir` command-line option, or the `GIT_DIR`
   environment variable (see linkgit:git[1]).
+--
 +
 If you do not use bare repositories in your workflow, then it may be
 beneficial to set `safe.bareRepository` to `explicit` in your global
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 00545b2054..8439ce97df 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -221,6 +221,7 @@ Use `--no-value` to unset _<pattern>_.
 +
 Valid `<type>`'s include:
 +
+--
 - 'bool': canonicalize values `true`, `yes`, `on`, and positive
   numbers as "true", and values `false`, `no`, `off` and `0` as
   "false".
@@ -239,6 +240,7 @@ Valid `<type>`'s include:
   escape sequence. When setting a value, a sanity-check is performed to ensure
   that the given value is canonicalize-able as an ANSI color, but it is written
   as-is.
+--
 +
 If the command is in `list` mode, then the `--type <type>` argument will apply
 to each listed config value. If the value does not successfully parse in that
-- 
2.30.2

Re: [PATCH v2 1/3] doc: config: terminate runaway lists

[Jeff King]

On Thu, Jun 11, 2026 at 01:55:11AM +0300, Tuomas Ahola wrote:

> There are many places in git-config(1) where paragraphs that should
> logically come after a list are instead appended to the last item of
> the list.  This is a well-documented quirk of AsciiDoc, and can be
> mitigated by enclosing the list in an open block:
> 
> 	--
> 	* first item
> 	* last item
> 	--
> 	+
> 	New paragraph after the list.
> 
> Fix the issue accordingly.

Makes sense. We've run into problems in the past where adding "--"
doesn't quite work, because we are already inside a "--" (and IIRC the
behavior is not always completely predictable). But I double-checked
these cases, and we are not already in a "--". So we should be good
here.

-Peff

[PATCH v2 2/3] doc: config/sideband: fix description list delimiter

[Tuomas Ahola]

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/config/sideband.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/config/sideband.adoc b/Documentation/config/sideband.adoc
index 96fade7f5f..06de0d5c07 100644
--- a/Documentation/config/sideband.adoc
+++ b/Documentation/config/sideband.adoc
@@ -9,7 +9,7 @@ sideband.allowControlCharacters::
 	`color`::
 		Allow ANSI color sequences, line feeds and horizontal tabs,
 		but mask all other control characters. This is the default.
-	`cursor:`:
+	`cursor`::
 		Allow control sequences that move the cursor. This is
 		disabled by default.
 	`erase`::
-- 
2.30.2

[PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Tuomas Ahola]

Paired octothorpes are used in AsciiDoc to mark highlighted text,
<mark> being the equivalent HTML tag.  To use the symbol as a literal
character, it can be escaped with a backslash.

Do so in git-config.adoc.

While at it, tweak the text slightly to make it scan better.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/git-config.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 8439ce97df..e4af6cac68 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -119,10 +119,10 @@ OPTIONS
 	Append a comment at the end of new or modified lines.
 +
 If _<message>_ begins with one or more whitespaces followed
-by "#", it is used as-is.  If it begins with "#", a space is
+by "\#", it is used as-is.  If it begins with "\#", a space is
 prepended before it is used.  Otherwise, a string " # " (a
 space followed by a hash followed by a space) is prepended
-to it.  And the resulting string is placed immediately after
+to it.  The resulting string is placed immediately after
 the value defined for the variable.  The _<message>_ must
 not contain linefeed characters (no multi-line comments are
 permitted).
-- 
2.30.2

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Jeff King]

On Thu, Jun 11, 2026 at 01:55:13AM +0300, Tuomas Ahola wrote:

> Paired octothorpes are used in AsciiDoc to mark highlighted text,
> <mark> being the equivalent HTML tag.  To use the symbol as a literal
> character, it can be escaped with a backslash.
> 
> Do so in git-config.adoc.

I think this works OK, but in general I think most uses of backslash for
metacharacters should consider using literal backticks. That shields it
from the special meaning for asciidoc, but also will render it
differently for the user (usually with a typewriter font, which becomes
bold in roff output).

Though curiously the case of `#` in git-fast-import seems not to get
marked as <code> in the html output (even though the nearby `LF` does).
I wonder if there is some special treatment of `#` or something.

>  If _<message>_ begins with one or more whitespaces followed
> -by "#", it is used as-is.  If it begins with "#", a space is
> +by "\#", it is used as-is.  If it begins with "\#", a space is
>  prepended before it is used.  Otherwise, a string " # " (a
>  space followed by a hash followed by a space) is prepended

I saw the comment on round 1 about this second "#" on the line. But
while we are here, should we be doing the one in the context, too?

-Peff

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Jeff King]

On Thu, Jun 11, 2026 at 02:11:57AM -0400, Jeff King wrote:

> Though curiously the case of `#` in git-fast-import seems not to get
> marked as <code> in the html output (even though the nearby `LF` does).
> I wonder if there is some special treatment of `#` or something.

Ah, weird, it has to do with our config file.

If I do this (not in the git repository):

  echo 'This is a literal `#` symbol.' >foo.adoc
  asciidoc foo.adoc
  grep -i symbol foo.html

then I get <code> markers, like:

  <div class="paragraph"><p>This is a literal <code>#</code> symbol.</p></div>

But if I build with:

  asciidoc -f path/to/git/Documentation/asciidoc.conf foo.adoc

then the grep shows:

  <div class="paragraph"><p>This is a literal # symbol.</p></div>

Looks like it is due to our [literal-inlinemacro] definition, which
comes from 974cdca345 (doc: introduce a synopsis typesetting,
2024-09-24). I think this might have been an unintended side effect.
+cc the author of that commit.

For the purposes of your series, I think we can ignore any issues with
[literal-inlinemacro] for the moment, and decide on "\" versus ``
depending on which we prefer.

-Peff

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Jeff King]

[and naturally I forgot to cc Jean-Noël; resending, sorry for the noise]

On Thu, Jun 11, 2026 at 02:24:23AM -0400, Jeff King wrote:

> On Thu, Jun 11, 2026 at 02:11:57AM -0400, Jeff King wrote:
> 
> > Though curiously the case of `#` in git-fast-import seems not to get
> > marked as <code> in the html output (even though the nearby `LF` does).
> > I wonder if there is some special treatment of `#` or something.
> 
> Ah, weird, it has to do with our config file.
> 
> If I do this (not in the git repository):
> 
>   echo 'This is a literal `#` symbol.' >foo.adoc
>   asciidoc foo.adoc
>   grep -i symbol foo.html
> 
> then I get <code> markers, like:
> 
>   <div class="paragraph"><p>This is a literal <code>#</code> symbol.</p></div>
> 
> But if I build with:
> 
>   asciidoc -f path/to/git/Documentation/asciidoc.conf foo.adoc
> 
> then the grep shows:
> 
>   <div class="paragraph"><p>This is a literal # symbol.</p></div>
> 
> Looks like it is due to our [literal-inlinemacro] definition, which
> comes from 974cdca345 (doc: introduce a synopsis typesetting,
> 2024-09-24). I think this might have been an unintended side effect.
> +cc the author of that commit.
> 
> For the purposes of your series, I think we can ignore any issues with
> [literal-inlinemacro] for the moment, and decide on "\" versus ``
> depending on which we prefer.
> 
> -Peff

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Tuomas Ahola]

Jeff King <peff@peff.net> wrote:

> On Thu, Jun 11, 2026 at 01:55:13AM +0300, Tuomas Ahola wrote:
> 
> > Paired octothorpes are used in AsciiDoc to mark highlighted text,
> > <mark> being the equivalent HTML tag.  To use the symbol as a literal
> > character, it can be escaped with a backslash.
> > 
> > Do so in git-config.adoc.
> 
> I think this works OK, but in general I think most uses of backslash for
> metacharacters should consider using literal backticks. That shields it
> from the special meaning for asciidoc, but also will render it
> differently for the user (usually with a typewriter font, which becomes
> bold in roff output).
> 
> Though curiously the case of `#` in git-fast-import seems not to get
> marked as <code> in the html output (even though the nearby `LF` does).
> I wonder if there is some special treatment of `#` or something.
> 
> >  If _<message>_ begins with one or more whitespaces followed
> > -by "#", it is used as-is.  If it begins with "#", a space is
> > +by "\#", it is used as-is.  If it begins with "\#", a space is
> >  prepended before it is used.  Otherwise, a string " # " (a
> >  space followed by a hash followed by a space) is prepended
> 
> I saw the comment on round 1 about this second "#" on the line. But
> while we are here, should we be doing the one in the context, too?
> 
> -Peff

It seems adding that second backslash was already too much, as doc-diff (which
I neglected to run before submitting V2) shows:

```
$ ./doc-diff V1 V2
 
            If <message> begins with one or more whitespaces followed by "#",
-           it is used as-is. If it begins with "#", a space is prepended
+           it is used as-is. If it begins with "\#", a space is prepended
            before it is used. Otherwise, a string " # " (a space followed by a
            hash followed by a space) is prepended to it. The resulting string
            is placed immediately after the value defined for the variable. The
```

--Tuomas

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Jeff King]

On Thu, Jun 11, 2026 at 11:02:42AM +0300, Tuomas Ahola wrote:

> > >  If _<message>_ begins with one or more whitespaces followed
> > > -by "#", it is used as-is.  If it begins with "#", a space is
> > > +by "\#", it is used as-is.  If it begins with "\#", a space is
> > >  prepended before it is used.  Otherwise, a string " # " (a
> > >  space followed by a hash followed by a space) is prepended
> > 
> > I saw the comment on round 1 about this second "#" on the line. But
> > while we are here, should we be doing the one in the context, too?
> > 
> > -Peff
> 
> It seems adding that second backslash was already too much, as doc-diff (which
> I neglected to run before submitting V2) shows:
> 
> ```
> $ ./doc-diff V1 V2
>  
>             If <message> begins with one or more whitespaces followed by "#",
> -           it is used as-is. If it begins with "#", a space is prepended
> +           it is used as-is. If it begins with "\#", a space is prepended
>             before it is used. Otherwise, a string " # " (a space followed by a
>             hash followed by a space) is prepended to it. The resulting string
>             is placed immediately after the value defined for the variable. The
> ```

Heh, it would not be the first time I am baffled by asciidoc's parsing. :)

Adding a backslash to the third instance "fixes" the second one to me,
but I wouldn't want to rely on that (plus it breaks the third instance).

Using backticks does work, though it always opens a typographical
question. When reading the source, you see `#`, so you get a punctuation
delimiter but no typographical one. In the rendered output, you'll see
it in a typewriter font (assuming we fix the config issue), but we'd
lose the visible punctuation. I could live with that.

But for " # ", it gets weirder. We need punctuation to call out the
spaces, but what should happen to the quotes? They are not really part
of the literal string, so should they go inside or outside the
backticks? I think it may be a moot point as "` # `" is not parsed as
you might hope by asciidoc. Doing `" # "` does work, and is probably OK
enough here.

-Peff

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Tuomas Ahola]

Jeff King <peff@peff.net> wrote:

> On Thu, Jun 11, 2026 at 11:02:42AM +0300, Tuomas Ahola wrote:
> 
> > > >  If _<message>_ begins with one or more whitespaces followed
> > > > -by "#", it is used as-is.  If it begins with "#", a space is
> > > > +by "\#", it is used as-is.  If it begins with "\#", a space is
> > > >  prepended before it is used.  Otherwise, a string " # " (a
> > > >  space followed by a hash followed by a space) is prepended
> > > 
> > > I saw the comment on round 1 about this second "#" on the line. But
> > > while we are here, should we be doing the one in the context, too?
> > > 
> > > -Peff
> > 
> > It seems adding that second backslash was already too much, as doc-diff (which
> > I neglected to run before submitting V2) shows:
> > 
> > ```
> > $ ./doc-diff V1 V2
> >  
> >             If <message> begins with one or more whitespaces followed by "#",
> > -           it is used as-is. If it begins with "#", a space is prepended
> > +           it is used as-is. If it begins with "\#", a space is prepended
> >             before it is used. Otherwise, a string " # " (a space followed by a
> >             hash followed by a space) is prepended to it. The resulting string
> >             is placed immediately after the value defined for the variable. The
> > ```
> 
> Heh, it would not be the first time I am baffled by asciidoc's parsing. :)
> 
> Adding a backslash to the third instance "fixes" the second one to me,
> but I wouldn't want to rely on that (plus it breaks the third instance).
> 
> Using backticks does work, though it always opens a typographical
> question. When reading the source, you see `#`, so you get a punctuation
> delimiter but no typographical one. In the rendered output, you'll see
> it in a typewriter font (assuming we fix the config issue), but we'd
> lose the visible punctuation. I could live with that.
> 
> But for " # ", it gets weirder. We need punctuation to call out the
> spaces, but what should happen to the quotes? They are not really part
> of the literal string, so should they go inside or outside the
> backticks? I think it may be a moot point as "` # `" is not parsed as
> you might hope by asciidoc. Doing `" # "` does work, and is probably OK
> enough here.
> 
> -Peff

Okay, I'll change those to `#` and `" # "`.  That seems to be the best,
or the least bad option right now. :-)

--Tuomas

Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Using backticks does work, though it always opens a typographical
> question. When reading the source, you see `#`, so you get a punctuation
> delimiter but no typographical one. In the rendered output, you'll see
> it in a typewriter font (assuming we fix the config issue), but we'd
> lose the visible punctuation. I could live with that.
> ...
> you might hope by asciidoc. Doing `" # "` does work, and is probably OK
> enough here.

Yucky, yucky, asciidoc.  I think these literal notation `#` would be
a good way forward, given the constraints.

Thanks.

[PATCH v3 0/3] doc: config: fix AsciiDoc glitches

[Tuomas Ahola]

Fix various markup shortcomings in git-config(1).

Based on 29bd7ed512 (The second batch, 2026-05-12).

Tuomas Ahola (3):
  doc: config: terminate runaway lists
  doc: config/sideband: fix description list delimiter
  doc: git-config: escape erroneous highlight markup

 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/config/sideband.adoc | 2 +-
 Documentation/git-config.adoc      | 8 +++++---
 5 files changed, 13 insertions(+), 5 deletions(-)

Intervall-diff mot v2:
-:  ---------- > 1:  c9131b23fd doc: config: terminate runaway lists
-:  ---------- > 2:  ca65211ea4 doc: config/sideband: fix description list delimiter
1:  0341a4bde9 ! 3:  e2d0cc8218 doc: git-config: escape erroneous highlight markup
    @@ Commit message
     
         Paired octothorpes are used in AsciiDoc to mark highlighted text,
         <mark> being the equivalent HTML tag.  To use the symbol as a literal
    -    character, it can be escaped with a backslash.
    +    character, it can be escaped with backticks.
     
         Do so in git-config.adoc.
     
    @@ Documentation/git-config.adoc: OPTIONS
      +
      If _<message>_ begins with one or more whitespaces followed
     -by "#", it is used as-is.  If it begins with "#", a space is
    -+by "\#", it is used as-is.  If it begins with "\#", a space is
    - prepended before it is used.  Otherwise, a string " # " (a
    +-prepended before it is used.  Otherwise, a string " # " (a
    ++by `#`, it is used as-is.  If it begins with `#`, a space is
    ++prepended before it is used.  Otherwise, a string `" # "` (a
      space followed by a hash followed by a space) is prepended
     -to it.  And the resulting string is placed immediately after
     +to it.  The resulting string is placed immediately after

base-commit: 29bd7ed5127255713c1ac2f43b7c6f257d7b4594
-- 
2.30.2

[PATCH v3 1/3] doc: config: terminate runaway lists

[Tuomas Ahola]

There are many places in git-config(1) where paragraphs that should
logically come after a list are instead appended to the last item of
the list.  This is a well-documented quirk of AsciiDoc, and can be
mitigated by enclosing the list in an open block:

	--
	* first item
	* last item
	--
	+
	New paragraph after the list.

Fix the issue accordingly.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---

Notes (doc-diff):
    diff --git a/29bd7ed5127255713c1ac2f43b7c6f257d7b4594/home/taahol/share/man/man1/git-config.1 b/c9131b23fd1c8611fde5664fcfd4e6d5283648ad/home/taahol/share/man/man1/git-config.1
    index 326782e637..d915897ca5 100644
    --- a/29bd7ed5127255713c1ac2f43b7c6f257d7b4594/home/taahol/share/man/man1/git-config.1
    +++ b/c9131b23fd1c8611fde5664fcfd4e6d5283648ad/home/taahol/share/man/man1/git-config.1
    @@ -234,10 +234,10 @@ OPTIONS
                    sanity-check is performed to ensure that the given value is
                    canonicalize-able as an ANSI color, but it is written as-is.
    
    -               If the command is in list mode, then the --type <type> argument
    -               will apply to each listed config value. If the value does not
    -               successfully parse in that format, then it will be omitted from
    -               the list.
    +           If the command is in list mode, then the --type <type> argument
    +           will apply to each listed config value. If the value does not
    +           successfully parse in that format, then it will be omitted from the
    +           list.
    
            --bool, --int, --bool-or-int, --path, --expiry-date
                Historical options for selecting a type specifier. Prefer instead
    @@ -841,9 +841,9 @@ CONFIGURATION FILE
                    Boolean false literals are no, off, false, 0 and the empty
                    string.
    
    -               When converting a value to its canonical form using the
    -               --type=bool type specifier, git config will ensure that the
    -               output is "true" or "false" (spelled in lowercase).
    +           When converting a value to its canonical form using the --type=bool
    +           type specifier, git config will ensure that the output is "true" or
    +           "false" (spelled in lowercase).
    
            integer
                The value for many variables that specify various sizes can be
    @@ -5869,28 +5869,26 @@ CONFIGURATION FILE
                    exactly match the value advertised by the server for the
                    "token" field.
    
    -               If any of these conditions is not met for any field name listed
    -               in promisor.checkFields, the advertised remote "foo" is
    -               rejected.
    +           If any of these conditions is not met for any field name listed in
    +           promisor.checkFields, the advertised remote "foo" is rejected.
    
    -               For the "partialCloneFilter" field, this allows the client to
    -               ensure that the server’s filter matches what it expects
    -               locally, preventing inconsistencies in filtering behavior. For
    -               the "token" field, this can be used to verify that
    -               authentication credentials match expected values.
    +           For the "partialCloneFilter" field, this allows the client to
    +           ensure that the server’s filter matches what it expects locally,
    +           preventing inconsistencies in filtering behavior. For the "token"
    +           field, this can be used to verify that authentication credentials
    +           match expected values.
    
    -               Field values are compared case-sensitively.
    +           Field values are compared case-sensitively.
    
    -               The "name" and "url" fields are always checked according to the
    -               promisor.acceptFromServer policy, independently of this
    -               setting.
    +           The "name" and "url" fields are always checked according to the
    +           promisor.acceptFromServer policy, independently of this setting.
    
    -               The field names and values should be passed by the server
    -               through the "promisor-remote" capability by using the
    -               promisor.sendFields config variable. The fields are checked
    -               only if the promisor.acceptFromServer config variable is not
    -               set to "None". If set to "None", this config variable has no
    -               effect. See gitprotocol-v2(5).
    +           The field names and values should be passed by the server through
    +           the "promisor-remote" capability by using the promisor.sendFields
    +           config variable. The fields are checked only if the
    +           promisor.acceptFromServer config variable is not set to "None". If
    +           set to "None", this config variable has no effect. See gitprotocol-
    +           v2(5).
    
            promisor.storeFields
                A comma or space separated list of additional remote related field
    @@ -6630,15 +6628,15 @@ CONFIGURATION FILE
                    the top-level --git-dir command-line option, or the GIT_DIR
                    environment variable (see git(1)).
    
    -               If you do not use bare repositories in your workflow, then it
    -               may be beneficial to set safe.bareRepository to explicit in
    -               your global config. This will protect you from attacks that
    -               involve cloning a repository that contains a bare repository
    -               and running a Git command within that directory.
    +           If you do not use bare repositories in your workflow, then it may
    +           be beneficial to set safe.bareRepository to explicit in your global
    +           config. This will protect you from attacks that involve cloning a
    +           repository that contains a bare repository and running a Git
    +           command within that directory.
    
    -               This config setting is only respected in protected
    -               configuration (see the section called “SCOPES”). This prevents
    -               untrusted repositories from tampering with this value.
    +           This config setting is only respected in protected configuration
    +           (see the section called “SCOPES”). This prevents untrusted
    +           repositories from tampering with this value.
    
            safe.directory
                These config entries specify Git-tracked directories that are

 Documentation/config.adoc          | 4 +++-
 Documentation/config/promisor.adoc | 2 ++
 Documentation/config/safe.adoc     | 2 ++
 Documentation/git-config.adoc      | 2 ++
 4 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/config.adoc b/Documentation/config.adoc
index dcea3c0c15..fc48c1c461 100644
--- a/Documentation/config.adoc
+++ b/Documentation/config.adoc
@@ -276,13 +276,15 @@ boolean::
        When a variable is said to take a boolean value, many
        synonyms are accepted for 'true' and 'false'; these are all
        case-insensitive.
-
++
+--
 	true;; Boolean true literals are `yes`, `on`, `true`,
 		and `1`.  Also, a variable defined without `= <value>`
 		is taken as true.
 
 	false;; Boolean false literals are `no`, `off`, `false`,
 		`0` and the empty string.
+--
 +
 When converting a value to its canonical form using the `--type=bool` type
 specifier, 'git config' will ensure that the output is "true" or
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index b0fa43b839..39af63dcb8 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -63,11 +63,13 @@ If one of these field names (e.g., "token") is being checked for an
 advertised promisor remote (e.g., "foo"), three conditions must be met
 for the check of this specific field to pass:
 +
+--
 1. The corresponding local configuration (e.g., `remote.foo.token`)
    must be set.
 2. The server must advertise the "token" field for remote "foo".
 3. The value of the locally configured `remote.foo.token` must exactly
    match the value advertised by the server for the "token" field.
+--
 +
 If any of these conditions is not met for any field name listed in
 `promisor.checkFields`, the advertised remote "foo" is rejected.
diff --git a/Documentation/config/safe.adoc b/Documentation/config/safe.adoc
index 2d45c98b12..5ae4476b24 100644
--- a/Documentation/config/safe.adoc
+++ b/Documentation/config/safe.adoc
@@ -2,10 +2,12 @@ safe.bareRepository::
 	Specifies which bare repositories Git will work with. The currently
 	supported values are:
 +
+--
 * `all`: Git works with all bare repositories. This is the default.
 * `explicit`: Git only works with bare repositories specified via
   the top-level `--git-dir` command-line option, or the `GIT_DIR`
   environment variable (see linkgit:git[1]).
+--
 +
 If you do not use bare repositories in your workflow, then it may be
 beneficial to set `safe.bareRepository` to `explicit` in your global
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 00545b2054..8439ce97df 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -221,6 +221,7 @@ Use `--no-value` to unset _<pattern>_.
 +
 Valid `<type>`'s include:
 +
+--
 - 'bool': canonicalize values `true`, `yes`, `on`, and positive
   numbers as "true", and values `false`, `no`, `off` and `0` as
   "false".
@@ -239,6 +240,7 @@ Valid `<type>`'s include:
   escape sequence. When setting a value, a sanity-check is performed to ensure
   that the given value is canonicalize-able as an ANSI color, but it is written
   as-is.
+--
 +
 If the command is in `list` mode, then the `--type <type>` argument will apply
 to each listed config value. If the value does not successfully parse in that
-- 
2.30.2

[PATCH v3 2/3] doc: config/sideband: fix description list delimiter

[Tuomas Ahola]

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---

Notes (doc-diff):
    diff --git a/c9131b23fd1c8611fde5664fcfd4e6d5283648ad/home/taahol/share/man/man1/git-config.1 b/ca65211ea4c351071c5e76dabe4700ad074b75d3/home/taahol/share/man/man1/git-config.1
    index d915897ca5..e0e2bf3c36 100644
    --- a/c9131b23fd1c8611fde5664fcfd4e6d5283648ad/home/taahol/share/man/man1/git-config.1
    +++ b/ca65211ea4c351071c5e76dabe4700ad074b75d3/home/taahol/share/man/man1/git-config.1
    @@ -6827,8 +6827,10 @@ CONFIGURATION FILE
                color
                    Allow ANSI color sequences, line feeds and horizontal tabs, but
                    mask all other control characters. This is the default.
    -               cursor:: Allow control sequences that move the cursor. This is
    -               disabled by default.
    +
    +           cursor
    +               Allow control sequences that move the cursor. This is disabled
    +               by default.
    
                erase
                    Allow control sequences that erase charactrs. This is disabled

 Documentation/config/sideband.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/config/sideband.adoc b/Documentation/config/sideband.adoc
index 96fade7f5f..06de0d5c07 100644
--- a/Documentation/config/sideband.adoc
+++ b/Documentation/config/sideband.adoc
@@ -9,7 +9,7 @@ sideband.allowControlCharacters::
 	`color`::
 		Allow ANSI color sequences, line feeds and horizontal tabs,
 		but mask all other control characters. This is the default.
-	`cursor:`:
+	`cursor`::
 		Allow control sequences that move the cursor. This is
 		disabled by default.
 	`erase`::
-- 
2.30.2

[PATCH v3 3/3] doc: git-config: escape erroneous highlight markup

[Tuomas Ahola]

Paired octothorpes are used in AsciiDoc to mark highlighted text,
<mark> being the equivalent HTML tag.  To use the symbol as a literal
character, it can be escaped with backticks.

Do so in git-config.adoc.

While at it, tweak the text slightly to make it scan better.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---

Notes (doc-diff):
    diff --git a/ca65211ea4c351071c5e76dabe4700ad074b75d3/home/taahol/share/man/man1/git-config.1 b/e2d0cc8218242cc859daabb179af07ebf96fe459/home/taahol/share/man/man1/git-config.1
    index e0e2bf3c36..1e9e49b197 100644
    --- a/ca65211ea4c351071c5e76dabe4700ad074b75d3/home/taahol/share/man/man1/git-config.1
    +++ b/e2d0cc8218242cc859daabb179af07ebf96fe459/home/taahol/share/man/man1/git-config.1
    @@ -113,11 +113,11 @@ OPTIONS
            --comment <message>
                Append a comment at the end of new or modified lines.
    
    -           If <message> begins with one or more whitespaces followed by "", it
    -           is used as-is. If it begins with "", a space is prepended before it
    +           If <message> begins with one or more whitespaces followed by #, it
    +           is used as-is. If it begins with #, a space is prepended before it
                is used. Otherwise, a string " # " (a space followed by a hash
    -           followed by a space) is prepended to it. And the resulting string
    -           is placed immediately after the value defined for the variable. The
    +           followed by a space) is prepended to it. The resulting string is
    +           placed immediately after the value defined for the variable. The
                <message> must not contain linefeed characters (no multi-line
                comments are permitted).

 Documentation/git-config.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 8439ce97df..57af010ade 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -119,10 +119,10 @@ OPTIONS
 	Append a comment at the end of new or modified lines.
 +
 If _<message>_ begins with one or more whitespaces followed
-by "#", it is used as-is.  If it begins with "#", a space is
-prepended before it is used.  Otherwise, a string " # " (a
+by `#`, it is used as-is.  If it begins with `#`, a space is
+prepended before it is used.  Otherwise, a string `" # "` (a
 space followed by a hash followed by a space) is prepended
-to it.  And the resulting string is placed immediately after
+to it.  The resulting string is placed immediately after
 the value defined for the variable.  The _<message>_ must
 not contain linefeed characters (no multi-line comments are
 permitted).
-- 
2.30.2