README.md

mkit

status: alpha License: MIT OR Apache-2.0 crates.io docs.rs codecov

Version control you can prove. mkit is a content-addressed version control toolkit written in Rust.

mkit gives you what you expect from Git: commits, refs, branches, and remotes. It also treats signatures and attestations as part of the object model. Every commit carries an Ed25519 signature, and any service can attach witness signatures to it as in-toto v1 Statements in DSSE envelopes.

[!NOTE] Alpha (pre-1.0). The v1 on-disk and wire formats are stable through the 0.x line, pinned by golden vectors. APIs, CLI flags, and unpinned internals may change in any 0.x release. See CHANGELOG.md.

Install

curl mkit.sh | sh

The script downloads the signed release binary for your platform, verifies its cosign signature, and installs mkit into ~/.local/bin.

Linux release archives require glibc 2.39 or newer; see Linux requirements and workarounds.

Other options:

cargo install mkit-cli                        # crates.io (Rust 1.95+)
bun add @officialunofficial/mkit-wasm         # WASM, or: npm i @officialunofficial/mkit-wasm

[!WARNING] Do not run cargo install mkit. That crate name belongs to an unrelated project. The CLI is published as mkit-cli.

mkit supports Linux and macOS. On Windows, run it under WSL. docs/INSTALL.md covers pinned versions, release archives, verification (cosign, SHA256SUMS), and hardware signers.

Quick start

mkit init                      # create .mkit/ in the current directory
mkit keygen                    # generate an Ed25519 signing key
echo hello > hi.txt
mkit add hi.txt
mkit commit -m "first commit"

mkit remote add origin mkit+file:///srv/mkit/my-repo
mkit push origin               # first push records origin as the upstream
mkit push                      # later pushes go to the upstream

That's your first signed commit. Push rejects non-fast-forward updates unless you pass --force-with-lease or --force.

Attest to the commit, then verify the attestation:

mkit attest --predicate-type https://example.com/sign-off/v1
mkit verify-attest --trust-roots .mkit/attest-trust-roots.toml

verify-attest trusts only keys you register with mkit trust add. SPEC-ATTESTATIONS §6.5 walks through trust roots. The full command reference is in docs/CLI.md. Coming from Git? Read docs/GUIDE-GIT-WORKFLOWS.md.

Why mkit

• One hash, everywhere. An object's ID is the BLAKE3 hash of its canonical serialization. There is no algorithm negotiation and no SHA-1/SHA-256 split. Large files split into content-defined chunks, so a small edit costs only the edit. See SPEC-OBJECTS.
• Attestations built in. mkit attest stores in-toto v1 Statements in DSSE envelopes, with the commit hash as the subject. Standard tools such as cosign and in-toto-go can verify them, and one envelope can carry several signatures. See SPEC-ATTESTATIONS.
• Keys stay where you want them. Keys can live in an encrypted software vault, the macOS Keychain, Linux Secret Service, systemd-creds, or a YubiKey. External signers (TPM 2.0, FIDO2/CTAP, Apple Secure Enclave) plug in over a v1 stdio protocol. One key reference covers commit signing, attestations, and SSH push auth. See SPEC-KEYSTORE.
• Strict transports. The URL scheme picks the transport: mkit+file://, mkit+https://, mkit+s3://, mkit+ssh://, or mkit+enc:// (deprecated: no maintained server). mkit never falls back to another transport. See SPEC-TRANSPORT.
• Proof without a clone. Anyone holding a trusted commit ID can prove that a path, chunk, or whole object set belongs to it. See docs/VERIFY.md.
• Script-friendly CLI. Data goes to stdout and diagnostics to stderr. Read commands support --format=json, and exit codes follow sysexits(3).

Performance

mkit pulls clearly ahead of Git on large files and their edits, and runs roughly even on everyday operations. Pack creation for 100 files of 1 MiB each:

Pack creation wallclock at 100 files x 1 MiB: mkit finishes in 143 ms versus 1,645 ms for git2 and 2,957 ms for git pack-objects

The performance page has end-to-end add/commit/push comparisons with Git and the methodology. More microbenchmarks live in benchmarks/charts/. Reproduce them with:

cargo bench -p mkit-benches --bench hashing --bench sign_verify \
  --bench object_commit --bench pack_create -- --quick
cargo run -p mkit-benches --bin render-charts

Documentation

Want the library instead of the CLI? Run cargo add mkit-core (docs.rs).

Build and contribute

cd rust
cargo build --release                       # → target/release/mkit
cargo test --workspace
cargo fmt --check
cargo clippy --all-targets -- -D warnings

The MSRV is Rust 1.95.0, pinned in rust/rust-toolchain.toml.

Issues and PRs are welcome. CONTRIBUTING.md covers build, test, and style expectations. Inbound contributions use the project license, with no DCO or CLA. Follow docs/STYLE-GUIDE.md for docs and commit messages.

To report a security issue, follow SECURITY.md.

License

mkit is dual-licensed under MIT or Apache-2.0, at your option. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion is dual-licensed the same way, with no additional terms or conditions.

mkit is published by Official Unofficial, Inc., which owns the mkit name and marks.