[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

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

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