[PATCH] doc: Make asciidoc bullet items separate

[PATCH] doc: Make asciidoc bullet items separate

[Brigham Campbell]

Fix conjoined bullet items in maintenance asciidoc file.

Signed-off-by: Brigham Campbell <me@brighamcampbell.com>
---
 Documentation/config/maintenance.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
index da8be9f812..c778ab09ac 100644
--- a/Documentation/config/maintenance.adoc
+++ b/Documentation/config/maintenance.adoc
@@ -41,6 +41,7 @@ The possible strategies are:
 This repacking strategy is a full replacement for the `gc` strategy and is
 recommended for large repositories. This is the default strategy for manual
 maintenance.
++
 * `incremental`: This setting optimizes for performing small maintenance
   activities that do not delete any data. This does not schedule the `gc`
   task, but runs the `prefetch` and `commit-graph` tasks hourly, the

---
base-commit: 3cb9185f65410273787f74333cc027d2ea5daada
change-id: 20260907-maintenance-doc-bullet-fix-d351253f8a91

Thanks!
-- 
Brigham Campbell
https://brighamcampbell.com

Re: [PATCH] doc: Make asciidoc bullet items separate

[Patrick Steinhardt]

On Mon, Sep 07, 2026 at 01:15:57AM -0600, Brigham Campbell wrote:
> Fix conjoined bullet items in maintenance asciidoc file.

Not, probably not worth a reroll: it would have been nice to point out
that this is in git-config(1). E.g. something like this:

    doc: fix conjoined maintenance strategies in git-config(1)

    Fix conjoined bullet items for the maintennace strategies in
    git-config(1).

> diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
> index da8be9f812..c778ab09ac 100644
> --- a/Documentation/config/maintenance.adoc
> +++ b/Documentation/config/maintenance.adoc
> @@ -41,6 +41,7 @@ The possible strategies are:
>  This repacking strategy is a full replacement for the `gc` strategy and is
>  recommended for large repositories. This is the default strategy for manual
>  maintenance.
> ++
>  * `incremental`: This setting optimizes for performing small maintenance
>    activities that do not delete any data. This does not schedule the `gc`
>    task, but runs the `prefetch` and `commit-graph` tasks hourly, the

Ah, indeed. I can confirm that this is misrendered when looking at
git-config(1), and with your patch it indeed renders correctly. Thanks
for this simple and obvious fix!

Patrick

Re: [PATCH] doc: Make asciidoc bullet items separate

[Kristoffer Haugsbakk]

On Mon, Sep 7, 2026, at 09:15, Brigham Campbell wrote:
> Fix conjoined bullet items in maintenance asciidoc file.
>
> Signed-off-by: Brigham Campbell <me@brighamcampbell.com>
> ---
>  Documentation/config/maintenance.adoc | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/config/maintenance.adoc
> b/Documentation/config/maintenance.adoc
> index da8be9f812..c778ab09ac 100644
> --- a/Documentation/config/maintenance.adoc
> +++ b/Documentation/config/maintenance.adoc
> @@ -41,6 +41,7 @@ The possible strategies are:
>  This repacking strategy is a full replacement for the `gc` strategy
> and is
>  recommended for large repositories. This is the default strategy for
> manual
>  maintenance.
> ++
>  * `incremental`: This setting optimizes for performing small
> maintenance
>    activities that do not delete any data. This does not schedule the
> `gc`
>    task, but runs the `prefetch` and `commit-graph` tasks hourly, the
>
> ---
> base-commit: 3cb9185f65410273787f74333cc027d2ea5daada
> change-id: 20260907-maintenance-doc-bullet-fix-d351253f8a91

I wonder if this gives different results for asciidoc and asciidoctor.

• asciidoctor: seems that the bullet list is correct with or without
  this change (no change)
• asciidoc: needs this change

Note that I’ve made enough asciidoc/tor mistakes so I’m not that
reliable of a witness.

I also idly wonder why git-scm renders this bullet list as it ought
to. This hunk has not been modified for a while. The second paragraph
which ostensibly made it conjoined was d9bccf2e (builtin/maintenance:
introduce "geometric" strategy, 2025-10-24).

https://git-scm.com/docs/git-config

Re: [PATCH] doc: Make asciidoc bullet items separate

[Brigham Campbell]

On Mon Sep 7, 2026 at 2:46 AM MDT, Patrick Steinhardt wrote:
> Not, probably not worth a reroll: it would have been nice to point out
> that this is in git-config(1). E.g. something like this:
>
>     doc: fix conjoined maintenance strategies in git-config(1)
>
>     Fix conjoined bullet items for the maintennace

maintennace -> maintenance

>                                                    strategies in
>     git-config(1).

I'll mention git-config(1) in v2 if maintainers request a new revision
(though I agree that a patch this simple probably doesn't need a
reroll). Otherwise, I invite the committer to make editorial changes to
the commit message as they see fit.

>> diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
>> index da8be9f812..c778ab09ac 100644
>> --- a/Documentation/config/maintenance.adoc
>> +++ b/Documentation/config/maintenance.adoc
>> @@ -41,6 +41,7 @@ The possible strategies are:
>>  This repacking strategy is a full replacement for the `gc` strategy and is
>>  recommended for large repositories. This is the default strategy for manual
>>  maintenance.
>> ++
>>  * `incremental`: This setting optimizes for performing small maintenance
>>    activities that do not delete any data. This does not schedule the `gc`
>>    task, but runs the `prefetch` and `commit-graph` tasks hourly, the
>
> Ah, indeed. I can confirm that this is misrendered when looking at
> git-config(1), and with your patch it indeed renders correctly. Thanks
> for this simple and obvious fix!

Thanks for the review! It's a minor change, but this is my first patch
to the git project, so I appreciate your time and expertise.

Cheers!
-- 
Brigham Campbell
https://brighamcampbell.com

[PATCH v2] doc: fix conjoined maintenance strategies in git-config(1)

[Brigham Campbell]

Fix conjoined bullet items for the maintenance strategies in
git-config(1). Reportedly, asciidoctor renders this document correctly
both before and after this patch. asciidoc renders it correctly only
_after_ this patch.

Signed-off-by: Brigham Campbell <me@brighamcampbell.com>
---
I wouldn't normally spin a v2 this quickly, but Jun specifically asked
for v2 on a thread on the "what's cooking" news.

Patrick, Kristoffer, if this revision is to your liking, I'd appreciate
an Acked-by from either of you. If not, please let me know what to
change for v3.

Changes in v2:
- Tweak commit message wording
- Link to v1: https://patch.msgid.link/20260907-maintenance-doc-bullet-fix-v1-1-dc08dbe61a82@brighamcampbell.com

Cc: git@vger.kernel.org
To: Taylor Blau <me@ttaylorr.com>
To: Junio C Hamano <gitster@pobox.com>
To: Patrick Steinhardt <ps@pks.im>
To: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
---
 Documentation/config/maintenance.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
index da8be9f812..c778ab09ac 100644
--- a/Documentation/config/maintenance.adoc
+++ b/Documentation/config/maintenance.adoc
@@ -41,6 +41,7 @@ The possible strategies are:
 This repacking strategy is a full replacement for the `gc` strategy and is
 recommended for large repositories. This is the default strategy for manual
 maintenance.
++
 * `incremental`: This setting optimizes for performing small maintenance
   activities that do not delete any data. This does not schedule the `gc`
   task, but runs the `prefetch` and `commit-graph` tasks hourly, the

---
base-commit: 3cb9185f65410273787f74333cc027d2ea5daada
change-id: 20260907-maintenance-doc-bullet-fix-d351253f8a91

Thanks!
-- 
Brigham Campbell
https://brighamcampbell.com

Re: [PATCH v2] doc: fix conjoined maintenance strategies in git-config(1)

[Patrick Steinhardt]

On Thu, Sep 10, 2026 at 12:52:31AM -0600, Brigham Campbell wrote:
> Fix conjoined bullet items for the maintenance strategies in
> git-config(1). Reportedly, asciidoctor renders this document correctly
> both before and after this patch. asciidoc renders it correctly only
> _after_ this patch.
> 
> Signed-off-by: Brigham Campbell <me@brighamcampbell.com>
> ---
> I wouldn't normally spin a v2 this quickly, but Jun specifically asked
> for v2 on a thread on the "what's cooking" news.

The pacing is totally fine, it's been multiple days since your v1.

> Patrick, Kristoffer, if this revision is to your liking, I'd appreciate
> an Acked-by from either of you. If not, please let me know what to
> change for v3.

This version looks good to me, thanks!

Patrick

Re: [PATCH] doc: Make asciidoc bullet items separate

[Jeff King]

On Mon, Sep 07, 2026 at 12:18:48PM +0200, Kristoffer Haugsbakk wrote:

> I wonder if this gives different results for asciidoc and asciidoctor.
> 
> • asciidoctor: seems that the bullet list is correct with or without
>   this change (no change)
> • asciidoc: needs this change

Yeah, I think we've run into this sort of parsing subtlety between the
two before.

I imagine this is how you did it, but for the original author and
anybody else working on documentation, it is often useful to do:

  cd Documentation
  ./doc-diff HEAD^ HEAD
  ./doc-diff --asciidoctor HEAD^ HEAD

to see how your changes work in both systems. You can also do:

  ./doc-diff --from-asciidoctor --to-asciidoc HEAD HEAD

to see how the two renderers differ currently, but there's quite a lot
of noise (differing wrapping, indentation, use of quotes, etc). All of
those may be candidates for examination and fixing, but it is a lot of
noise if you are looking at your one area. ;)

> I also idly wonder why git-scm renders this bullet list as it ought
> to. This hunk has not been modified for a while. The second paragraph
> which ostensibly made it conjoined was d9bccf2e (builtin/maintenance:
> introduce "geometric" strategy, 2025-10-24).

It uses asciidoctor. :)

-Peff