Merge branch 'ab/tech-docs-to-help'
Expose a lot of "tech docs" via "git help" interface. * ab/tech-docs-to-help: docs: move http-protocol docs to man section 5 docs: move cruft pack docs to gitformat-pack docs: move pack format docs to man section 5 docs: move signature docs to man section 5 docs: move index format docs to man section 5 docs: move protocol-related docs to man section 5 docs: move commit-graph format docs to man section 5 git docs: add a category for file formats, protocols and interfaces git docs: add a category for user-facing file, repo and command UX git help doc: use "<doc>" instead of "<guide>" help.c: remove common category behavior from drop_prefix() behavior help.c: refactor drop_prefix() to use a "switch" statement"
This commit is contained in:
Junio C Hamano
commit
c0f6dd49f1
@ -24,10 +24,21 @@ 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-chunk.txt
|
||||
MAN5_TXT += gitformat-commit-graph.txt
|
||||
MAN5_TXT += gitformat-index.txt
|
||||
MAN5_TXT += gitformat-pack.txt
|
||||
MAN5_TXT += gitformat-signature.txt
|
||||
MAN5_TXT += githooks.txt
|
||||
MAN5_TXT += gitignore.txt
|
||||
MAN5_TXT += gitmailmap.txt
|
||||
MAN5_TXT += gitmodules.txt
|
||||
MAN5_TXT += gitprotocol-capabilities.txt
|
||||
MAN5_TXT += gitprotocol-common.txt
|
||||
MAN5_TXT += gitprotocol-http.txt
|
||||
MAN5_TXT += gitprotocol-pack.txt
|
||||
MAN5_TXT += gitprotocol-v2.txt
|
||||
MAN5_TXT += gitrepository-layout.txt
|
||||
MAN5_TXT += gitweb.conf.txt
|
||||
|
||||
@ -95,26 +106,16 @@ TECH_DOCS += MyFirstObjectWalk
|
||||
TECH_DOCS += SubmittingPatches
|
||||
TECH_DOCS += ToolsForGit
|
||||
TECH_DOCS += technical/bitmap-format
|
||||
TECH_DOCS += technical/bundle-format
|
||||
TECH_DOCS += technical/cruft-packs
|
||||
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
|
||||
TECH_DOCS += technical/pack-heuristics
|
||||
TECH_DOCS += technical/pack-protocol
|
||||
TECH_DOCS += technical/parallel-checkout
|
||||
TECH_DOCS += technical/partial-clone
|
||||
TECH_DOCS += technical/protocol-capabilities
|
||||
TECH_DOCS += technical/protocol-common
|
||||
TECH_DOCS += technical/protocol-v2
|
||||
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
|
||||
@ -290,6 +291,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
|
||||
cmds-synchingrepositories.txt \
|
||||
cmds-synchelpers.txt \
|
||||
cmds-guide.txt \
|
||||
cmds-developerinterfaces.txt \
|
||||
cmds-userinterfaces.txt \
|
||||
cmds-purehelpers.txt \
|
||||
cmds-foreignscminterface.txt
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
lsrefs.unborn::
|
||||
May be "advertise" (the default), "allow", or "ignore". If "advertise",
|
||||
the server will respond to the client sending "unborn" (as described in
|
||||
protocol-v2.txt) and will advertise support for this feature during the
|
||||
linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the
|
||||
protocol v2 capability advertisement. "allow" is the same as
|
||||
"advertise" except that the server will not advertise support for this
|
||||
feature; this is useful for load-balanced servers that cannot be
|
||||
|
||||
@ -166,7 +166,7 @@ permuted into their appropriate location when writing a new bitmap.
|
||||
|
||||
pack.writeReverseIndex::
|
||||
When true, git will write a corresponding .rev file (see:
|
||||
link:../technical/pack-format.html[Documentation/technical/pack-format.txt])
|
||||
linkgit:gitformat-pack[5])
|
||||
for each new packfile that it writes in all places except for
|
||||
linkgit:git-fast-import[1] and in the bulk checkin mechanism.
|
||||
Defaults to false.
|
||||
|
||||
@ -58,6 +58,6 @@ protocol.version::
|
||||
* `1` - the original wire protocol with the addition of a version string
|
||||
in the initial response from the server.
|
||||
|
||||
* `2` - link:technical/protocol-v2.html[wire protocol version 2].
|
||||
* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].
|
||||
|
||||
--
|
||||
|
||||
@ -56,10 +56,8 @@ using "thin packs", bundles created using exclusions are smaller in
|
||||
size. That they're "thin" under the hood is merely noted here as a
|
||||
curiosity, and as a reference to other documentation.
|
||||
|
||||
See link:technical/bundle-format.html[the `bundle-format`
|
||||
documentation] for more details and the discussion of "thin pack" in
|
||||
link:technical/pack-format.html[the pack format documentation] for
|
||||
further details.
|
||||
See linkgit:gitformat-bundle[5] for more details and the discussion of
|
||||
"thin pack" in linkgit:gitformat-pack[5] for further details.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
@ -77,7 +75,7 @@ verify <file>::
|
||||
commits exist and are fully linked in the current repository.
|
||||
Then, 'git bundle' prints a list of missing commits, if any.
|
||||
Finally, information about additional capabilities, such as "object
|
||||
filter", is printed. See "Capabilities" in link:technical/bundle-format.html
|
||||
filter", is printed. See "Capabilities" in linkgit:gitformat-bundle[5]
|
||||
for more information. The exit code is zero for success, but will
|
||||
be nonzero if the bundle file is invalid.
|
||||
|
||||
@ -337,6 +335,11 @@ You can also see what references it offers:
|
||||
$ git ls-remote mybundle
|
||||
----------------
|
||||
|
||||
FILE FORMAT
|
||||
-----------
|
||||
|
||||
See linkgit:gitformat-bundle[5].
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
|
||||
@ -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
|
||||
|
||||
@ -9,14 +9,16 @@ SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
|
||||
'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
|
||||
'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
|
||||
'git help' [-g|--guides]
|
||||
'git help' [-c|--config]
|
||||
'git help' [--user-interfaces]
|
||||
'git help' [--developer-interfaces]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
|
||||
With no options and no '<command>' or '<doc>' given, the synopsis of the 'git'
|
||||
command and a list of the most commonly used Git commands are printed
|
||||
on the standard output.
|
||||
|
||||
@ -26,8 +28,8 @@ printed on the standard output.
|
||||
If the option `--guides` or `-g` is given, a list of the
|
||||
Git concept guides is also printed on the standard output.
|
||||
|
||||
If a command, or a guide, is given, a manual page for that command or
|
||||
guide is brought up. The 'man' program is used by default for this
|
||||
If a command or other documentation is given, the relevant manual page
|
||||
will be brought up. The 'man' program is used by default for this
|
||||
purpose, but this can be overridden by other options or configuration
|
||||
variables.
|
||||
|
||||
@ -69,6 +71,23 @@ OPTIONS
|
||||
--guides::
|
||||
Prints a list of the Git concept guides on the standard output.
|
||||
|
||||
--user-interfaces::
|
||||
Prints a list of the repository, command and file interfaces
|
||||
documentation on the standard output.
|
||||
+
|
||||
In-repository file interfaces such as `.git/info/exclude` are
|
||||
documented here (see linkgit:gitrepository-layout[5]), as well as
|
||||
in-tree configuration such as `.mailmap` (see linkgit:gitmailmap[5]).
|
||||
+
|
||||
This section of the documentation also covers general or widespread
|
||||
user-interface conventions (e.g. linkgit:gitcli[7]), and
|
||||
pseudo-configuration such as the file-based `.git/hooks/*` interface
|
||||
described in linkgit:githooks[5].
|
||||
|
||||
--developer-interfaces::
|
||||
Print list of file formats, protocols and other developer
|
||||
interfaces documentation on the standard output.
|
||||
|
||||
-i::
|
||||
--info::
|
||||
Display manual page for the command in the 'info' format. The
|
||||
|
||||
@ -128,8 +128,8 @@ $ git multi-pack-index verify
|
||||
SEE ALSO
|
||||
--------
|
||||
See link:technical/multi-pack-index.html[The Multi-Pack-Index Design
|
||||
Document] and link:technical/pack-format.html[The Multi-Pack-Index
|
||||
Format] for more information on the multi-pack-index feature.
|
||||
Document] and linkgit:gitformat-pack[5] for more information on the
|
||||
multi-pack-index feature and its file format.
|
||||
|
||||
|
||||
GIT
|
||||
|
||||
@ -39,10 +39,9 @@ OPTIONS
|
||||
--http-backend-info-refs::
|
||||
Used by linkgit:git-http-backend[1] to serve up
|
||||
`$GIT_URL/info/refs?service=git-upload-pack` requests. See
|
||||
"Smart Clients" in link:technical/http-protocol.html[the HTTP
|
||||
transfer protocols] documentation and "HTTP Transport" in
|
||||
link:technical/protocol-v2.html[the Git Wire Protocol, Version
|
||||
2] documentation. Also understood by
|
||||
"Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP
|
||||
Transport" in in the linkgit:gitprotocol-v2[5]
|
||||
documentation. Also understood by
|
||||
linkgit:git-receive-pack[1].
|
||||
|
||||
<directory>::
|
||||
|
||||
@ -339,6 +339,23 @@ The following documentation pages are guides about Git concepts.
|
||||
|
||||
include::cmds-guide.txt[]
|
||||
|
||||
Repository, command and file interfaces
|
||||
---------------------------------------
|
||||
|
||||
This documentation discusses repository and command interfaces which
|
||||
users are expected to interact with directly. See `--user-formats` in
|
||||
linkgit:git-help[1] for more details on the critera.
|
||||
|
||||
include::cmds-userinterfaces.txt[]
|
||||
|
||||
File formats, protocols and other developer interfaces
|
||||
------------------------------------------------------
|
||||
|
||||
This documentation discusses file formats, over-the-wire protocols and
|
||||
other git developer interfaces. See `--developer-interfaces` in
|
||||
linkgit:git-help[1].
|
||||
|
||||
include::cmds-developerinterfaces.txt[]
|
||||
|
||||
Configuration Mechanism
|
||||
-----------------------
|
||||
|
||||
@ -1,11 +1,33 @@
|
||||
= Git bundle v2 format
|
||||
gitformat-bundle(5)
|
||||
===================
|
||||
|
||||
The Git bundle format is a format that represents both refs and Git objects.
|
||||
NAME
|
||||
----
|
||||
gitformat-bundle - The bundle file format
|
||||
|
||||
== Format
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
*.bundle
|
||||
*.bdl
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
The Git bundle format is a format that represents both refs and Git
|
||||
objects. A bundle is a header in a format similar to
|
||||
linkgit:git-show-ref[1] followed by a pack in *.pack format.
|
||||
|
||||
The format is created and read by the linkgit:git-bundle[1] command,
|
||||
and supported by e.g. linkgit:git-fetch[1] and linkgit:git-clone[1].
|
||||
|
||||
|
||||
FORMAT
|
||||
------
|
||||
|
||||
We will use ABNF notation to define the Git bundle format. See
|
||||
protocol-common.txt for the details.
|
||||
linkgit:gitprotocol-common[5] for the details.
|
||||
|
||||
A v2 bundle looks like this:
|
||||
|
||||
@ -36,7 +58,9 @@ value = *(%01-09 / %0b-FF)
|
||||
pack = ... ; packfile
|
||||
----
|
||||
|
||||
== Semantics
|
||||
|
||||
SEMANTICS
|
||||
---------
|
||||
|
||||
A Git bundle consists of several parts.
|
||||
|
||||
@ -62,13 +86,15 @@ In the bundle format, there can be a comment following a prerequisite obj-id.
|
||||
This is a comment and it has no specific meaning. The writer of the bundle MAY
|
||||
put any string here. The reader of the bundle MUST ignore the comment.
|
||||
|
||||
=== Note on the shallow clone and a Git bundle
|
||||
Note on the shallow clone and a Git bundle
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Note that the prerequisites does not represent a shallow-clone boundary. The
|
||||
semantics of the prerequisites and the shallow-clone boundaries are different,
|
||||
and the Git bundle v2 format cannot represent a shallow clone repository.
|
||||
|
||||
== Capabilities
|
||||
CAPABILITIES
|
||||
------------
|
||||
|
||||
Because there is no opportunity for negotiation, unknown capabilities cause 'git
|
||||
bundle' to abort.
|
||||
@ -79,3 +105,7 @@ bundle' to abort.
|
||||
* `filter` specifies an object filter as in the `--filter` option in
|
||||
linkgit:git-rev-list[1]. The resulting pack-file must be marked as a
|
||||
`.promisor` pack-file after it is unbundled.
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -1,12 +1,25 @@
|
||||
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
|
||||
the pack format documentation in linkgit:gitformat-pack[5]).
|
||||
|
||||
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
|
||||
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 `multi-pack-index` format in linkgit:gitformat-pack[5] and
|
||||
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,9 +121,13 @@ 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
|
||||
parse the multi-pack-index file format documented in
|
||||
link:technical/pack-format.html[the multi-pack-index file format].
|
||||
the multi-pack-index file format section of linkgit:gitformat-pack[5].
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -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.
|
||||
@ -62,23 +75,23 @@ CHUNK LOOKUP:
|
||||
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
|
||||
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
|
||||
@ -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
|
||||
|
||||
@ -125,7 +139,7 @@ Git index format
|
||||
entry is encoded as if the path name for the previous entry is an
|
||||
empty string). At the beginning of an entry, an integer N in the
|
||||
variable width encoding (the same encoding as the offset is encoded
|
||||
for OFS_DELTA pack entries; see pack-format.txt) is stored, followed
|
||||
for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
|
||||
by a NUL-terminated string S. Removing N bytes from the end of the
|
||||
path name for the previous entry, and replacing it with the string S
|
||||
yields the path name for this entry.
|
||||
@ -402,3 +416,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
|
||||
@ -1,5 +1,30 @@
|
||||
Git pack format
|
||||
===============
|
||||
gitformat-pack(5)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitformat-pack - Git pack format
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
$GIT_DIR/objects/pack/pack-*.{pack,idx}
|
||||
$GIT_DIR/objects/pack/pack-*.rev
|
||||
$GIT_DIR/objects/pack/pack-*.mtimes
|
||||
$GIT_DIR/objects/pack/multi-pack-index
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
The Git pack format is now Git stores most of its primary repository
|
||||
data. Over the lietime af a repository loose objects (if any) and
|
||||
smaller packs are consolidated into larger pack(s). See
|
||||
linkgit:git-gc[1] and linkgit:git-pack-objects[1].
|
||||
|
||||
The pack format is also used over-the-wire, see
|
||||
e.g. linkgit:gitprotocol-v2[5], as well as being a part of
|
||||
other container formats in the case of linkgit:gitformat-bundle[5].
|
||||
|
||||
== Checksums and object IDs
|
||||
|
||||
@ -356,7 +381,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
|
||||
@ -482,3 +507,132 @@ packs arranged in MIDX order (with the preferred pack coming first).
|
||||
|
||||
The MIDX's reverse index is stored in the optional 'RIDX' chunk within
|
||||
the MIDX itself.
|
||||
|
||||
== cruft packs
|
||||
|
||||
The cruft packs feature offer an alternative to Git's traditional mechanism of
|
||||
removing unreachable objects. This document provides an overview of Git's
|
||||
pruning mechanism, and how a cruft pack can be used instead to accomplish the
|
||||
same.
|
||||
|
||||
=== Background
|
||||
|
||||
To remove unreachable objects from your repository, Git offers `git repack -Ad`
|
||||
(see linkgit:git-repack[1]). Quoting from the documentation:
|
||||
|
||||
----
|
||||
[...] unreachable objects in a previous pack become loose, unpacked objects,
|
||||
instead of being left in the old pack. [...] loose unreachable objects will be
|
||||
pruned according to normal expiry rules with the next 'git gc' invocation.
|
||||
----
|
||||
|
||||
Unreachable objects aren't removed immediately, since doing so could race with
|
||||
an incoming push which may reference an object which is about to be deleted.
|
||||
Instead, those unreachable objects are stored as loose objects and stay that way
|
||||
until they are older than the expiration window, at which point they are removed
|
||||
by linkgit:git-prune[1].
|
||||
|
||||
Git must store these unreachable objects loose in order to keep track of their
|
||||
per-object mtimes. If these unreachable objects were written into one big pack,
|
||||
then either freshening that pack (because an object contained within it was
|
||||
re-written) or creating a new pack of unreachable objects would cause the pack's
|
||||
mtime to get updated, and the objects within it would never leave the expiration
|
||||
window. Instead, objects are stored loose in order to keep track of the
|
||||
individual object mtimes and avoid a situation where all cruft objects are
|
||||
freshened at once.
|
||||
|
||||
This can lead to undesirable situations when a repository contains many
|
||||
unreachable objects which have not yet left the grace period. Having large
|
||||
directories in the shards of `.git/objects` can lead to decreased performance in
|
||||
the repository. But given enough unreachable objects, this can lead to inode
|
||||
starvation and degrade the performance of the whole system. Since we
|
||||
can never pack those objects, these repositories often take up a large amount of
|
||||
disk space, since we can only zlib compress them, but not store them in delta
|
||||
chains.
|
||||
|
||||
=== Cruft packs
|
||||
|
||||
A cruft pack eliminates the need for storing unreachable objects in a loose
|
||||
state by including the per-object mtimes in a separate file alongside a single
|
||||
pack containing all loose objects.
|
||||
|
||||
A cruft pack is written by `git repack --cruft` when generating a new pack.
|
||||
linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
|
||||
is a classic all-into-one repack, meaning that everything in the resulting pack is
|
||||
reachable, and everything else is unreachable. Once written, the `--cruft`
|
||||
option instructs `git repack` to generate another pack containing only objects
|
||||
not packed in the previous step (which equates to packing all unreachable
|
||||
objects together). This progresses as follows:
|
||||
|
||||
1. Enumerate every object, marking any object which is (a) not contained in a
|
||||
kept-pack, and (b) whose mtime is within the grace period as a traversal
|
||||
tip.
|
||||
|
||||
2. Perform a reachability traversal based on the tips gathered in the previous
|
||||
step, adding every object along the way to the pack.
|
||||
|
||||
3. Write the pack out, along with a `.mtimes` file that records the per-object
|
||||
timestamps.
|
||||
|
||||
This mode is invoked internally by linkgit:git-repack[1] when instructed to
|
||||
write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
|
||||
of packs which will not be deleted by the repack; in other words, they contain
|
||||
all of the repository's reachable objects.
|
||||
|
||||
When a repository already has a cruft pack, `git repack --cruft` typically only
|
||||
adds objects to it. An exception to this is when `git repack` is given the
|
||||
`--cruft-expiration` option, which allows the generated cruft pack to omit
|
||||
expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
|
||||
later on.
|
||||
|
||||
It is linkgit:git-gc[1] that is typically responsible for removing expired
|
||||
unreachable objects.
|
||||
|
||||
=== Caution for mixed-version environments
|
||||
|
||||
Repositories that have cruft packs in them will continue to work with any older
|
||||
version of Git. Note, however, that previous versions of Git which do not
|
||||
understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
|
||||
all of the objects in it. In other words, do not expect older (pre-cruft pack)
|
||||
versions of Git to interpret or even read the contents of the `.mtimes` file.
|
||||
|
||||
Note that having mixed versions of Git GC-ing the same repository can lead to
|
||||
unreachable objects never being completely pruned. This can happen under the
|
||||
following circumstances:
|
||||
|
||||
- An older version of Git running GC explodes the contents of an existing
|
||||
cruft pack loose, using the cruft pack's mtime.
|
||||
- A newer version running GC collects those loose objects into a cruft pack,
|
||||
where the .mtime file reflects the loose object's actual mtimes, but the
|
||||
cruft pack mtime is "now".
|
||||
|
||||
Repeating this process will lead to unreachable objects not getting pruned as a
|
||||
result of repeatedly resetting the objects' mtimes to the present time.
|
||||
|
||||
If you are GC-ing repositories in a mixed version environment, consider omitting
|
||||
the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
|
||||
leaving the `gc.cruftPacks` configuration unset until all writers understand
|
||||
cruft packs.
|
||||
|
||||
=== Alternatives
|
||||
|
||||
Notable alternatives to this design include:
|
||||
|
||||
- The location of the per-object mtime data, and
|
||||
- Storing unreachable objects in multiple cruft packs.
|
||||
|
||||
On the location of mtime data, a new auxiliary file tied to the pack was chosen
|
||||
to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
|
||||
support for optional chunks of data, it may make sense to consolidate the
|
||||
`.mtimes` format into the `.idx` itself.
|
||||
|
||||
Storing unreachable objects among multiple cruft packs (e.g., creating a new
|
||||
cruft pack during each repacking operation including only unreachable objects
|
||||
which aren't already stored in an earlier cruft pack) is significantly more
|
||||
complicated to construct, and so aren't pursued here. The obvious drawback to
|
||||
the current implementation is that the entire cruft pack must be re-written from
|
||||
scratch.
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -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
|
||||
@ -1,8 +1,20 @@
|
||||
Git Protocol Capabilities
|
||||
=========================
|
||||
gitprotocol-capabilities(5)
|
||||
===========================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitprotocol-capabilities - Protocol v0 and v1 capabilities
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
<over-the-wire-protocol>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
NOTE: this document describes capabilities for versions 0 and 1 of the pack
|
||||
protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
|
||||
protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
|
||||
doc.
|
||||
|
||||
Servers SHOULD support all capabilities defined in this document.
|
||||
@ -77,7 +89,7 @@ interleaved with S-R-Q.
|
||||
multi_ack_detailed
|
||||
------------------
|
||||
This is an extension of multi_ack that permits client to better
|
||||
understand the server's in-memory state. See pack-protocol.txt,
|
||||
understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
|
||||
section "Packfile Negotiation" for more information.
|
||||
|
||||
no-done
|
||||
@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests
|
||||
this capability, after unpacking and updating references the server
|
||||
will respond with whether the packfile unpacked successfully and if
|
||||
each reference was updated successfully. If any of those were not
|
||||
successful, it will send back an error message. See pack-protocol.txt
|
||||
successful, it will send back an error message. See linkgit:gitprotocol-pack[5]
|
||||
for example messages.
|
||||
|
||||
report-status-v2
|
||||
@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
|
||||
the "proc-receive" hook. The "proc-receive" hook may handle a command
|
||||
for a pseudo-reference which may create or update a reference with
|
||||
different name, new-oid, and old-oid. While the capability
|
||||
'report-status' cannot report for such case. See pack-protocol.txt
|
||||
'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]
|
||||
for details.
|
||||
|
||||
delete-refs
|
||||
@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
|
||||
current implementation uses trace2 session IDs (see
|
||||
link:api-trace2.html[api-trace2] for details), but this may change and users of
|
||||
the session ID should not rely on this fact.
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -1,5 +1,20 @@
|
||||
Documentation Common to Pack and Http Protocols
|
||||
===============================================
|
||||
gitprotocol-common(5)
|
||||
=====================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitprotocol-common - Things common to various protocols
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
<over-the-wire-protocol>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
This document sets defines things common to various over-the-wire
|
||||
protocols and file formats used in Git.
|
||||
|
||||
ABNF Notation
|
||||
-------------
|
||||
@ -97,3 +112,7 @@ Examples (as C-style strings):
|
||||
"000bfoobar\n" "foobar\n"
|
||||
"0004" ""
|
||||
----
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -1,5 +1,19 @@
|
||||
HTTP transfer protocols
|
||||
=======================
|
||||
gitprotocol-http(5)
|
||||
===================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitprotocol-http - Git HTTP-based protocols
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
<over-the-wire-protocol>
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Git supports two HTTP based transfer protocols. A "dumb" protocol
|
||||
which requires only a standard HTTP server on the server end of the
|
||||
@ -222,7 +236,7 @@ smart server reply:
|
||||
S: 0000
|
||||
|
||||
The client may send Extra Parameters (see
|
||||
Documentation/technical/pack-protocol.txt) as a colon-separated string
|
||||
linkgit:gitprotocol-pack[5]) as a colon-separated string
|
||||
in the Git-Protocol HTTP header.
|
||||
|
||||
Uses the `--http-backend-info-refs` option to
|
||||
@ -512,11 +526,18 @@ the id obtained through ref discovery as old_id.
|
||||
|
||||
TODO: Document this further.
|
||||
|
||||
|
||||
References
|
||||
REFERENCES
|
||||
----------
|
||||
|
||||
http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
|
||||
http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
|
||||
link:technical/pack-protocol.html
|
||||
link:technical/protocol-capabilities.html
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
linkgit:gitprotocol-pack[5]
|
||||
linkgit:gitprotocol-capabilities[5]
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -1,11 +1,23 @@
|
||||
Packfile transfer protocols
|
||||
===========================
|
||||
gitprotocol-pack(5)
|
||||
===================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitprotocol-pack - How packs are transferred over-the-wire
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
<over-the-wire-protocol>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Git supports transferring data in packfiles over the ssh://, git://, http:// and
|
||||
file:// transports. There exist two sets of protocols, one for pushing
|
||||
data from a client to a server and another for fetching data from a
|
||||
server to a client. The three transports (ssh, git, file) use the same
|
||||
protocol to transfer data. http is documented in http-protocol.txt.
|
||||
protocol to transfer data. http is documented in linkgit:gitprotocol-http[5].
|
||||
|
||||
The processes invoked in the canonical Git implementation are 'upload-pack'
|
||||
on the server side and 'fetch-pack' on the client side for fetching data;
|
||||
@ -18,7 +30,7 @@ pkt-line Format
|
||||
---------------
|
||||
|
||||
The descriptions below build on the pkt-line format described in
|
||||
protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
|
||||
linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
|
||||
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
|
||||
include a LF, but the receiver MUST NOT complain if it is not present.
|
||||
|
||||
@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
|
||||
|
||||
Servers that receive any such Extra Parameters MUST ignore all
|
||||
unrecognized keys. Currently, the only Extra Parameter recognized is
|
||||
"version" with a value of '1' or '2'. See protocol-v2.txt for more
|
||||
"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more
|
||||
information on protocol version 2.
|
||||
|
||||
Git Transport
|
||||
@ -455,7 +467,7 @@ Now that the client and server have finished negotiation about what
|
||||
the minimal amount of data that needs to be sent to the client is, the server
|
||||
will construct and send the required data in packfile format.
|
||||
|
||||
See pack-format.txt for what the packfile itself actually looks like.
|
||||
See linkgit:gitformat-pack[5] for what the packfile itself actually looks like.
|
||||
|
||||
If 'side-band' or 'side-band-64k' capabilities have been specified by
|
||||
the client, the server will send the packfile data multiplexed.
|
||||
@ -707,3 +719,7 @@ An example client/server communication might look like this:
|
||||
S: 0018ok refs/heads/debug\n
|
||||
S: 002ang refs/heads/master non-fast-forward\n
|
||||
----
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -1,5 +1,17 @@
|
||||
Git Wire Protocol, Version 2
|
||||
============================
|
||||
gitprotocol-v2(5)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
gitprotocol-v2 - Git Wire Protocol, Version 2
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
<over-the-wire-protocol>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
This document presents a specification for a version 2 of Git's wire
|
||||
protocol. Protocol v2 will improve upon v1 in the following ways:
|
||||
@ -26,8 +38,7 @@ Packet-Line Framing
|
||||
-------------------
|
||||
|
||||
All communication is done using packet-line framing, just as in v1. See
|
||||
`Documentation/technical/pack-protocol.txt` and
|
||||
`Documentation/technical/protocol-common.txt` for more information.
|
||||
linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.
|
||||
|
||||
In protocol v2 these special packets will have the following semantics:
|
||||
|
||||
@ -42,7 +53,7 @@ Initial Client Request
|
||||
In general a client can request to speak protocol v2 by sending
|
||||
`version=2` through the respective side-channel for the transport being
|
||||
used which inevitably sets `GIT_PROTOCOL`. More information can be
|
||||
found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
|
||||
found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the
|
||||
`GIT_PROTOCOL` definition in `git.txt`. In all cases the
|
||||
response from the server is the capability advertisement.
|
||||
|
||||
@ -66,7 +77,7 @@ HTTP Transport
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When using the http:// or https:// transport a client makes a "smart"
|
||||
info/refs request as described in `http-protocol.txt` and requests that
|
||||
info/refs request as described in linkgit:gitprotocol-http[5] and requests that
|
||||
v2 be used by supplying "version=2" in the `Git-Protocol` header.
|
||||
|
||||
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
|
||||
@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.
|
||||
attr = "size"
|
||||
|
||||
obj-info = obj-id SP obj-size
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
|
||||
has the git packed object header, which is variable-length. We want to
|
||||
strip that off so we can start playing with the zlib data directly. You
|
||||
can either work your way through it manually (the format is described in
|
||||
link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
|
||||
linkgit:gitformat-pack[5]),
|
||||
or you can walk through it in a debugger. I did the latter, creating a
|
||||
valid pack like:
|
||||
|
||||
|
||||
@ -32,6 +32,9 @@ my %SECTIONS;
|
||||
'SEE ALSO' => {
|
||||
order => $order++,
|
||||
},
|
||||
'FILE FORMAT' => {
|
||||
order => $order++,
|
||||
},
|
||||
'GIT' => {
|
||||
required => 1,
|
||||
order => $order++,
|
||||
|
||||
@ -78,7 +78,7 @@ client and an optional response message from the server. Both the
|
||||
client and server messages are unlimited in length and are terminated
|
||||
with a flush packet.
|
||||
|
||||
The pkt-line routines (Documentation/technical/protocol-common.txt)
|
||||
The pkt-line routines (linkgit:gitprotocol-common[5])
|
||||
are used to simplify buffer management during message generation,
|
||||
transmission, and reception. A flush packet is used to mark the end
|
||||
of the message. This allows the sender to incrementally generate and
|
||||
|
||||
@ -1,123 +0,0 @@
|
||||
= Cruft packs
|
||||
|
||||
The cruft packs feature offer an alternative to Git's traditional mechanism of
|
||||
removing unreachable objects. This document provides an overview of Git's
|
||||
pruning mechanism, and how a cruft pack can be used instead to accomplish the
|
||||
same.
|
||||
|
||||
== Background
|
||||
|
||||
To remove unreachable objects from your repository, Git offers `git repack -Ad`
|
||||
(see linkgit:git-repack[1]). Quoting from the documentation:
|
||||
|
||||
[quote]
|
||||
[...] unreachable objects in a previous pack become loose, unpacked objects,
|
||||
instead of being left in the old pack. [...] loose unreachable objects will be
|
||||
pruned according to normal expiry rules with the next 'git gc' invocation.
|
||||
|
||||
Unreachable objects aren't removed immediately, since doing so could race with
|
||||
an incoming push which may reference an object which is about to be deleted.
|
||||
Instead, those unreachable objects are stored as loose objects and stay that way
|
||||
until they are older than the expiration window, at which point they are removed
|
||||
by linkgit:git-prune[1].
|
||||
|
||||
Git must store these unreachable objects loose in order to keep track of their
|
||||
per-object mtimes. If these unreachable objects were written into one big pack,
|
||||
then either freshening that pack (because an object contained within it was
|
||||
re-written) or creating a new pack of unreachable objects would cause the pack's
|
||||
mtime to get updated, and the objects within it would never leave the expiration
|
||||
window. Instead, objects are stored loose in order to keep track of the
|
||||
individual object mtimes and avoid a situation where all cruft objects are
|
||||
freshened at once.
|
||||
|
||||
This can lead to undesirable situations when a repository contains many
|
||||
unreachable objects which have not yet left the grace period. Having large
|
||||
directories in the shards of `.git/objects` can lead to decreased performance in
|
||||
the repository. But given enough unreachable objects, this can lead to inode
|
||||
starvation and degrade the performance of the whole system. Since we
|
||||
can never pack those objects, these repositories often take up a large amount of
|
||||
disk space, since we can only zlib compress them, but not store them in delta
|
||||
chains.
|
||||
|
||||
== Cruft packs
|
||||
|
||||
A cruft pack eliminates the need for storing unreachable objects in a loose
|
||||
state by including the per-object mtimes in a separate file alongside a single
|
||||
pack containing all loose objects.
|
||||
|
||||
A cruft pack is written by `git repack --cruft` when generating a new pack.
|
||||
linkgit:git-pack-objects[1]'s `--cruft` option. Note that `git repack --cruft`
|
||||
is a classic all-into-one repack, meaning that everything in the resulting pack is
|
||||
reachable, and everything else is unreachable. Once written, the `--cruft`
|
||||
option instructs `git repack` to generate another pack containing only objects
|
||||
not packed in the previous step (which equates to packing all unreachable
|
||||
objects together). This progresses as follows:
|
||||
|
||||
1. Enumerate every object, marking any object which is (a) not contained in a
|
||||
kept-pack, and (b) whose mtime is within the grace period as a traversal
|
||||
tip.
|
||||
|
||||
2. Perform a reachability traversal based on the tips gathered in the previous
|
||||
step, adding every object along the way to the pack.
|
||||
|
||||
3. Write the pack out, along with a `.mtimes` file that records the per-object
|
||||
timestamps.
|
||||
|
||||
This mode is invoked internally by linkgit:git-repack[1] when instructed to
|
||||
write a cruft pack. Crucially, the set of in-core kept packs is exactly the set
|
||||
of packs which will not be deleted by the repack; in other words, they contain
|
||||
all of the repository's reachable objects.
|
||||
|
||||
When a repository already has a cruft pack, `git repack --cruft` typically only
|
||||
adds objects to it. An exception to this is when `git repack` is given the
|
||||
`--cruft-expiration` option, which allows the generated cruft pack to omit
|
||||
expired objects instead of waiting for linkgit:git-gc[1] to expire those objects
|
||||
later on.
|
||||
|
||||
It is linkgit:git-gc[1] that is typically responsible for removing expired
|
||||
unreachable objects.
|
||||
|
||||
== Caution for mixed-version environments
|
||||
|
||||
Repositories that have cruft packs in them will continue to work with any older
|
||||
version of Git. Note, however, that previous versions of Git which do not
|
||||
understand the `.mtimes` file will use the cruft pack's mtime as the mtime for
|
||||
all of the objects in it. In other words, do not expect older (pre-cruft pack)
|
||||
versions of Git to interpret or even read the contents of the `.mtimes` file.
|
||||
|
||||
Note that having mixed versions of Git GC-ing the same repository can lead to
|
||||
unreachable objects never being completely pruned. This can happen under the
|
||||
following circumstances:
|
||||
|
||||
- An older version of Git running GC explodes the contents of an existing
|
||||
cruft pack loose, using the cruft pack's mtime.
|
||||
- A newer version running GC collects those loose objects into a cruft pack,
|
||||
where the .mtime file reflects the loose object's actual mtimes, but the
|
||||
cruft pack mtime is "now".
|
||||
|
||||
Repeating this process will lead to unreachable objects not getting pruned as a
|
||||
result of repeatedly resetting the objects' mtimes to the present time.
|
||||
|
||||
If you are GC-ing repositories in a mixed version environment, consider omitting
|
||||
the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and
|
||||
leaving the `gc.cruftPacks` configuration unset until all writers understand
|
||||
cruft packs.
|
||||
|
||||
== Alternatives
|
||||
|
||||
Notable alternatives to this design include:
|
||||
|
||||
- The location of the per-object mtime data, and
|
||||
- Storing unreachable objects in multiple cruft packs.
|
||||
|
||||
On the location of mtime data, a new auxiliary file tied to the pack was chosen
|
||||
to avoid complicating the `.idx` format. If the `.idx` format were ever to gain
|
||||
support for optional chunks of data, it may make sense to consolidate the
|
||||
`.mtimes` format into the `.idx` itself.
|
||||
|
||||
Storing unreachable objects among multiple cruft packs (e.g., creating a new
|
||||
cruft pack during each repacking operation including only unreachable objects
|
||||
which aren't already stored in an earlier cruft pack) is significantly more
|
||||
complicated to construct, and so aren't pursued here. The obvious drawback to
|
||||
the current implementation is that the entire cruft pack must be re-written from
|
||||
scratch.
|
||||
@ -205,7 +205,7 @@ SHA-1 content.
|
||||
Object storage
|
||||
~~~~~~~~~~~~~~
|
||||
Loose objects use zlib compression and packed objects use the packed
|
||||
format described in Documentation/technical/pack-format.txt, just like
|
||||
format described in linkgit:gitformat-pack[5], just like
|
||||
today. The content that is compressed and stored uses SHA-256 content
|
||||
instead of SHA-1 content.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ Long-running process protocol
|
||||
|
||||
This protocol is used when Git needs to communicate with an external
|
||||
process throughout the entire life of a single Git command. All
|
||||
communication is in pkt-line format (see technical/protocol-common.txt)
|
||||
communication is in pkt-line format (see linkgit:gitprotocol-common[5])
|
||||
over standard input and standard output.
|
||||
|
||||
Handshake
|
||||
|
||||
@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section
|
||||
directly before the `packfile` section (right after `wanted-refs` if it is
|
||||
sent) containing URIs of any of the given protocols. The URIs point to
|
||||
packfiles that use only features that the client has declared that it supports
|
||||
(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of
|
||||
(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
|
||||
this section.
|
||||
|
||||
Clients should then download and index all the given URIs (in addition to
|
||||
|
||||
@ -79,7 +79,7 @@ Design Details
|
||||
upload-pack negotiation.
|
||||
+
|
||||
This uses the existing capability discovery mechanism.
|
||||
See "filter" in Documentation/technical/pack-protocol.txt.
|
||||
See "filter" in linkgit:gitprotocol-pack[5].
|
||||
|
||||
- Clients pass a "filter-spec" to clone and fetch which is passed to the
|
||||
server to request filtering during packfile construction.
|
||||
|
||||
@ -3133,7 +3133,7 @@ those "loose" objects.
|
||||
You can save space and make Git faster by moving these loose objects in
|
||||
to a "pack file", which stores a group of objects in an efficient
|
||||
compressed format; the details of how pack files are formatted can be
|
||||
found in link:technical/pack-format.html[pack format].
|
||||
found in link:gitformat-pack[5].
|
||||
|
||||
To put the loose objects into a pack, just run git repack:
|
||||
|
||||
|
||||
1
Makefile
1
Makefile
@ -3531,6 +3531,7 @@ check-docs::
|
||||
sed -e '1,/^### command list/d' \
|
||||
-e '/^#/d' \
|
||||
-e '/guide$$/d' \
|
||||
-e '/interfaces$$/d' \
|
||||
-e 's/[ ].*//' \
|
||||
-e 's/^/listed /' command-list.txt; \
|
||||
$(MAKE) -C Documentation print-man1 | \
|
||||
|
||||
@ -43,6 +43,8 @@ static enum help_action {
|
||||
HELP_ACTION_ALL = 1,
|
||||
HELP_ACTION_GUIDES,
|
||||
HELP_ACTION_CONFIG,
|
||||
HELP_ACTION_USER_INTERFACES,
|
||||
HELP_ACTION_DEVELOPER_INTERFACES,
|
||||
HELP_ACTION_CONFIG_FOR_COMPLETION,
|
||||
HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION,
|
||||
} cmd_mode;
|
||||
@ -69,6 +71,12 @@ static struct option builtin_help_options[] = {
|
||||
|
||||
OPT_CMDMODE('g', "guides", &cmd_mode, N_("print list of useful guides"),
|
||||
HELP_ACTION_GUIDES),
|
||||
OPT_CMDMODE(0, "user-interfaces", &cmd_mode,
|
||||
N_("print list of user-facing repository, command and file interfaces"),
|
||||
HELP_ACTION_USER_INTERFACES),
|
||||
OPT_CMDMODE(0, "developer-interfaces", &cmd_mode,
|
||||
N_("print list of file formats, protocols and other developer interfaces"),
|
||||
HELP_ACTION_DEVELOPER_INTERFACES),
|
||||
OPT_CMDMODE('c', "config", &cmd_mode, N_("print all configuration variable names"),
|
||||
HELP_ACTION_CONFIG),
|
||||
OPT_CMDMODE_F(0, "config-for-completion", &cmd_mode, "",
|
||||
@ -81,9 +89,11 @@ static struct option builtin_help_options[] = {
|
||||
|
||||
static const char * const builtin_help_usage[] = {
|
||||
"git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]",
|
||||
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
|
||||
N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]"),
|
||||
"git help [-g|--guides]",
|
||||
"git help [-c|--config]",
|
||||
"git help [--user-interfaces]",
|
||||
"git help [--developer-interfaces]",
|
||||
NULL
|
||||
};
|
||||
|
||||
@ -654,6 +664,14 @@ int cmd_help(int argc, const char **argv, const char *prefix)
|
||||
opt_mode_usage(argc, "--config-for-completion", help_format);
|
||||
list_config_help(SHOW_CONFIG_VARS);
|
||||
return 0;
|
||||
case HELP_ACTION_USER_INTERFACES:
|
||||
opt_mode_usage(argc, "--user-interfaces", help_format);
|
||||
list_user_interfaces_help();
|
||||
return 0;
|
||||
case HELP_ACTION_DEVELOPER_INTERFACES:
|
||||
opt_mode_usage(argc, "--developer-interfaces", help_format);
|
||||
list_developer_interfaces_help();
|
||||
return 0;
|
||||
case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION:
|
||||
opt_mode_usage(argc, "--config-sections-for-completion",
|
||||
help_format);
|
||||
|
||||
3
cache.h
3
cache.h
@ -475,8 +475,7 @@ extern struct index_state the_index;
|
||||
|
||||
/*
|
||||
* Values in this enum (except those outside the 3 bit range) are part
|
||||
* of pack file format. See Documentation/technical/pack-format.txt
|
||||
* for more information.
|
||||
* of pack file format. See gitformat-pack(5) for more information.
|
||||
*/
|
||||
enum object_type {
|
||||
OBJ_BAD = -1,
|
||||
|
||||
@ -43,6 +43,15 @@
|
||||
# specified here, which can only have "guide" attribute and nothing
|
||||
# else.
|
||||
#
|
||||
# User-facing repository, command and file interfaces such as
|
||||
# documentation for the .gitmodules, .mailmap etc. files lives in man
|
||||
# sections 5 and 7. These entries can only have the "userinterfaces"
|
||||
# attribute and nothing else.
|
||||
#
|
||||
# Git's file formats and protocols, such as documentation for the
|
||||
# *.bundle format lives in man section 5. These entries can only have
|
||||
# the "developerinterfaces" attribute and nothing else.
|
||||
#
|
||||
### command list (do not change this line)
|
||||
# command name category [category] [category]
|
||||
git-add mainporcelain worktree
|
||||
@ -192,24 +201,35 @@ git-verify-tag ancillaryinterrogators
|
||||
git-whatchanged ancillaryinterrogators complete
|
||||
git-worktree mainporcelain
|
||||
git-write-tree plumbingmanipulators
|
||||
gitattributes guide
|
||||
gitcli guide
|
||||
gitattributes userinterfaces
|
||||
gitcli userinterfaces
|
||||
gitcore-tutorial guide
|
||||
gitcredentials guide
|
||||
gitcvs-migration guide
|
||||
gitdiffcore guide
|
||||
giteveryday guide
|
||||
gitfaq guide
|
||||
gitformat-bundle developerinterfaces
|
||||
gitformat-chunk developerinterfaces
|
||||
gitformat-commit-graph developerinterfaces
|
||||
gitformat-index developerinterfaces
|
||||
gitformat-pack developerinterfaces
|
||||
gitformat-signature developerinterfaces
|
||||
gitglossary guide
|
||||
githooks guide
|
||||
gitignore guide
|
||||
githooks userinterfaces
|
||||
gitignore userinterfaces
|
||||
gitk mainporcelain
|
||||
gitmailmap guide
|
||||
gitmodules guide
|
||||
gitmailmap userinterfaces
|
||||
gitmodules userinterfaces
|
||||
gitnamespaces guide
|
||||
gitprotocol-capabilities developerinterfaces
|
||||
gitprotocol-common developerinterfaces
|
||||
gitprotocol-http developerinterfaces
|
||||
gitprotocol-pack developerinterfaces
|
||||
gitprotocol-v2 developerinterfaces
|
||||
gitremote-helpers guide
|
||||
gitrepository-layout guide
|
||||
gitrevisions guide
|
||||
gitrepository-layout userinterfaces
|
||||
gitrevisions userinterfaces
|
||||
gitsubmodules guide
|
||||
gittutorial guide
|
||||
gittutorial-2 guide
|
||||
|
||||
39
help.c
39
help.c
@ -38,19 +38,30 @@ static struct category_description main_categories[] = {
|
||||
{ CAT_plumbinginterrogators, N_("Low-level Commands / Interrogators") },
|
||||
{ CAT_synchingrepositories, N_("Low-level Commands / Syncing Repositories") },
|
||||
{ CAT_purehelpers, N_("Low-level Commands / Internal Helpers") },
|
||||
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces") },
|
||||
{ CAT_developerinterfaces, N_("Developer-facing file file formats, protocols and interfaces") },
|
||||
{ 0, NULL }
|
||||
};
|
||||
|
||||
static const char *drop_prefix(const char *name, uint32_t category)
|
||||
{
|
||||
const char *new_name;
|
||||
const char *prefix;
|
||||
|
||||
if (skip_prefix(name, "git-", &new_name))
|
||||
return new_name;
|
||||
if (category == CAT_guide && skip_prefix(name, "git", &new_name))
|
||||
switch (category) {
|
||||
case CAT_guide:
|
||||
case CAT_userinterfaces:
|
||||
case CAT_developerinterfaces:
|
||||
prefix = "git";
|
||||
break;
|
||||
default:
|
||||
prefix = "git-";
|
||||
break;
|
||||
}
|
||||
if (skip_prefix(name, prefix, &new_name))
|
||||
return new_name;
|
||||
|
||||
return name;
|
||||
|
||||
}
|
||||
|
||||
static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)
|
||||
@ -426,6 +437,26 @@ void list_guides_help(void)
|
||||
putchar('\n');
|
||||
}
|
||||
|
||||
void list_user_interfaces_help(void)
|
||||
{
|
||||
struct category_description catdesc[] = {
|
||||
{ CAT_userinterfaces, N_("User-facing repository, command and file interfaces:") },
|
||||
{ 0, NULL }
|
||||
};
|
||||
print_cmd_by_category(catdesc, NULL);
|
||||
putchar('\n');
|
||||
}
|
||||
|
||||
void list_developer_interfaces_help(void)
|
||||
{
|
||||
struct category_description catdesc[] = {
|
||||
{ CAT_developerinterfaces, N_("File formats, protocols and other developer interfaces:") },
|
||||
{ 0, NULL }
|
||||
};
|
||||
print_cmd_by_category(catdesc, NULL);
|
||||
putchar('\n');
|
||||
}
|
||||
|
||||
static int get_alias(const char *var, const char *value, void *data)
|
||||
{
|
||||
struct string_list *list = data;
|
||||
|
||||
2
help.h
2
help.h
@ -22,6 +22,8 @@ static inline void mput_char(char c, unsigned int num)
|
||||
void list_common_cmds_help(void);
|
||||
void list_all_cmds_help(int show_external_commands, int show_aliases);
|
||||
void list_guides_help(void);
|
||||
void list_user_interfaces_help(void);
|
||||
void list_developer_interfaces_help(void);
|
||||
|
||||
void list_all_main_cmds(struct string_list *list);
|
||||
void list_all_other_cmds(struct string_list *list);
|
||||
|
||||
@ -22,7 +22,7 @@
|
||||
*
|
||||
* - pack position refers to an object's position within a non-existent pack
|
||||
* described by the MIDX. The pack structure is described in
|
||||
* Documentation/technical/pack-format.txt.
|
||||
* gitformat-pack(5).
|
||||
*
|
||||
* It is effectively a concatanation of all packs in the MIDX (ordered by
|
||||
* their numeric ID within the MIDX) in their original order within each
|
||||
|
||||
@ -69,7 +69,7 @@ int valid_remote_name(const char *name);
|
||||
struct strvec;
|
||||
/*
|
||||
* Determine what <prefix> values to pass to the peer in ref-prefix lines
|
||||
* (see Documentation/technical/protocol-v2.txt).
|
||||
* (see linkgit:gitprotocol-v2[5]).
|
||||
*/
|
||||
void refspec_ref_prefixes(const struct refspec *rs,
|
||||
struct strvec *ref_prefixes);
|
||||
|
||||
@ -44,6 +44,8 @@ test_expect_success 'invalid usage' '
|
||||
test_expect_code 129 git help -g add &&
|
||||
test_expect_code 129 git help -a -g &&
|
||||
|
||||
test_expect_code 129 git help --user-interfaces add &&
|
||||
|
||||
test_expect_code 129 git help -g -c &&
|
||||
test_expect_code 129 git help --config-for-completion add &&
|
||||
test_expect_code 129 git help --config-sections-for-completion add
|
||||
@ -104,9 +106,9 @@ test_expect_success 'git help' '
|
||||
test_i18ngrep "^ commit " help.output &&
|
||||
test_i18ngrep "^ fetch " help.output
|
||||
'
|
||||
|
||||
test_expect_success 'git help -g' '
|
||||
git help -g >help.output &&
|
||||
test_i18ngrep "^ attributes " help.output &&
|
||||
test_i18ngrep "^ everyday " help.output &&
|
||||
test_i18ngrep "^ tutorial " help.output
|
||||
'
|
||||
@ -127,6 +129,12 @@ test_expect_success 'git help succeeds without git.html' '
|
||||
test_cmp expect test-browser.log
|
||||
'
|
||||
|
||||
test_expect_success 'git help --user-interfaces' '
|
||||
git help --user-interfaces >help.output &&
|
||||
grep "^ attributes " help.output &&
|
||||
grep "^ mailmap " help.output
|
||||
'
|
||||
|
||||
test_expect_success 'git help -c' '
|
||||
git help -c >help.output &&
|
||||
cat >expect <<-\EOF &&
|
||||
@ -220,6 +228,10 @@ test_expect_success "'git help -a' section spacing" '
|
||||
Low-level Commands / Syncing Repositories
|
||||
|
||||
Low-level Commands / Internal Helpers
|
||||
|
||||
User-facing repository, command and file interfaces
|
||||
|
||||
Developer-facing file file formats, protocols and interfaces
|
||||
EOF
|
||||
test_cmp expect actual
|
||||
'
|
||||
|
||||
@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
|
||||
# This is not possible with protocol v2, since both objects and refs
|
||||
# are obtained from the "git-upload-pack" path. A solution to this is
|
||||
# to teach the server and client to be able to inline ls-refs requests
|
||||
# as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
|
||||
# can serve refs, just like it does in protocol v0.
|
||||
# as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
|
||||
# "info/refs" can serve refs, just like it does in protocol v0.
|
||||
GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
|
||||
expect_askpass none
|
||||
'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user