Continue the move of existing Documentation/technical/* protocol and
file-format documentation into our main documentation space.
By moving these we can properly link from the newly created
gitformat-commit-graph do to a gitformat-chunk-format manpage we build
by default. Let's also move the rest over for consistency.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx>
---
Documentation/Makefile | 6 ++-
...bitmap-format.txt => gitformat-bitmap.txt} | 38 +++++++++++++++----
.../chunk-format.txt => gitformat-chunk.txt} | 21 +++++++++-
Documentation/gitformat-commit-graph.txt | 2 +-
.../index-format.txt => gitformat-index.txt} | 20 +++++++++-
...ure-format.txt => gitformat-signature.txt} | 21 ++++++++--
Documentation/technical/pack-format.txt | 2 +-
command-list.txt | 4 ++
8 files changed, 97 insertions(+), 17 deletions(-)
rename Documentation/{technical/bitmap-format.txt => gitformat-bitmap.txt} (91%)
rename Documentation/{technical/chunk-format.txt => gitformat-chunk.txt} (94%)
rename Documentation/{technical/index-format.txt => gitformat-index.txt} (98%)
rename Documentation/{technical/signature-format.txt => gitformat-signature.txt} (96%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index ba587b75a51..f8a84173667 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,12 +21,16 @@ 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-bitmap.txt
MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
MAN5_TXT += gitformat-pack-protocol.txt
MAN5_TXT += gitformat-protocol-capabilities.txt
MAN5_TXT += gitformat-protocol-common.txt
MAN5_TXT += gitformat-protocol-v2.txt
+MAN5_TXT += gitformat-signature.txt
MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmailmap.txt
@@ -98,7 +102,6 @@ TECH_DOCS += MyFirstObjectWalk
TECH_DOCS += SubmittingPatches
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/http-protocol
-TECH_DOCS += technical/index-format
TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
TECH_DOCS += technical/pack-format
@@ -109,7 +112,6 @@ TECH_DOCS += technical/racy-git
TECH_DOCS += technical/reftable
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
-TECH_DOCS += technical/signature-format
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/gitformat-bitmap.txt
similarity index 91%
rename from Documentation/technical/bitmap-format.txt
rename to Documentation/gitformat-bitmap.txt
index 04b3ec21785..b239dc5cbe1 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/gitformat-bitmap.txt
@@ -1,7 +1,25 @@
-GIT bitmap v1 format
-====================
+gitformat-bitmap(5)
+===================
-== Pack and multi-pack bitmaps
+NAME
+----
+gitformat-bitmap - The bitmap file format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/pack/*.bitmap
+
+DESCRIPTION
+-----------
+
+Bitmaps are a file format associated with .pack files. See
+link:technical/pack-format.html[the pack format documentation] and
+linkgit:git-pack-objects[1].
+
+== GIT bitmap v1 format
+
+=== Pack and multi-pack bitmaps
Bitmaps store reachability information about the set of objects in a packfile,
or a multi-pack index (MIDX). The former is defined obviously, and the latter is
@@ -37,7 +55,7 @@ Certain bitmap extensions are supported (see: Appendix B). No extensions are
required for bitmaps corresponding to packfiles. For bitmaps that correspond to
MIDXs, both the bit-cache and rev-cache extensions are required.
-== On-disk format
+=== On-disk format
- A header appears at the beginning:
@@ -131,7 +149,8 @@ MIDXs, both the bit-cache and rev-cache extensions are required.
- The compressed bitmap itself, see Appendix A.
-== Appendix A: Serialization format for an EWAH bitmap
+Appendix A - Serialization format for an EWAH bitmap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
library, making them backwards compatible with the JGit
@@ -179,13 +198,14 @@ chunk. For efficient appending to the bitstream, the EWAH stores a
pointer to the last RLW in the stream.
-== Appendix B: Optional Bitmap Sections
+Appendix B - Optional Bitmap Sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These sections may or may not be present in the `.bitmap` file; their
presence is indicated by the header flags section described above.
Name-hash cache
----------------
+~~~~~~~~~~~~~~~
If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
a cache of 32-bit values, one per object in the pack/MIDX. The value at
@@ -205,3 +225,7 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
If implementations want to choose a different hashing scheme, they are
free to do so, but MUST allocate a new header flag (because comparing
hashes made under two different schemes would be pointless).
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/chunk-format.txt b/Documentation/gitformat-chunk.txt
similarity index 94%
rename from Documentation/technical/chunk-format.txt
rename to Documentation/gitformat-chunk.txt
index f36ce42f37c..8ddf21e3277 100644
--- a/Documentation/technical/chunk-format.txt
+++ b/Documentation/gitformat-chunk.txt
@@ -1,5 +1,18 @@
-Chunk-based file formats
-========================
+gitformat-chunk(5)
+==================
+
+NAME
+----
+gitformat-chunk - Chunk-based file formats
+
+SYNOPSIS
+--------
+
+Used by linkgit:gitformat-commit-graph[5] and the "MIDX" format (see
+link:technical/pack-format.html[the pack format documentation]).
+
+DESCRIPTION
+-----------
Some file formats in Git use a common concept of "chunks" to describe
sections of the file. This allows structured access to a large file by
@@ -114,3 +127,7 @@ for future formats:
in `midx.c` for how the chunk-format API is used to write and
parse the multi-pack-index file format documented in
link:technical/pack-format.html[the multi-pack-index file format].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 25eb131dcd2..5f839eda058 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -75,7 +75,7 @@ All multi-byte numbers are in network byte order.
ID appears at most once.
The CHUNK LOOKUP matches the table of contents from
- link:technical/chunk-format.html[the chunk-based file format].
+ the chunk-based file format, see linkgit:gitformat-chunk[5]
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
diff --git a/Documentation/technical/index-format.txt b/Documentation/gitformat-index.txt
similarity index 98%
rename from Documentation/technical/index-format.txt
rename to Documentation/gitformat-index.txt
index 65da0daaa56..41491d2a075 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/gitformat-index.txt
@@ -1,5 +1,19 @@
+gitformat-index(5)
+==================
+
+NAME
+----
+gitformat-index - Git index format
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/index
+
+DESCRIPTION
+-----------
+
Git index format
-================
== The Git index file has the following format
@@ -404,3 +418,7 @@ The remaining data of each directory block is grouped by type:
with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
tools should avoid interacting with a sparse index unless they understand
this extension.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/signature-format.txt b/Documentation/gitformat-signature.txt
similarity index 96%
rename from Documentation/technical/signature-format.txt
rename to Documentation/gitformat-signature.txt
index 166721be6f6..a249869fafa 100644
--- a/Documentation/technical/signature-format.txt
+++ b/Documentation/gitformat-signature.txt
@@ -1,7 +1,18 @@
-Git signature format
-====================
+gitformat-signature(5)
+======================
-== Overview
+NAME
+----
+gitformat-signature - Git cryptographic signature formats
+
+SYNOPSIS
+--------
+[verse]
+<[tag|commit] object header(s)>
+<over-the-wire protocol>
+
+DESCRIPTION
+-----------
Git uses cryptographic signatures in various places, currently objects (tags,
commits, mergetags) and transactions (pushes). In every case, the command which
@@ -200,3 +211,7 @@ Date: Wed Jun 15 09:13:29 2016 +0000
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
----
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index 8d2f42f29e5..79cc83aead0 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -337,7 +337,7 @@ CHUNK LOOKUP:
using the next chunk position if necessary.)
The CHUNK LOOKUP matches the table of contents from
- link:technical/chunk-format.html[the chunk-based file format].
+ the chunk-based file format, see linkgit:gitformat-chunk[5].
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
diff --git a/command-list.txt b/command-list.txt
index f4d1f9c31b1..42093fd5a07 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -207,12 +207,16 @@ gitcvs-migration guide
gitdiffcore guide
giteveryday guide
gitfaq guide
+gitformat-bitmap gitformats
gitformat-bundle gitformats
+gitformat-chunk gitformats
gitformat-commit-graph gitformats
+gitformat-index gitformats
gitformat-pack-protocol gitformats
gitformat-protocol-capabilities gitformats
gitformat-protocol-common gitformats
gitformat-protocol-v2 gitformats
+gitformat-signature gitformats
gitglossary guide
githooks userformats
gitignore userformats
--
2.34.1.929.ge922d848c7a
