Format and protocol specifications
Object formats, repository state and communication protocols.
Check the status of each document before you rely on it. Each entry links to the full text in the docs/specs/ directory of the kit repository.
Each document declares its status in front matter. SPEC-CONVENTIONS defines the words. A draft document can change or have gaps that it names. A stable document changes only with a version change.
A normative document sets requirements that every compatible implementation must meet.
Objects and hashing
How bytes become content-addressed objects: layouts, Merkle identity, chunking and deltas.
SPEC-OBJECTS(opens in a new tab) stable
The byte layout of every object type over 32-byte BLAKE3 IDs. A tool can read and write these bytes from this document alone.
SPEC-MERKLE-OBJECTS(opens in a new tab) stable-normative
How the ID of a tree and of a chunked blob comes from a binary Merkle tree root.
SPEC-FASTCDC(opens in a new tab) stable
Content-defined chunking with a fixed gear table, so that every producer cuts a file the same way.
SPEC-DELTA(opens in a new tab) stable
The instruction stream that a delta entry in a packfile uses to rebuild an object from a base.
SPEC-DISCLOSURE(opens in a new tab) draft-normative
Proof that one path, chunk or byte range belongs to a commit, and proof that a served object set is complete.
Repository state
State that kit keeps in .kit/: refs, the staging index, linked worktrees, locks and garbage collection.
SPEC-REFS(opens in a new tab) stable-normative
Ref names, ref storage, and the compare-and-swap rules for a ref update.
SPEC-INDEX(opens in a new tab) stable-normative
The layout of the staging index file, including the stat cache.
SPEC-WORKTREE(opens in a new tab) draft-normative
Linked working trees: the split of state, discovery, and locking across trees.
SPEC-CONCURRENCY(opens in a new tab) draft-normative
The total order in which a kit process takes its locks.
SPEC-GC(opens in a new tab) stable-normative
Garbage collection: retention roots, the recovery log, and when an unreachable object goes.
SPEC-HISTORY-ORDER(opens in a new tab) draft-normative
The bounded order in which a server walks all parents of a commit, and the state it carries between pages.
Packs and transport
How objects and refs move between repositories.
SPEC-PACKFILE(opens in a new tab) stable
The packfile format that kit uses to upload, download and bundle objects.
SPEC-TRANSPORT(opens in a new tab) stable-normative
The transport verbs and the URL schemes: file, SSH, HTTPS, S3 and memory.
SPEC-TRANSPORT-CONNECT(opens in a new tab) draft-normative
The kit.transport.v1 Connect service, the remote protocol of kit+https remotes.
SPEC-HTTP-OBJECTS(opens in a new tab) draft-normative
Plain HTTP object serving, read authorization, URL tokens and proofs.
SPEC-SPARSE-CHECKOUT(opens in a new tab) stable-normative
A verifiable sparse checkout: complete tree metadata without the unselected file payloads.
Security and signing
Signatures and attestations: signing bytes, key storage, config trust and verifiable history.
SPEC-SIGNING(opens in a new tab) stable-normative
The exact bytes that an Ed25519 signature covers on a commit, remix or tag, and the domain separator.
SPEC-KEYSTORE(opens in a new tab) stable-normative
The key vault interface and its backends.
SPEC-WRITE-GRANTS(opens in a new tab) draft-normative
Owner-signed grants that let a key write to, or read from, the repositories of a namespace.
SPEC-CONFIG-SECURITY(opens in a new tab) normative
Which config keys a repository may set and which only the user may set.
SPEC-ATTESTATIONS(opens in a new tab) draft
Attestations about a commit: in-toto v1 statements in DSSE envelopes, and how kit stores and verifies them.
SPEC-RELEASE-THRESHOLD(opens in a new tab) draft-normative
BLS12-381 threshold signatures for a release. The wire bytes and the verifier path.
SPEC-HISTORY-PROOF(opens in a new tab) draft-normative
Proof that a commit is in the first-parent history of another commit.
Interop and subprocess protocols
Protocols for Git import and export, external signers and subprocess RPC.
SPEC-GIT-BRIDGE(opens in a new tab) draft-normative
A deterministic export of kit objects to Git objects.
SPEC-GIT-IMPORT(opens in a new tab) draft-normative
An import of Git objects into kit objects that the importer signs.
SPEC-EXTERNAL-SIGNER(opens in a new tab) draft
The protocol between kit and a signer that runs as a separate process, such as an HSM or a hardware key.
SPEC-RPC(opens in a new tab) stable-normative
The framed protobuf protocol that kit uses over stdio for signers and for kit serve.
Spec conventions
How to write and read the specs.
SPEC-CONVENTIONS(opens in a new tab) stable-normative
The shared vocabulary: requirement keywords, the status words, and the encoding notation.