freshlybakedca.ke
Git fork
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>
authored by
Ramsay Jones
and committed by
Junio C Hamano
b770ed95
45e8b7c2
+19
-10
Documentation/technical/commit-graph.adoc
+19
-10
Documentation/technical/commit-graph.adoc
···
39
Values 1-4 satisfy the requirements of parse_commit_gently().
40
41
There are two definitions of generation number:
42
1. Corrected committer dates (generation number v2)
43
2. Topological levels (generation number v1)
44
···
158
we enable fast writes of new commit data without rewriting the entire commit
159
history -- at least, most of the time.
160
161
-
## File Layout
162
163
A commit-graph chain uses multiple files, and we use a fixed naming convention
164
to organize these files. Each commit-graph file has a name
···
170
171
For example, if the `commit-graph-chain` file contains the lines
172
173
-
```
174
{hash0}
175
{hash1}
176
{hash2}
177
-
```
178
179
then the commit-graph chain looks like the following diagram:
180
···
213
`graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
214
`{hash0}` and `{hash1}`.
215
216
-
## Merging commit-graph files
217
218
If we only added a new commit-graph file on every write, we would run into a
219
linear search problem through many commit-graph files. Instead, we use a merge
···
225
the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
226
file.
227
228
+---------------------+
229
| |
230
| (new commits) |
···
250
| |
251
| |
252
+-----------------------+
253
254
During this process, the commits to write are combined, sorted and we write the
255
contents to a temporary file, all while holding a `commit-graph-chain.lock`
···
257
according to the computed `{hash3}`. Finally, we write the new chain data to
258
`commit-graph-chain.lock`:
259
260
-
```
261
{hash3}
262
{hash0}
263
-
```
264
265
We then close the lock-file.
266
267
-
## Merge Strategy
268
269
When writing a set of commits that do not exist in the commit-graph stack of
270
height N, we default to creating a new file at level N + 1. We then decide to
···
289
number of commits) could be extracted into config settings for full
290
flexibility.
291
292
-
## Handling Mixed Generation Number Chains
293
294
With the introduction of generation number v2 and generation data chunk, the
295
following scenario is possible:
···
318
rewriting split commit-graph as a single file (`--split=replace`) creates a
319
single layer with corrected commit dates.
320
321
-
## Deleting graph-{hash} files
322
323
After a new tip file is written, some `graph-{hash}` files may no longer
324
be part of a chain. It is important to remove these files from disk, eventually.
···
333
defaults to zero, but can be changed using command-line arguments or a config
334
setting.
335
336
-
## Chains across multiple object directories
337
338
In a repo with alternates, we look for the `commit-graph-chain` file starting
339
in the local object directory and then in each alternate. The first file that
···
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
···
159
we enable fast writes of new commit data without rewriting the entire commit
160
history -- at least, most of the time.
161
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
···
172
173
For example, if the `commit-graph-chain` file contains the lines
174
175
+
----
176
{hash0}
177
{hash1}
178
{hash2}
179
+
----
180
181
then the commit-graph chain looks like the following diagram:
182
···
215
`graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
216
`{hash0}` and `{hash1}`.
217
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
···
228
the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
229
file.
230
231
+
....
232
+---------------------+
233
| |
234
| (new commits) |
···
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`
···
262
according to the computed `{hash3}`. Finally, we write the new chain data to
263
`commit-graph-chain.lock`:
264
265
+
----
266
{hash3}
267
{hash0}
268
+
----
269
270
We then close the lock-file.
271
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
···
295
number of commits) could be extracted into config settings for full
296
flexibility.
297
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:
···
325
rewriting split commit-graph as a single file (`--split=replace`) creates a
326
single layer with corrected commit dates.
327
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.
···
341
defaults to zero, but can be changed using command-line arguments or a config
342
setting.
343
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