[RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Ramsay Jones]

Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
---
 Documentation/technical/commit-graph.adoc | 34 +++++++++++------------
 1 file changed, 16 insertions(+), 18 deletions(-)

diff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc
index 2c26e95e51..15396f58ab 100644
--- a/Documentation/technical/commit-graph.adoc
+++ b/Documentation/technical/commit-graph.adoc
@@ -1,5 +1,4 @@
-Git Commit-Graph Design Notes
-=============================
+= Git Commit-Graph Design Notes
 
 Git walks the commit graph for many reasons, including:
 
@@ -39,6 +38,7 @@ A consumer may load the following info for a commit from the graph:
 Values 1-4 satisfy the requirements of parse_commit_gently().
 
 There are two definitions of generation number:
+
 1. Corrected committer dates (generation number v2)
 2. Topological levels (generation number v1)
 
@@ -122,8 +122,7 @@ can be stored in the commit-graph file using the 30 bits available
 to topological levels. This presents another case where a commit can
 have generation number equal to that of a parent.
 
-Design Details
---------------
+== Design Details
 
 - The commit-graph file is stored in a file named 'commit-graph' in the
   .git/objects/info directory. This could be stored in the info directory
@@ -149,8 +148,7 @@ Design Details
   helpful for these clones, anyway. The commit-graph will not be read or
   written when shallow commits are present.
 
-Commit-Graphs Chains
---------------------
+== Commit-Graphs Chains
 
 Typically, repos grow with near-constant velocity (commits per day). Over time,
 the number of commits added by a fetch operation is much smaller than the
@@ -158,7 +156,7 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
 we enable fast writes of new commit data without rewriting the entire commit
 history -- at least, most of the time.
 
-## File Layout
+=== File Layout
 
 A commit-graph chain uses multiple files, and we use a fixed naming convention
 to organize these files. Each commit-graph file has a name
@@ -170,11 +168,11 @@ hashes for the files in order from "lowest" to "highest".
 
 For example, if the `commit-graph-chain` file contains the lines
 
-```
+----
 	{hash0}
 	{hash1}
 	{hash2}
-```
+----
 
 then the commit-graph chain looks like the following diagram:
 
@@ -213,7 +211,7 @@ specifying the hashes of all files in the lower layers. In the above example,
 `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
 `{hash0}` and `{hash1}`.
 
-## Merging commit-graph files
+=== Merging commit-graph files
 
 If we only added a new commit-graph file on every write, we would run into a
 linear search problem through many commit-graph files.  Instead, we use a merge
@@ -257,14 +255,14 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`
 according to the computed `{hash3}`. Finally, we write the new chain data to
 `commit-graph-chain.lock`:
 
-```
+----
 	{hash3}
 	{hash0}
-```
+----
 
 We then close the lock-file.
 
-## Merge Strategy
+=== Merge Strategy
 
 When writing a set of commits that do not exist in the commit-graph stack of
 height N, we default to creating a new file at level N + 1. We then decide to
@@ -289,7 +287,7 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
 number of commits) could be extracted into config settings for full
 flexibility.
 
-## Handling Mixed Generation Number Chains
+=== Handling Mixed Generation Number Chains
 
 With the introduction of generation number v2 and generation data chunk, the
 following scenario is possible:
@@ -318,7 +316,7 @@ have corrected commit dates when written by compatible versions of Git. Thus,
 rewriting split commit-graph as a single file (`--split=replace`) creates a
 single layer with corrected commit dates.
 
-## Deleting graph-{hash} files
+=== Deleting graph-\{hash\} files
 
 After a new tip file is written, some `graph-{hash}` files may no longer
 be part of a chain. It is important to remove these files from disk, eventually.
@@ -333,7 +331,7 @@ files whose modified times are older than a given expiry window. This window
 defaults to zero, but can be changed using command-line arguments or a config
 setting.
 
-## Chains across multiple object directories
+=== Chains across multiple object directories
 
 In a repo with alternates, we look for the `commit-graph-chain` file starting
 in the local object directory and then in each alternate. The first file that
@@ -369,8 +367,8 @@ their custom environment:
     access to the new chain until its chain is updated to reference those files.
     (This may change in the future [5].)
 
-Related Links
--------------
+== Related Links
+
 [0] https://bugs.chromium.org/p/git/issues/detail?id=8
     Chromium work item for: Serialized Commit Graph
 
-- 
2.51.0

Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
> ---
>  Documentation/technical/commit-graph.adoc | 34 +++++++++++------------
>  1 file changed, 16 insertions(+), 18 deletions(-)

Are these the issues?

 - Use ={n} prefixes instead of underlines for the section headers.

 - Use ={n} not #{n} prefixes for the section headers.

 - A blank line between a leading text before a numbered list.

 - Mark-up of displayed materials.

The majority of our pages (I think all of the manual pages) use
underlines.  Are we getting warnings on them that we'd need to
change?  I personally find the underlined style easier to read
in the source text (even though I understand why people would
prefer to use the ={n} prefix style---having to adjust the length
of the underline is a bit more work when retitling).

The remainder of this message does not have any comment from me,
but is left as a reference for others.

> diff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc
> index 2c26e95e51..15396f58ab 100644
> --- a/Documentation/technical/commit-graph.adoc
> +++ b/Documentation/technical/commit-graph.adoc
> @@ -1,5 +1,4 @@
> -Git Commit-Graph Design Notes
> -=============================
> += Git Commit-Graph Design Notes
>  
>  Git walks the commit graph for many reasons, including:
>  
> @@ -39,6 +38,7 @@ A consumer may load the following info for a commit from the graph:
>  Values 1-4 satisfy the requirements of parse_commit_gently().
>  
>  There are two definitions of generation number:
> +
>  1. Corrected committer dates (generation number v2)
>  2. Topological levels (generation number v1)
>  
> @@ -122,8 +122,7 @@ can be stored in the commit-graph file using the 30 bits available
>  to topological levels. This presents another case where a commit can
>  have generation number equal to that of a parent.
>  
> -Design Details
> ---------------
> +== Design Details
>  
>  - The commit-graph file is stored in a file named 'commit-graph' in the
>    .git/objects/info directory. This could be stored in the info directory
> @@ -149,8 +148,7 @@ Design Details
>    helpful for these clones, anyway. The commit-graph will not be read or
>    written when shallow commits are present.
>  
> -Commit-Graphs Chains
> ---------------------
> +== Commit-Graphs Chains
>  
>  Typically, repos grow with near-constant velocity (commits per day). Over time,
>  the number of commits added by a fetch operation is much smaller than the
> @@ -158,7 +156,7 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
>  we enable fast writes of new commit data without rewriting the entire commit
>  history -- at least, most of the time.
>  
> -## File Layout
> +=== File Layout
>  
>  A commit-graph chain uses multiple files, and we use a fixed naming convention
>  to organize these files. Each commit-graph file has a name
> @@ -170,11 +168,11 @@ hashes for the files in order from "lowest" to "highest".
>  
>  For example, if the `commit-graph-chain` file contains the lines
>  
> -```
> +----
>  	{hash0}
>  	{hash1}
>  	{hash2}
> -```
> +----
>  
>  then the commit-graph chain looks like the following diagram:
>  
> @@ -213,7 +211,7 @@ specifying the hashes of all files in the lower layers. In the above example,
>  `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
>  `{hash0}` and `{hash1}`.
>  
> -## Merging commit-graph files
> +=== Merging commit-graph files
>  
>  If we only added a new commit-graph file on every write, we would run into a
>  linear search problem through many commit-graph files.  Instead, we use a merge
> @@ -257,14 +255,14 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`
>  according to the computed `{hash3}`. Finally, we write the new chain data to
>  `commit-graph-chain.lock`:
>  
> -```
> +----
>  	{hash3}
>  	{hash0}
> -```
> +----
>  
>  We then close the lock-file.
>  
> -## Merge Strategy
> +=== Merge Strategy
>  
>  When writing a set of commits that do not exist in the commit-graph stack of
>  height N, we default to creating a new file at level N + 1. We then decide to
> @@ -289,7 +287,7 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
>  number of commits) could be extracted into config settings for full
>  flexibility.
>  
> -## Handling Mixed Generation Number Chains
> +=== Handling Mixed Generation Number Chains
>  
>  With the introduction of generation number v2 and generation data chunk, the
>  following scenario is possible:
> @@ -318,7 +316,7 @@ have corrected commit dates when written by compatible versions of Git. Thus,
>  rewriting split commit-graph as a single file (`--split=replace`) creates a
>  single layer with corrected commit dates.
>  
> -## Deleting graph-{hash} files
> +=== Deleting graph-\{hash\} files
>  
>  After a new tip file is written, some `graph-{hash}` files may no longer
>  be part of a chain. It is important to remove these files from disk, eventually.
> @@ -333,7 +331,7 @@ files whose modified times are older than a given expiry window. This window
>  defaults to zero, but can be changed using command-line arguments or a config
>  setting.
>  
> -## Chains across multiple object directories
> +=== Chains across multiple object directories
>  
>  In a repo with alternates, we look for the `commit-graph-chain` file starting
>  in the local object directory and then in each alternate. The first file that
> @@ -369,8 +367,8 @@ their custom environment:
>      access to the new chain until its chain is updated to reference those files.
>      (This may change in the future [5].)
>  
> -Related Links
> --------------
> +== Related Links
> +
>  [0] https://bugs.chromium.org/p/git/issues/detail?id=8
>      Chromium work item for: Serialized Commit Graph

Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Ramsay Jones]

On 26/09/2025 4:52 pm, Junio C Hamano wrote:
> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
>> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
>> ---
>>  Documentation/technical/commit-graph.adoc | 34 +++++++++++------------
>>  1 file changed, 16 insertions(+), 18 deletions(-)
> 
> Are these the issues?
> 
>  - Use ={n} prefixes instead of underlines for the section headers.
> 
>  - Use ={n} not #{n} prefixes for the section headers.
> 
>  - A blank line between a leading text before a numbered list.
> 
>  - Mark-up of displayed materials.
> 
> The majority of our pages (I think all of the manual pages) use
> underlines.  Are we getting warnings on them that we'd need to
> change?  I personally find the underlined style easier to read
> in the source text (even though I understand why people would
> prefer to use the ={n} prefix style---having to adjust the length
> of the underline is a bit more work when retitling).

Heh, my first attempt used an '+' character for the underlining of the
'next' level headers, rather than '## ', since that was what I thought
it was (from a very vague memory), but asciidoc disagreed! ;)

I tried searching the web for the answer, without success, so went with
the 'prefix' style used here. However, when I read the above, it made me
look at out current docs and gitworkflows.adoc showed me I should have
used an '~' character instead.

I just tried this and it works great (apart from having to \-quote the
'{' and '}' characters in one title), so a revised 'diff' is given below.

[all the other problems remain, of course]

Would you prefer this 'patch'?

ATB,
Ramsay Jones

--- >8 ---
diff --git a/Documentation/technical/commit-graph.adoc b/Documentation/technical/commit-graph.adoc
index 2c26e95e51..f5522ba437 100644
--- a/Documentation/technical/commit-graph.adoc
+++ b/Documentation/technical/commit-graph.adoc
@@ -39,6 +39,7 @@ A consumer may load the following info for a commit from the graph:
 Values 1-4 satisfy the requirements of parse_commit_gently().
 
 There are two definitions of generation number:
+
 1. Corrected committer dates (generation number v2)
 2. Topological levels (generation number v1)
 
@@ -158,7 +159,8 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
 we enable fast writes of new commit data without rewriting the entire commit
 history -- at least, most of the time.
 
-## File Layout
+File Layout
+~~~~~~~~~~~
 
 A commit-graph chain uses multiple files, and we use a fixed naming convention
 to organize these files. Each commit-graph file has a name
@@ -170,11 +172,11 @@ hashes for the files in order from "lowest" to "highest".
 
 For example, if the `commit-graph-chain` file contains the lines
 
-```
+----
 	{hash0}
 	{hash1}
 	{hash2}
-```
+----
 
 then the commit-graph chain looks like the following diagram:
 
@@ -213,7 +215,8 @@ specifying the hashes of all files in the lower layers. In the above example,
 `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
 `{hash0}` and `{hash1}`.
 
-## Merging commit-graph files
+Merging commit-graph files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If we only added a new commit-graph file on every write, we would run into a
 linear search problem through many commit-graph files.  Instead, we use a merge
@@ -257,14 +260,15 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`
 according to the computed `{hash3}`. Finally, we write the new chain data to
 `commit-graph-chain.lock`:
 
-```
+----
 	{hash3}
 	{hash0}
-```
+----
 
 We then close the lock-file.
 
-## Merge Strategy
+Merge Strategy
+~~~~~~~~~~~~~~
 
 When writing a set of commits that do not exist in the commit-graph stack of
 height N, we default to creating a new file at level N + 1. We then decide to
@@ -289,7 +293,8 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
 number of commits) could be extracted into config settings for full
 flexibility.
 
-## Handling Mixed Generation Number Chains
+Handling Mixed Generation Number Chains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 With the introduction of generation number v2 and generation data chunk, the
 following scenario is possible:
@@ -318,7 +323,8 @@ have corrected commit dates when written by compatible versions of Git. Thus,
 rewriting split commit-graph as a single file (`--split=replace`) creates a
 single layer with corrected commit dates.
 
-## Deleting graph-{hash} files
+Deleting graph-\{hash\} files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After a new tip file is written, some `graph-{hash}` files may no longer
 be part of a chain. It is important to remove these files from disk, eventually.
@@ -333,7 +339,8 @@ files whose modified times are older than a given expiry window. This window
 defaults to zero, but can be changed using command-line arguments or a config
 setting.
 
-## Chains across multiple object directories
+Chains across multiple object directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a repo with alternates, we look for the `commit-graph-chain` file starting
 in the local object directory and then in each alternate. The first file that

Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

> I tried searching the web for the answer, without success, so went with
> the 'prefix' style used here. However, when I read the above, it made me
> look at out current docs and gitworkflows.adoc showed me I should have
> used an '~' character instead.
>
> I just tried this and it works great (apart from having to \-quote the
> '{' and '}' characters in one title), so a revised 'diff' is given below.

Oy.  It is one of the special things I am unsure about---would a
character used for such quoting (e.g., backslash in this case) count
as one display space to count the number of underlying characters?

That is, which one of these do AsciiDoc and Asciidoctor want?

    Deleting graph-\{hash\} files
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Deleting graph-\{hash\} files
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~--

There is

    OPTIONS[[OPTIONS]]
    ------------------

that appears in MyFirstContribution.adoc (even though that is an
illustration of what you would write in the source and never used),
and

    `builtin_objectmode`
    ~~~~~~~~~~~~~~~~~~~~

that appears in gitattributes.adoc (this one is rendered), so I've
been assuming that these characters necessary for mark-up do count.

I guess this is the same "prefix is easier to write, underling is
harder to write correctly" theme?  If we know which one is correct
and can use the correct version, then I do prefer the underlined
form.

Thanks.

Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Ramsay Jones]

On 26/09/2025 10:21 pm, Junio C Hamano wrote:
> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
>> I tried searching the web for the answer, without success, so went with
>> the 'prefix' style used here. However, when I read the above, it made me
>> look at out current docs and gitworkflows.adoc showed me I should have
>> used an '~' character instead.
>>
>> I just tried this and it works great (apart from having to \-quote the
>> '{' and '}' characters in one title), so a revised 'diff' is given below.
> 
> Oy.  It is one of the special things I am unsure about---would a
> character used for such quoting (e.g., backslash in this case) count
> as one display space to count the number of underlying characters?
> 
> That is, which one of these do AsciiDoc and Asciidoctor want?
> 
>     Deleting graph-\{hash\} files
>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is what I did and, with asciidoc anyway, looked fine.

>     Deleting graph-\{hash\} files
>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

I just tried this, and it was fine also! :)

Hmm, let me just try asciidoctor ...

Well, with asciidoctor it requires the underlining to be exactly
the same size as the text (ie the second example above), otherwise
it mangles the heading (well it doesn't seem to recognize it as a
heading at all. It looks like:

Deleting graph-{hash} files ~~~~~~~~~

So, not the first time asciidoc and asciidoctor differ in the rendered
output. (yes, the number of ~ chars is not the same as the input).

So, I need to change the diff to extend the underlining on that
heading, so both asciidoc and asciidoctor both render it correctly.

BTW, the asciidoc version of this document has a date which appears after
the initial heading (but it is the day before the 'last date updated' one
at the end of the document) and I have no idea why it is there!

(To be clear, it does not appear in the asciidoctor rendering!)

ATB,
Ramsay Jones

Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

>> That is, which one of these do AsciiDoc and Asciidoctor want?
>> 
>>     Deleting graph-\{hash\} files
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> This is what I did and, with asciidoc anyway, looked fine.
>
>>     Deleting graph-\{hash\} files
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> I just tried this, and it was fine also! :)
>
> Hmm, let me just try asciidoctor ...
>
> Well, with asciidoctor it requires the underlining to be exactly
> the same size as the text (ie the second example above), otherwise
> it mangles the heading (well it doesn't seem to recognize it as a
> heading at all. It looks like:
>
> Deleting graph-{hash} files ~~~~~~~~~
>
> So, not the first time asciidoc and asciidoctor differ in the rendered
> output. (yes, the number of ~ chars is not the same as the input).

Yeah, so the latter one (i.e. count escapes and mark-up letters when
computing how long your underline need to be) is required to please
both.  I knew AsciiDoc allowed a bit of slop and that is how your
experiment (the first one above) was fine.  I didn't know how large
a slop AsciiDoc allowed, but it seems at least we can be missing two
and the tool is still happy.

> So, I need to change the diff to extend the underlining on that
> heading, so both asciidoc and asciidoctor both render it correctly.

So it seems.

Thanks.