freshlybakedca.ke / git
Git fork
fork atom

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