mirror of
https://github.com/git-for-windows/git.git
synced 2026-02-04 12:24:55 -06:00
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>
This commit is contained in:
parent
45e8b7c2d4
commit
b770ed9545
@ -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
|
||||
@ -225,6 +228,7 @@ is determined by the merge strategy that the files should collapse to
|
||||
the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
|
||||
file.
|
||||
|
||||
....
|
||||
+---------------------+
|
||||
| |
|
||||
| (new commits) |
|
||||
@ -250,6 +254,7 @@ file.
|
||||
| |
|
||||
| |
|
||||
+-----------------------+
|
||||
....
|
||||
|
||||
During this process, the commits to write are combined, sorted and we write the
|
||||
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}`
|
||||
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 +295,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 +325,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 +341,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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user