docs: move pack format docs to man section 5
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the various documentation pertaining to the *.pack format and related files, and updating things that refer to it to link to the new location. By moving these we can properly link from the newly created gitformat-commit-graph to a gitformat-chunk-format page. Integrating "Documentation/technical/bitmap-format.txt" and "Documentation/technical/cruft-packs.txt" might logically be part of this change, but as those cover parts of the wider "pack format" (including associated files) that's documented outside of "Documentation/technical/pack-format.txt" let's leave those for now, subsequent commit(s) will address those. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Aug 4, 2022 at 18:28 UTC
977c47b46d4d4e5b25afd548c1bd6c108afad632
15 files changed
+68
-22
Documentation/Makefile
+2
-1
@@ -25,8 +25,10 @@ MAN1_TXT += gitweb.txt
25
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
26
MAN5_TXT += gitattributes.txt
27
MAN5_TXT += gitformat-bundle.txt
28
+MAN5_TXT += gitformat-chunk.txt
29
MAN5_TXT += gitformat-commit-graph.txt
30
MAN5_TXT += gitformat-index.txt
31
+MAN5_TXT += gitformat-pack.txt
32
MAN5_TXT += gitformat-signature.txt
33
MAN5_TXT += githooks.txt
34
MAN5_TXT += gitignore.txt
@@ -108,7 +110,6 @@ TECH_DOCS += technical/hash-function-transition
110
TECH_DOCS += technical/http-protocol
111
TECH_DOCS += technical/long-running-process-protocol
112
TECH_DOCS += technical/multi-pack-index
111
-TECH_DOCS += technical/pack-format
113
TECH_DOCS += technical/pack-heuristics
114
TECH_DOCS += technical/parallel-checkout
115
TECH_DOCS += technical/partial-clone
Documentation/config/pack.txt
+1
-1
@@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.
166
167
pack.writeReverseIndex::
168
When true, git will write a corresponding .rev file (see:
169
- link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
169
+ linkgit:gitformat-pack[5])
170
for each new packfile that it writes in all places except for
171
linkgit:git-fast-import[1] and in the bulk checkin mechanism.
172
Defaults to false.
Documentation/git-bundle.txt
+1
-2
@@ -57,8 +57,7 @@ size. That they're "thin" under the hood is merely noted here as a
57
curiosity, and as a reference to other documentation.
58
59
See linkgit:gitformat-bundle[5] for more details and the discussion of
60
-"thin pack" in link:technical/pack-format.html[the pack format
61
-documentation] for further details.
60
+"thin pack" in linkgit:gitformat-pack[5] for further details.
61
62
OPTIONS
63
-------
Documentation/git-multi-pack-index.txt
+2
-2
@@ -128,8 +128,8 @@ $ git multi-pack-index verify
128
SEE ALSO
129
--------
130
See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
131
-Document] and link:technical/pack-format.html[The Multi-Pack-Index
132
-Format] for more information on the multi-pack-index feature.
131
+Document] and linkgit:gitformat-pack[5] for more information on the
132
+multi-pack-index feature and its file format.
133
134
135
GIT
Documentation/gitformat-chunk.txt
renamed
+21
-4
@@ -1,11 +1,24 @@
1
-Chunk-based file formats
2
-========================
1
+gitformat-chunk(5)
2
+==================
3
+
4
+NAME
5
+----
6
+gitformat-chunk - Chunk-based file formats
7
+
8
+SYNOPSIS
9
+--------
10
+
11
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
12
+the pack format documentation in linkgit:gitformat-pack[5]).
13
+
14
+DESCRIPTION
15
+-----------
16
17
Some file formats in Git use a common concept of "chunks" to describe
18
sections of the file. This allows structured access to a large file by
19
scanning a small "table of contents" for the remaining data. This common
20
format is used by the `commit-graph` and `multi-pack-index` files. See
8
-link:technical/pack-format.html[the `multi-pack-index` format] and
21
+the `multi-pack-index` format in linkgit:gitformat-pack[5] and
22
the `commit-graph` format in linkgit:gitformat-commit-graph[5] for
23
how they use the chunks to describe structured data.
24
@@ -113,4 +126,8 @@ for future formats:
126
* *multi-pack-index:* see `write_midx_internal()` and `load_multi_pack_index()`
127
in `midx.c` for how the chunk-format API is used to write and
128
parse the multi-pack-index file format documented in
116
- link:technical/pack-format.html[the multi-pack-index file format].
129
+ the multi-pack-index file format section of linkgit:gitformat-pack[5].
130
+
131
+GIT
132
+---
133
+Part of the linkgit:git[1] suite
Documentation/gitformat-commit-graph.txt
+1
-1
@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.
75
ID appears at most once.
76
77
The CHUNK LOOKUP matches the table of contents from
78
- link:technical/chunk-format.html[the chunk-based file format].
78
+ the chunk-based file format, see linkgit:gitformat-chunk[5]
79
80
The remaining data in the body is described one chunk at a time, and
81
these chunks may be given in any order. Chunks are required unless
Documentation/gitformat-index.txt
+1
-1
@@ -141,7 +141,7 @@ Git index format
141
entry is encoded as if the path name for the previous entry is an
142
empty string). At the beginning of an entry, an integer N in the
143
variable width encoding (the same encoding as the offset is encoded
144
- for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
144
+ for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
145
by a NUL-terminated string S. Removing N bytes from the end of the
146
path name for the previous entry, and replacing it with the string S
147
yields the path name for this entry.
Documentation/gitformat-pack.txt
renamed
+31
-3
@@ -1,5 +1,29 @@
1
-Git pack format
2
-===============
1
+gitformat-pack(5)
2
+=================
3
+
4
+NAME
5
+----
6
+gitformat-pack - Git pack format
7
+
8
+
9
+SYNOPSIS
10
+--------
11
+[verse]
12
+$GIT_DIR/objects/pack/pack-*.{pack,idx}
13
+$GIT_DIR/objects/pack/pack-*.rev
14
+$GIT_DIR/objects/pack/multi-pack-index
15
+
16
+DESCRIPTION
17
+-----------
18
+
19
+The Git pack format is now Git stores most of its primary repository
20
+data. Over the lietime af a repository loose objects (if any) and
21
+smaller packs are consolidated into larger pack(s). See
22
+linkgit:git-gc[1] and linkgit:git-pack-objects[1].
23
+
24
+The pack format is also used over-the-wire, see
25
+e.g. linkgit:gitprotocol-v2[5], as well as being a part of
26
+other container formats in the case of linkgit:gitformat-bundle[5].
27
28
== Checksums and object IDs
29
@@ -356,7 +380,7 @@ CHUNK LOOKUP:
380
using the next chunk position if necessary.)
381
382
The CHUNK LOOKUP matches the table of contents from
359
- link:technical/chunk-format.html[the chunk-based file format].
383
+ the chunk-based file format, see linkgit:gitformat-chunk[5].
384
385
The remaining data in the body is described one chunk at a time, and
386
these chunks may be given in any order. Chunks are required unless
@@ -482,3 +506,7 @@ packs arranged in MIDX order (with the preferred pack coming first).
506
507
The MIDX's reverse index is stored in the optional 'RIDX' chunk within
508
the MIDX itself.
509
+
510
+GIT
511
+---
512
+Part of the linkgit:git[1] suite
Documentation/gitprotocol-pack.txt
+1
-1
@@ -467,7 +467,7 @@ Now that the client and server have finished negotiation about what
467
the minimal amount of data that needs to be sent to the client is, the server
468
will construct and send the required data in packfile format.
469
470
-See pack-format.txt for what the packfile itself actually looks like.
470
+See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.
471
472
If 'side-band' or 'side-band-64k' capabilities have been specified by
473
the client, the server will send the packfile data multiplexed.
Documentation/howto/recover-corrupted-object-harder.txt
+1
-1
@@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
68
has the git packed object header, which is variable-length. We want to
69
strip that off so we can start playing with the zlib data directly. You
70
can either work your way through it manually (the format is described in
71
-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
71
+linkgit:gitformat-pack[5]),
72
or you can walk through it in a debugger. I did the latter, creating a
73
valid pack like:
74
Documentation/technical/hash-function-transition.txt
+1
-1
@@ -205,7 +205,7 @@ SHA-1 content.
205
Object storage
206
~~~~~~~~~~~~~~
207
Loose objects use zlib compression and packed objects use the packed
208
-format described in Documentation/technical/pack-format.txt, just like
208
+format described in linkgit:gitformat-pack[5], just like
209
today. The content that is compressed and stored uses SHA-256 content
210
instead of SHA-1 content.
211
Documentation/user-manual.txt
+1
-1
@@ -3133,7 +3133,7 @@ those "loose" objects.
3133
You can save space and make Git faster by moving these loose objects in
3134
to a "pack file", which stores a group of objects in an efficient
3135
compressed format; the details of how pack files are formatted can be
3136
-found in link:technical/pack-format.html[pack format].
3136
+found in link:gitformat-pack[5].
3137
3138
To put the loose objects into a pack, just run git repack:
3139
cache.h
+1
-2
@@ -475,8 +475,7 @@ extern struct index_state the_index;
475
476
/*
477
* Values in this enum (except those outside the 3 bit range) are part
478
- * of pack file format. See Documentation/technical/pack-format.txt
479
- * for more information.
478
+ * of pack file format. See gitformat-pack(5) for more information.
479
*/
480
enum object_type {
481
OBJ_BAD = -1,
command-list.txt
+2
@@ -210,8 +210,10 @@ gitdiffcore guide
210
giteveryday guide
211
gitfaq guide
212
gitformat-bundle developerinterfaces
213
+gitformat-chunk developerinterfaces
214
gitformat-commit-graph developerinterfaces
215
gitformat-index developerinterfaces
216
+gitformat-pack developerinterfaces
217
gitformat-signature developerinterfaces
218
gitglossary guide
219
githooks userinterfaces
pack-revindex.h
+1
-1
@@ -22,7 +22,7 @@
22
*
23
* - pack position refers to an object's position within a non-existent pack
24
* described by the MIDX. The pack structure is described in
25
- * Documentation/technical/pack-format.txt.
25
+ * gitformat-pack(5).
26
*
27
* It is effectively a concatanation of all packs in the MIDX (ordered by
28
* their numeric ID within the MIDX) in their original order within each