From: Ramsay Jones Date: Fri, 26 Sep 2025 18:11:57 GMT Subject: Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting Message-ID: In-Reply-To: On 26/09/2025 4:52 pm, Junio C Hamano wrote: > Ramsay Jones writes: > >> Signed-off-by: Ramsay Jones >> --- >> 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