| Message ID | patch-v8-06.12-df3ef265d45-20220804T162138Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 8cbace93d270dc49f007a2c1922769240a22eca5 |
| Headers | show |
| Series | docs: create & use "(user|developer) interfaces" categories | expand |
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > Continue the move of existing Documentation/technical/* protocol and > file-format documentation into our main documentation space. > ... > diff --git a/command-list.txt b/command-list.txt > index 1950c4ccd9c..3afcfcd35f0 100644 > --- a/command-list.txt > +++ b/command-list.txt > @@ -210,6 +210,7 @@ gitdiffcore guide > giteveryday guide > gitfaq guide > gitformat-bundle developerinterfaces > +gitformat-commit-graph developerinterfaces > gitglossary guide > githooks userinterfaces > gitignore userinterfaces This round the entire patch looks good to me, including this file.
On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote: > Continue the move of existing Documentation/technical/* protocol and > file-format documentation into our main documentation space. > > By moving the documentation for the commit-graph format into man > section 5 and the new "developerinterfaces" category. This change is > split from subsequent commits due to the relatively large amount of > ASCIIDOC formatting changes that are required. So after this series I got a couple of gitformat-* manpages, but, alas, most of them render improperly: a lot of paragraphs are for some reason fixed width even in a fullscreen terminal window, and their width is more than 80 chars, so they are rather awkward in a standard-width terminal. This also affects the html version, where those paragraphs are rendered with a fixed-width font. > Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > --- > Documentation/Makefile | 1 + > Documentation/git-commit-graph.txt | 5 ++ > ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------ > Documentation/technical/chunk-format.txt | 4 +- > command-list.txt | 1 + > 5 files changed, 41 insertions(+), 17 deletions(-) > rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%) > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 1a4a545f44a..e7bd72bb84e 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt > # man5 / man7 guides (note: new guides should also be added to command-list.txt) > MAN5_TXT += gitattributes.txt > MAN5_TXT += gitformat-bundle.txt > +MAN5_TXT += gitformat-commit-graph.txt > MAN5_TXT += githooks.txt > MAN5_TXT += gitignore.txt > MAN5_TXT += gitmailmap.txt > diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt > index e1f48c95b3c..047decdb65b 100644 > --- a/Documentation/git-commit-graph.txt > +++ b/Documentation/git-commit-graph.txt > @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append > ------------------------------------------------ > > > +FILE FORMAT > +----------- > + > +see linkgit:gitformat-commit-graph[5]. > + > GIT > --- > Part of the linkgit:git[1] suite > diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt > similarity index 88% > rename from Documentation/technical/commit-graph-format.txt > rename to Documentation/gitformat-commit-graph.txt > index 484b185ba98..108dc2295c0 100644 > --- a/Documentation/technical/commit-graph-format.txt > +++ b/Documentation/gitformat-commit-graph.txt > @@ -1,5 +1,18 @@ > -Git commit graph format > -======================= > +gitformat-commit-graph(5) > +========================= > + > +NAME > +---- > +gitformat-commit-graph - Git commit graph format > + > +SYNOPSIS > +-------- > +[verse] > +$GIT_DIR/objects/info/commit-graph > +$GIT_DIR/objects/info/commit-graphs/* > + > +DESCRIPTION > +----------- > > The Git commit graph stores a list of commit OIDs and some associated > metadata, including: > @@ -30,7 +43,7 @@ and hash type. > > All multi-byte numbers are in network byte order. > > -HEADER: > +=== HEADER: > > 4-byte signature: > The signature is: {'C', 'G', 'P', 'H'} > @@ -52,7 +65,7 @@ HEADER: > We infer the length (H*B) of the Base Graphs chunk > from this value. > > -CHUNK LOOKUP: > +=== CHUNK LOOKUP: > > (C + 1) * 12 bytes listing the table of contents for the chunks: > First 4 bytes describe the chunk id. Value 0 is a terminating label. > @@ -68,17 +81,17 @@ CHUNK LOOKUP: > these chunks may be given in any order. Chunks are required unless > otherwise specified. > > -CHUNK DATA: > +=== CHUNK DATA: > > - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) > +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) > The ith entry, F[i], stores the number of OIDs with first > byte at most i. Thus F[255] stores the total > number of commits (N). > > - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) > +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) > The OIDs for all commits in the graph, sorted in ascending order. > > - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) > +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) > * The first H bytes are for the OID of the root tree. > * The next 8 bytes are for the positions of the first two parents > of the ith commit. Stores value 0x70000000 if no parent in that > @@ -93,7 +106,7 @@ CHUNK DATA: > 2 bits of the lowest byte, storing the 33rd and 34th bit of the > commit time. > > - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] > +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] > * This list of 4-byte values store corrected commit date offsets for the > commits, arranged in the same order as commit data chunk. > * If the corrected commit date offset cannot be stored within 31 bits, > @@ -104,7 +117,7 @@ CHUNK DATA: > by compatible versions of Git and in case of split commit-graph chains, > the topmost layer also has Generation Data chunk. > > - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] > +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] > * This list of 8-byte values stores the corrected commit date offsets > for commits with corrected commit date offsets that cannot be > stored within 31 bits. > @@ -112,7 +125,7 @@ CHUNK DATA: > chunk is present and atleast one corrected commit date offset cannot > be stored within 31 bits. > > - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] > +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] > This list of 4-byte values store the second through nth parents for > all octopus merges. The second parent value in the commit data stores > an array position within this list along with the most-significant bit > @@ -120,14 +133,14 @@ CHUNK DATA: > positions for the parents until reaching a value with the most-significant > bit on. The other bits correspond to the position of the last parent. > > - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] > +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] > * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters > from commit 0 to commit i (inclusive) in lexicographic order. The Bloom > filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header > length), where BIDX[-1] is 0. > * The BIDX chunk is ignored if the BDAT chunk is not present. > > - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] > +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] > * It starts with header consisting of three unsigned 32-bit integers: > - Version of the hash algorithm being used. We currently only support > value 1 which corresponds to the 32-bit version of the murmur3 hash > @@ -147,13 +160,13 @@ CHUNK DATA: > of length one, with either all bits set to zero or one respectively. > * The BDAT chunk is present if and only if BIDX is present. > > - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] > +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] > This list of H-byte hashes describe a set of B commit-graph files that > form a commit-graph chain. The graph position for the ith commit in this > file's OID Lookup chunk is equal to i plus the number of commits in all > base graphs. If B is non-zero, this chunk must exist. > > -TRAILER: > +=== TRAILER: > > H-byte HASH-checksum of all of the above. > > @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote > possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By > changing the IDs, newer versions of Git will silently ignore those older > chunks and write the new information without trusting the incorrect data. > + > +GIT > +--- > +Part of the linkgit:git[1] suite > diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt > index 593614fceda..f36ce42f37c 100644 > --- a/Documentation/technical/chunk-format.txt > +++ b/Documentation/technical/chunk-format.txt > @@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by > scanning a small "table of contents" for the remaining data. This common > format is used by the `commit-graph` and `multi-pack-index` files. See > link:technical/pack-format.html[the `multi-pack-index` format] and > -link:technical/commit-graph-format.html[the `commit-graph` format] for > +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for > how they use the chunks to describe structured data. > > A chunk-based file format begins with some header information custom to > @@ -108,7 +108,7 @@ for future formats: > * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()` > in `commit-graph.c` for how the chunk-format API is used to write and > parse the commit-graph file format documented in > - link:technical/commit-graph-format.html[the commit-graph file format]. > + the commit-graph file format in linkgit:gitformat-commit-graph[5]. > > * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` > in `midx.c` for how the chunk-format API is used to write and > diff --git a/command-list.txt b/command-list.txt > index 1950c4ccd9c..3afcfcd35f0 100644 > --- a/command-list.txt > +++ b/command-list.txt > @@ -210,6 +210,7 @@ gitdiffcore guide > giteveryday guide > gitfaq guide > gitformat-bundle developerinterfaces > +gitformat-commit-graph developerinterfaces > gitglossary guide > githooks userinterfaces > gitignore userinterfaces > -- > 2.37.1.1233.g61622908797 >
On Tue, Nov 08 2022, SZEDER Gábor wrote: > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote: >> Continue the move of existing Documentation/technical/* protocol and >> file-format documentation into our main documentation space. >> >> By moving the documentation for the commit-graph format into man >> section 5 and the new "developerinterfaces" category. This change is >> split from subsequent commits due to the relatively large amount of >> ASCIIDOC formatting changes that are required. > > So after this series I got a couple of gitformat-* manpages, but, > alas, most of them render improperly: a lot of paragraphs are for some > reason fixed width even in a fullscreen terminal window, and their > width is more than 80 chars, so they are rather awkward in a > standard-width terminal. This also affects the html version, where > those paragraphs are rendered with a fixed-width font. Do you have examples of that, and are these cases where the formatting was different before the move from Documentation/technical/* I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and may have missed some cases, but I think that was also the case before...
On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote: > > On Tue, Nov 08 2022, SZEDER Gábor wrote: > > > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote: > >> Continue the move of existing Documentation/technical/* protocol and > >> file-format documentation into our main documentation space. > >> > >> By moving the documentation for the commit-graph format into man > >> section 5 and the new "developerinterfaces" category. This change is > >> split from subsequent commits due to the relatively large amount of > >> ASCIIDOC formatting changes that are required. > > > > So after this series I got a couple of gitformat-* manpages, but, > > alas, most of them render improperly: a lot of paragraphs are for some > > reason fixed width even in a fullscreen terminal window, and their > > width is more than 80 chars, so they are rather awkward in a > > standard-width terminal. This also affects the html version, where > > those paragraphs are rendered with a fixed-width font. > > Do you have examples of that Here's the description of two chunks copy-pasted from 'man gitformat-commit-graph' in a full-screen terminal, the first being properly formatted (i.e. line length adjusted to the width of the terminal), the latter having fixed-width: Generation Data Overflow (ID: {G, D, O, 2 }) [Optional] • This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. • Generation Data Overflow chunk is present only when Generation Data chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. Extra Edge List (ID: {E, D, G, E}) [Optional] This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit on. Starting at that array position, iterate through this list of commit positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. There are similar formating issues in 'gitformat-index' and 'gitformat-pack' as well. I can see these both with AsciiDoc and Asciidoctor. > and are these cases where the formatting > was different before the move from Documentation/technical/* > > I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and > may have missed some cases, but I think that was also the case before... I'm not sure about "before", because 'make man' never built and installed these gitformat-* manpages before this series.
On Tue, Nov 08 2022, SZEDER Gábor wrote: > On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote: >> >> On Tue, Nov 08 2022, SZEDER Gábor wrote: >> >> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote: >> >> Continue the move of existing Documentation/technical/* protocol and >> >> file-format documentation into our main documentation space. >> >> >> >> By moving the documentation for the commit-graph format into man >> >> section 5 and the new "developerinterfaces" category. This change is >> >> split from subsequent commits due to the relatively large amount of >> >> ASCIIDOC formatting changes that are required. >> > >> > So after this series I got a couple of gitformat-* manpages, but, >> > alas, most of them render improperly: a lot of paragraphs are for some >> > reason fixed width even in a fullscreen terminal window, and their >> > width is more than 80 chars, so they are rather awkward in a >> > standard-width terminal. This also affects the html version, where >> > those paragraphs are rendered with a fixed-width font. >> >> Do you have examples of that > > Here's the description of two chunks copy-pasted from 'man > gitformat-commit-graph' in a full-screen terminal, the first being > properly formatted (i.e. line length adjusted to the width of the > terminal), the latter having fixed-width: > > Generation Data Overflow (ID: {G, D, O, 2 }) [Optional] > • This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. > > • Generation Data Overflow chunk is present only when Generation Data chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. > > Extra Edge List (ID: {E, D, G, E}) [Optional] > This list of 4-byte values store the second through nth parents for > all octopus merges. The second parent value in the commit data stores > an array position within this list along with the most-significant bit > on. Starting at that array position, iterate through this list of commit > positions for the parents until reaching a value with the most-significant > bit on. The other bits correspond to the position of the last parent. > > There are similar formating issues in 'gitformat-index' and > 'gitformat-pack' as well. I can see these both with AsciiDoc and > Asciidoctor. Yeah, they look pretty bad. >> and are these cases where the formatting >> was different before the move from Documentation/technical/* >> >> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and >> may have missed some cases, but I think that was also the case before... > > I'm not sure about "before", because 'make man' never built and > installed these gitformat-* manpages before this series. In the case of "gitformat-commit-graph" there was never a "html" version of it before c0f6dd49f19 (Merge branch 'ab/tech-docs-to-help', 2022-08-14). But if you check out c0f6dd49f19^1 and: diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c9..d7a066a68d0 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -96,6 +96,7 @@ TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/bundle-format +TECH_DOCS += technical/commit-graph-format TECH_DOCS += technical/cruft-packs TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protoco Then "make html" you'll see what the formatting was like before. Here's generated versions of those & git-scm.com's version for comparison: https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/commit-graph-format.html https://git-scm.com/docs/gitformat-commit-graph https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/index-format.html https://git-scm.com/docs/gitformat-index https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/pack-format.html https://git-scm.com/docs/gitformat-pack They should obviously be fixed, but I left that out of scope of that series. If it was a fix-syntax-nits-while-at-it it would have been a lot longer, and some of it's in some pseudo-syntax that was never quite valid markdown. E.g. commit-graph-format.txt tried to use link:* syntax in block-quoted text. What I found *mostly* worked was to use "==" for sections, which e.g. for gitformat-commit-graph ends up formatting it nicely as long as it's followed by a bullet-point list, but as you show with "This lits of 4-byte..." that doesn't do the trick when it's not a list, instead it uses the literal formatting (which almost the entire body of the text used before). I think the most minimal way of fixing it is to de-indent the opening line of those sections, e.g.: diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt index 31cad585e23..84df4a3ed03 100644 --- a/Documentation/gitformat-commit-graph.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order. === CHUNK LOOKUP: - (C + 1) * 12 bytes listing the table of contents for the chunks: +(C + 1) * 12 bytes listing the table of contents for the chunks: First 4 bytes describe the chunk id. Value 0 is a terminating label. Other 8 bytes provide the byte-offset in current file for chunk to start. (Chunks are ordered contiguously in the file, so you can infer the length using the next chunk position if necessary.) Each chunk ID appears at most once. - The CHUNK LOOKUP matches the table of contents from +The CHUNK LOOKUP matches the table of contents from the chunk-based file format, see linkgit:gitformat-chunk[5] - The remaining data in the body is described one chunk at a time, and +The remaining data in the body is described one chunk at a time, and these chunks may be given in any order. Chunks are required unless otherwise specified. @@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order. be stored within 31 bits. ==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] - This list of 4-byte values store the second through nth parents for +This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit on. Starting at that array position, iterate through this list of commit Seems to fix those "flow" issues for me, i.e. it's now a normal paragraph, instead of a block-quoted fixed-width text.
diff --git a/Documentation/Makefile b/Documentation/Makefile index 1a4a545f44a..e7bd72bb84e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -25,6 +25,7 @@ MAN1_TXT += gitweb.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index e1f48c95b3c..047decdb65b 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -143,6 +143,11 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append ------------------------------------------------ +FILE FORMAT +----------- + +see linkgit:gitformat-commit-graph[5]. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/gitformat-commit-graph.txt similarity index 88% rename from Documentation/technical/commit-graph-format.txt rename to Documentation/gitformat-commit-graph.txt index 484b185ba98..108dc2295c0 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/gitformat-commit-graph.txt @@ -1,5 +1,18 @@ -Git commit graph format -======================= +gitformat-commit-graph(5) +========================= + +NAME +---- +gitformat-commit-graph - Git commit graph format + +SYNOPSIS +-------- +[verse] +$GIT_DIR/objects/info/commit-graph +$GIT_DIR/objects/info/commit-graphs/* + +DESCRIPTION +----------- The Git commit graph stores a list of commit OIDs and some associated metadata, including: @@ -30,7 +43,7 @@ and hash type. All multi-byte numbers are in network byte order. -HEADER: +=== HEADER: 4-byte signature: The signature is: {'C', 'G', 'P', 'H'} @@ -52,7 +65,7 @@ HEADER: We infer the length (H*B) of the Base Graphs chunk from this value. -CHUNK LOOKUP: +=== CHUNK LOOKUP: (C + 1) * 12 bytes listing the table of contents for the chunks: First 4 bytes describe the chunk id. Value 0 is a terminating label. @@ -68,17 +81,17 @@ CHUNK LOOKUP: these chunks may be given in any order. Chunks are required unless otherwise specified. -CHUNK DATA: +=== CHUNK DATA: - OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) +==== OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes) The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total number of commits (N). - OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) +==== OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes) The OIDs for all commits in the graph, sorted in ascending order. - Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) +==== Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes) * The first H bytes are for the OID of the root tree. * The next 8 bytes are for the positions of the first two parents of the ith commit. Stores value 0x70000000 if no parent in that @@ -93,7 +106,7 @@ CHUNK DATA: 2 bits of the lowest byte, storing the 33rd and 34th bit of the commit time. - Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] +==== Generation Data (ID: {'G', 'D', 'A', '2' }) (N * 4 bytes) [Optional] * This list of 4-byte values store corrected commit date offsets for the commits, arranged in the same order as commit data chunk. * If the corrected commit date offset cannot be stored within 31 bits, @@ -104,7 +117,7 @@ CHUNK DATA: by compatible versions of Git and in case of split commit-graph chains, the topmost layer also has Generation Data chunk. - Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] +==== Generation Data Overflow (ID: {'G', 'D', 'O', '2' }) [Optional] * This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits. @@ -112,7 +125,7 @@ CHUNK DATA: chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits. - Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] +==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional] This list of 4-byte values store the second through nth parents for all octopus merges. The second parent value in the commit data stores an array position within this list along with the most-significant bit @@ -120,14 +133,14 @@ CHUNK DATA: positions for the parents until reaching a value with the most-significant bit on. The other bits correspond to the position of the last parent. - Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] +==== Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters from commit 0 to commit i (inclusive) in lexicographic order. The Bloom filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header length), where BIDX[-1] is 0. * The BIDX chunk is ignored if the BDAT chunk is not present. - Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] +==== Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] * It starts with header consisting of three unsigned 32-bit integers: - Version of the hash algorithm being used. We currently only support value 1 which corresponds to the 32-bit version of the murmur3 hash @@ -147,13 +160,13 @@ CHUNK DATA: of length one, with either all bits set to zero or one respectively. * The BDAT chunk is present if and only if BIDX is present. - Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] +==== Base Graphs List (ID: {'B', 'A', 'S', 'E'}) [Optional] This list of H-byte hashes describe a set of B commit-graph files that form a commit-graph chain. The graph position for the ith commit in this file's OID Lookup chunk is equal to i plus the number of commits in all base graphs. If B is non-zero, this chunk must exist. -TRAILER: +=== TRAILER: H-byte HASH-checksum of all of the above. @@ -164,3 +177,7 @@ the number '2' in their chunk IDs because a previous version of Git wrote possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By changing the IDs, newer versions of Git will silently ignore those older chunks and write the new information without trusting the incorrect data. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/chunk-format.txt b/Documentation/technical/chunk-format.txt index 593614fceda..f36ce42f37c 100644 --- a/Documentation/technical/chunk-format.txt +++ b/Documentation/technical/chunk-format.txt @@ -6,7 +6,7 @@ sections of the file. This allows structured access to a large file by scanning a small "table of contents" for the remaining data. This common format is used by the `commit-graph` and `multi-pack-index` files. See link:technical/pack-format.html[the `multi-pack-index` format] and -link:technical/commit-graph-format.html[the `commit-graph` format] for +the `commit-graph` format in linkgit:gitformat-commit-graph[5] for how they use the chunks to describe structured data. A chunk-based file format begins with some header information custom to @@ -108,7 +108,7 @@ for future formats: * *commit-graph:* see `write_commit_graph_file()` and `parse_commit_graph()` in `commit-graph.c` for how the chunk-format API is used to write and parse the commit-graph file format documented in - link:technical/commit-graph-format.html[the commit-graph file format]. + the commit-graph file format in linkgit:gitformat-commit-graph[5]. * *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()` in `midx.c` for how the chunk-format API is used to write and diff --git a/command-list.txt b/command-list.txt index 1950c4ccd9c..3afcfcd35f0 100644 --- a/command-list.txt +++ b/command-list.txt @@ -210,6 +210,7 @@ gitdiffcore guide giteveryday guide gitfaq guide gitformat-bundle developerinterfaces +gitformat-commit-graph developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the documentation for the commit-graph format into man section 5 and the new "developerinterfaces" category. This change is split from subsequent commits due to the relatively large amount of ASCIIDOC formatting changes that are required. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/Makefile | 1 + Documentation/git-commit-graph.txt | 5 ++ ...-format.txt => gitformat-commit-graph.txt} | 47 +++++++++++++------ Documentation/technical/chunk-format.txt | 4 +- command-list.txt | 1 + 5 files changed, 41 insertions(+), 17 deletions(-) rename Documentation/{technical/commit-graph-format.txt => gitformat-commit-graph.txt} (88%)