Skip to contentSkip to conversation

doc: config: fix AsciiDoc glitches

PATCH Superseded Tuomas Ahola 5 participants 30 messages Jun 10 – Jun 12 Documentation

lore
Share & tools
lore
#0 lore raw

cover doc: config: fix AsciiDoc glitches

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

Signature · 1 line
2.30.2
#1 lore raw

PATCH 1/3 doc: config: terminate runaway lists

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.

---
 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(-)
Documentation/config.adoc +3 -1
index dcea3c0c15..fc48c1c461 100644
@@ -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
Documentation/config/promisor.adoc +2 -0
index b0fa43b839..39af63dcb8 100644
@@ -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.
Documentation/config/safe.adoc +2 -0
index 2d45c98b12..5ae4476b24 100644
@@ -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
Documentation/git-config.adoc +2 -0
index 00545b2054..8439ce97df 100644
@@ -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
Signature · 1 line
2.30.2
#2 lore raw

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

In reply to Tuomas Ahola

Fix a simple typo in AsciiDoc markup.

---
 Documentation/config/sideband.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/config/sideband.adoc +1 -1
index 96fade7f5f..06de0d5c07 100644
@@ -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`::
Signature · 1 line
2.30.2
#3 lore raw

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

Quoted 1 line

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

Quoted 1 line · Tuomas Ahola

Fix a simple typo in AsciiDoc markup.

The subject of the commit might be enough here.

Documentation/config/sideband.adoc sideband.allowControlCharacters:: · line 12

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

[snip]

Documentation/config/sideband.adoc +1 -1
@@ -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!

Quoted 5 lines
Documentation/config/sideband.adoc +0 -1
 		Allow control sequences that move the cursor. This is
 		disabled by default.
 	`erase`::
--

2.30.2

#4 lore raw

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

In reply to 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.

---
 Documentation/git-config.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-config.adoc +2 -2
index 8439ce97df..708e88cdeb 100644
@@ -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).
Signature · 1 line
2.30.2
#5 lore raw

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

Quoted 4 lines · 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.

Quoted 8 lines

Do so in git-config.adoc.

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

---
 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 ;-)

Quoted 17 lines
Documentation/git-config.adoc +2 -2
index 8439ce97df..708e88cdeb 100644
@@ -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).
#6 lore raw

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

Quoted 6 lines · Junio C Hamano

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 ;-)

Quoted 11 lines

Documentation/git-config.adoc OPTIONS · line 123

Quoted 11 lines
Documentation/git-config.adoc +1 -1
index 8439ce97df..708e88cdeb 100644
@@ -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

Quoted 2 lines

Documentation/git-config.adoc OPTIONS · line 124

Quoted 2 lines
Documentation/git-config.adoc +1 -1
-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?

Quoted 6 lines
Quoted 6 lines
Documentation/git-config.adoc +1 -1
 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).

#7 lore raw

v2 cover doc: config: fix AsciiDoc glitches

In reply to 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 <[email protected]>

## Commit message ##
- doc: config/sideband: fix typo in adoc markup
-
- Fix a simple typo in AsciiDoc markup.
+ doc: config/sideband: fix description list delimiter

3: 7d0916a874 ! 3: 0341a4bde9 doc: git-config: escape erroneous adoc markup
@@ Metadata
Author: Tuomas Ahola <[email protected]>

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

Signature · 1 line
2.30.2
#8 lore raw

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

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.

---
 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(-)
Documentation/config.adoc +3 -1
index dcea3c0c15..fc48c1c461 100644
@@ -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
Documentation/config/promisor.adoc +2 -0
index b0fa43b839..39af63dcb8 100644
@@ -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.
Documentation/config/safe.adoc +2 -0
index 2d45c98b12..5ae4476b24 100644
@@ -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
Documentation/git-config.adoc +2 -0
index 00545b2054..8439ce97df 100644
@@ -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
Signature · 1 line
2.30.2
#9 lore raw

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

Quoted 5 lines · 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:

Quoted 8 lines
	--
	* 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

#10 lore raw

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

In reply to Tuomas Ahola
---
 Documentation/config/sideband.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/config/sideband.adoc +1 -1
index 96fade7f5f..06de0d5c07 100644
@@ -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`::
Signature · 1 line
2.30.2
#11 lore raw

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

In reply to 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.

---
 Documentation/git-config.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-config.adoc +2 -2
index 8439ce97df..e4af6cac68 100644
@@ -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).
Signature · 1 line
2.30.2
#12 lore raw

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

Quoted 5 lines · 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.

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.

Documentation/git-config.adoc OPTIONS · line 124

Quoted 5 lines

If _<message>_ begins with one or more whitespaces followed

Documentation/git-config.adoc +1 -1
-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

#13 lore raw

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

Quoted 3 lines · Jeff King

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

#14 lore raw

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

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

Quoted 36 lines · Jeff King
Quoted 3 lines · Jeff King

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

#15 lore raw

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

Quoted 29 lines · On Thursday, 11 June 2026 08:25:25 CEST Jeff King wrote:

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

Quoted 26 lines · Jeff King
Quoted 3 lines · Jeff King

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.

Quoted 5 lines
Quoted 5 lines

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

Oh, this is the black magic regexp that is not considering # for keyword character. Should be solved by something like (and I really hate these .in files):

-- >8 --

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Date: Thu, 11 Jun 2026 19:44:43 +0200
Subject: [PATCH] asciidoc: fix handling of # in synopsis text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There are occurrences of # in the synopsis text of git-config(1) and git-clone(1) that are not handled as keyword by the current asciidoc and asciidoctor processors.

---
 Documentation/asciidoc.conf.in             | 12 ++++++------
 Documentation/asciidoctor-extensions.rb.in |  6 +++---
 2 files changed, 9 insertions(+), 9 deletions(-)
Documentation/asciidoc.conf.in +6 -6
index 31b883a72c..b50fad588e 100644
@@ -43,7 +43,7 @@ ifdef::doctype-book[]
 endif::doctype-book[]
 
 [literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$%]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@#\\\*\/_^\$%]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
 
 endif::backend-docbook[]
 
@@ -75,24 +75,24 @@ git-relative-html-prefix=
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
 
 [literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@#,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
 
 endif::backend-xhtml11[]
 
 ifdef::backend-docbook[]
 ifdef::doctype-manpage[]
 [blockdef-open]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@#,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
 
 [paradef-default]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@#,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
 endif::doctype-manpage[]
 endif::backend-docbook[]
 
 ifdef::backend-xhtml11[]
 [blockdef-open]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@#,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
 
 [paradef-default]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@#,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
 endif::backend-xhtml11[]
Documentation/asciidoctor-extensions.rb.in +3 -3
index fe64a62d96..b5f06827ca 100644
@@ -50,7 +50,7 @@ module Git
       def process parent, reader, attrs
         outlines = reader.lines.map do |l|
           l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2')
-           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
+           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@#,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
            .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
            .gsub(']', ']{empty}')
         end
@@ -73,7 +73,7 @@ module Git
         elsif type == :monospaced
           node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2')
               .gsub(/^\.\.\.?$/, '<literal>\0</literal>')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*%]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@#/_^\$\\\*%]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
         else
           open, close, supports_phrase = QUOTE_TAGS[type]
@@ -102,7 +102,7 @@ module Git
         if node.type == :monospaced
           node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
               .gsub(/^\.\.\.?$/, '<code>\0</code>')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*%]+\.{0,2})+)}, '\1<code>\2</code>')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@#,/_^\$\\\*%]+\.{0,2})+)}, '\1<code>\2</code>')
               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
 
         else
#16 lore raw

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

Quoted 3 lines · Jean-Noël AVILA

Oh, this is the black magic regexp that is not considering # for keyword character. Should be solved by something like (and I really hate these .in files):

Your patch looks reasonable to me, but for some reason I get this doc-diff output when comparing before/after (what we don't see is the improved output from bolding those chars, since doc-diff doesn't show any markup):

926d9be4ab7ee1a57d4c570ec0f8aba28b3c2af5/home/peff/share/man/man1/git-config.1 renamed from 73bccdb573fbdf3df4abf37570be486fc0f53d4a/home/peff/share/man/man1/git-config.1 +1 -1
index b77d79f..b2bced2 100644
@@ -6983,7 +6983,7 @@ CONFIGURATION FILE
 
      status.displayCommentPrefix
          If set to true, git-status(1) will insert a comment prefix before each
-         output line (starting with core.commentChar, i.e. # by default). This
+         output line (starting with core.commentChar, i.e.  # by default). This
          was the behavior of git-status(1) in Git 1.8.4 and previous. Defaults
          to false.
 

And I can see the extra space when looking at the rendered manpage. The XML output looks reasonable, though:

(starting with <literal>core.commentChar</literal>, i.e. <literal>#</literal> by default

as does the HTML. So perhaps it is happening at the roff level? But that looks like:

will insert a comment prefix before each output line (starting with \fBcore\&.commentChar\fR, i\&.e\&.
\fB#\fR
by default)\&. This was the behavior of

So...weird. groff wants to add extra space for some reason. It happens even if I drop the bolding, and just have "#" on a line by itself. I guess maybe it is the trailing "." of the previous line putting groff into "oh, I'm starting a new sentence" mode and it uses two spaces.

But I think that is all outside the scope of your fix, and this is an existing issue that we are now just unlucky enough to hit. I'd be tempted to ignore it and possibly fix it later.

-Peff

#17 lore raw

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

Quoted 8 lines · Jeff King

So...weird. groff wants to add extra space for some reason. It happens even if I drop the bolding, and just have "#" on a line by itself. I guess maybe it is the trailing "." of the previous line putting groff into "oh, I'm starting a new sentence" mode and it uses two spaces.

But I think that is all outside the scope of your fix, and this is an existing issue that we are now just unlucky enough to hit. I'd be tempted to ignore it and possibly fix it later.

Poking at the groff manpage for possible fixes, I think it is either:

1. Just turn off extra spaces between sentences, like this:

.ss 12 0

The first argument "12" is "the minimum word space is 12/12ths of the current font's word space. The second is "also add 0/12ths between sentences" (so, no extra space).

That prevents the problem from happening anywhere, but maybe people really like the extra spaces in other contexts.

2. There are some magic characters marked as "this doesn't start a new sentence". We can set that flag for "#" like this:

.cflags 32 \#

I don't think docbook has parameter support for either of those, so we'd have to do some kind of "shove this into the header" magic, which is a bit gross.

-Peff

#18 lore raw

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

In reply to Jeff King
Quoted 27 lines · Jeff King
Quoted 5 lines · 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.

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.

Documentation/git-config.adoc OPTIONS · line 124

Quoted 5 lines

If _<message>_ begins with one or more whitespaces followed

Documentation/git-config.adoc +1 -1
-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?

Quoted 1 line

-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

#19 lore raw

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

Quoted 23 lines · Tuomas Ahola
Quoted 10 lines

Documentation/git-config.adoc OPTIONS · line 124

Quoted 5 lines

If _<message>_ begins with one or more whitespaces followed

Documentation/git-config.adoc +1 -1
-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 "#",

(quoted diff) +1 -1
-           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
Quoted 1 line

```

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

#20 lore raw

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

Quoted 38 lines · Jeff King
Quoted 23 lines · Tuomas Ahola
Quoted 10 lines

Documentation/git-config.adoc OPTIONS · line 124

Quoted 5 lines

If _<message>_ begins with one or more whitespaces followed

Documentation/git-config.adoc +1 -1
-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 "#",

(quoted diff) +1 -1
-           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
Quoted 1 line

```

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.

Quoted 8 lines

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

#21 lore raw

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

In reply to Jeff King
Quoted 8 lines · Jeff King

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.

#22 lore raw

v3 cover doc: config: fix AsciiDoc glitches

In reply to 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

Signature · 1 line
2.30.2
#23 lore raw

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

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.

---

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(-)
Documentation/config.adoc +3 -1
index dcea3c0c15..fc48c1c461 100644
@@ -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
Documentation/config/promisor.adoc +2 -0
index b0fa43b839..39af63dcb8 100644
@@ -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.
Documentation/config/safe.adoc +2 -0
index 2d45c98b12..5ae4476b24 100644
@@ -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
Documentation/git-config.adoc +2 -0
index 00545b2054..8439ce97df 100644
@@ -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
Signature · 1 line
2.30.2
#24 lore raw

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

In reply to Tuomas Ahola

---

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(-)
Documentation/config/sideband.adoc +1 -1
index 96fade7f5f..06de0d5c07 100644
@@ -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`::
Signature · 1 line
2.30.2
#25 lore raw

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

In reply to 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.

---

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(-)
Documentation/git-config.adoc +3 -3
index 8439ce97df..57af010ade 100644
@@ -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).
Signature · 1 line
2.30.2
#26 lore raw
In reply to Tuomas Ahola
Quoted 4 lines · Tuomas Ahola

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

Thanks, this v3 looks good to me.

-Peff

#27 lore raw
Quoted 8 lines · Jeff King
Quoted 4 lines · Tuomas Ahola

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

Thanks, this v3 looks good to me.

Yup this one nicely sidesteps the yucky \# thing, which is very good.

Thanks.

#28 lore raw
In reply to Jeff King
Quoted 8 lines · Jeff King
Quoted 4 lines · Tuomas Ahola

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

Thanks, this v3 looks good to me.

Yup this one nicely sidesteps the yucky \# thing, which is very good.

Thanks.

#29 lore raw
In reply to Jeff King
Quoted 8 lines · Jeff King
Quoted 4 lines · Tuomas Ahola

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

Thanks, this v3 looks good to me.

Yup this one nicely sidesteps the yucky \# thing, which is very good.

Thanks.