doc: commit-graph.adoc: fix up some formatting
The formatting markup syntax used in this document (markdown?) is not interpreted correctly by asciidoc or asciidoctor. The main problem is the use of a '## ' prefix markup for some sub-headings, along with the use of '```' code markup and some missing literal blocks. In order to improve the (html) document formatting: - replace the '## ' prefix sub-title syntax with the '~~' underlining syntax for the relevant sub-headings. - replace the '```' code markup, which causes asciidoc(tor) to simply remove the marked up text, with a literal block '----' markup. - the second ascii diagram, in the 'Merging commit-graph files' section, is not rendered correctly by asciidoctor (asciidoc is fine) so enclose it in a '....' block. Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ramsay Jones committed
Oct 16, 2025 at 21:03 UTC
b770ed9545edf4919ea39d6fdd54fca402d28930
1 file changed
+19
-10
Documentation/technical/commit-graph.adoc
+19
-10
@@ -39,6 +39,7 @@ A consumer may load the following info for a commit from the graph:
39
Values 1-4 satisfy the requirements of parse_commit_gently().
40
41
There are two definitions of generation number:
42
+
43
1. Corrected committer dates (generation number v2)
44
2. Topological levels (generation number v1)
45
@@ -158,7 +159,8 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
159
we enable fast writes of new commit data without rewriting the entire commit
160
history -- at least, most of the time.
161
161
-## File Layout
162
+File Layout
163
+~~~~~~~~~~~
164
165
A commit-graph chain uses multiple files, and we use a fixed naming convention
166
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".
172
173
For example, if the `commit-graph-chain` file contains the lines
174
173
-```
175
+----
176
{hash0}
177
{hash1}
178
{hash2}
177
-```
179
+----
180
181
then the commit-graph chain looks like the following diagram:
182
@@ -213,7 +215,8 @@ specifying the hashes of all files in the lower layers. In the above example,
215
`graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
216
`{hash0}` and `{hash1}`.
217
216
-## Merging commit-graph files
218
+Merging commit-graph files
219
+~~~~~~~~~~~~~~~~~~~~~~~~~~
220
221
If we only added a new commit-graph file on every write, we would run into a
222
linear search problem through many commit-graph files. Instead, we use a merge
@@ -225,6 +228,7 @@ is determined by the merge strategy that the files should collapse to
228
the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
229
file.
230
231
+....
232
+---------------------+
233
| |
234
| (new commits) |
@@ -250,6 +254,7 @@ file.
254
| |
255
| |
256
+-----------------------+
257
+....
258
259
During this process, the commits to write are combined, sorted and we write the
260
contents to a temporary file, all while holding a `commit-graph-chain.lock`
@@ -257,14 +262,15 @@ lock-file. When the file is flushed, we rename it to `graph-{hash3}`
262
according to the computed `{hash3}`. Finally, we write the new chain data to
263
`commit-graph-chain.lock`:
264
260
-```
265
+----
266
{hash3}
267
{hash0}
263
-```
268
+----
269
270
We then close the lock-file.
271
267
-## Merge Strategy
272
+Merge Strategy
273
+~~~~~~~~~~~~~~
274
275
When writing a set of commits that do not exist in the commit-graph stack of
276
height N, we default to creating a new file at level N + 1. We then decide to
@@ -289,7 +295,8 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
295
number of commits) could be extracted into config settings for full
296
flexibility.
297
292
-## Handling Mixed Generation Number Chains
298
+Handling Mixed Generation Number Chains
299
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
300
301
With the introduction of generation number v2 and generation data chunk, the
302
following scenario is possible:
@@ -318,7 +325,8 @@ have corrected commit dates when written by compatible versions of Git. Thus,
325
rewriting split commit-graph as a single file (`--split=replace`) creates a
326
single layer with corrected commit dates.
327
321
-## Deleting graph-{hash} files
328
+Deleting graph-\{hash\} files
329
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330
331
After a new tip file is written, some `graph-{hash}` files may no longer
332
be part of a chain. It is important to remove these files from disk, eventually.
@@ -333,7 +341,8 @@ files whose modified times are older than a given expiry window. This window
341
defaults to zero, but can be changed using command-line arguments or a config
342
setting.
343
336
-## Chains across multiple object directories
344
+Chains across multiple object directories
345
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
346
347
In a repo with alternates, we look for the `commit-graph-chain` file starting
348
in the local object directory and then in each alternate. The first file that