Module commands 

Subcommand implementations. Each top-level command is its own module.

Dispatch lives in main.rs; business logic lives in library crates; this module is the thin presentation shim.

Modules

add

mkit add <path> / mkit add . — stage a file (or the whole worktree) into .mkit/index. add -p additionally stages individual hunks interactively (see run_patch).

attest

mkit attest — produce a signed DSSE attestation for a commit.

attest_factory

Factory helpers for building a Signer from CLI / config inputs.

bisect

mkit bisect start|good|bad|reset|skip|run — binary-search a history for the commit that introduced a regression. Backing state + search logic live in mkit_core::ops::bisect.

blame

mkit blame [-w] [-M] [-C] [--ignore-rev <rev>] [--ignore-revs-file <file>] [--ignore-rev-precise] [--first-parent] [--reverse] [<rev>] [-L <range>] <file> — line-level attribution.

branch

mkit branch — list / create / delete branches.

cat

mkit cat <hash> — decode and print an object by its hash.

cat_file

mkit cat-file (-t | -s | -p) <object> — inspect an object, like git cat-file.

checkout

mkit checkout <branch> — switch HEAD to a branch and materialise the branch tip’s tree into the working directory.

cherry_pick

mkit cherry-pick <commit> | --continue | --abort — replay a single commit onto HEAD, with a resolvable-conflict workflow (#177).

clean

mkit clean — remove untracked files from the worktree (like git clean).

clone

mkit clone <url> [<dir>] — initialise a new repo and pull from the URL. The destination defaults to the final path segment of the URL when <dir> is omitted.

commit

mkit commit — build a signed commit object from the staging index.

config_cmd

mkit config — show or set values.

conflict

Shared CLI helpers for the resolvable-conflict workflow (#177).

diff

mkit diff — show changes as a unified patch.

fetch

mkit fetch [<remote>] — like pull but does NOT move HEAD. Downloads every object reachable from each remote ref and updates the refs/remotes/<remote>/<name> tracking refs.

for_each_ref

mkit for-each-ref [--format=<fmt>] [<pattern>...] — iterate refs with an optional format string, like git for-each-ref.

gc

mkit gc — reclaim unreachable objects (mark-and-sweep prune).

git

mkit git — the git bridge subcommands (feature git-bridge): deterministic export to git mirrors (SPEC-GIT-BRIDGE) and, as the phases land, importer-signed import (SPEC-GIT-IMPORT).

git_import

mkit git import / mkit git fetch / mkit git pull — the importer-signed git→mkit direction (SPEC-GIT-IMPORT; feature git-bridge).

git_tools

mkit git verify / status / format-patch (feature git-bridge): bridge-state inspection and audit.

hash_cmd

mkit hash <file> — hash a file as a blob, store it, print the hash.

init

mkit init — create a fresh repository rooted at the current dir.

key

mkit key keystore management commands.

keygen

mkit keygen — generate a fresh signing key for one of the three attestation algorithms.

log

mkit log [<rev>] [<A>..<B> | <A>...<B>] — walk commit history.

ls_files

mkit ls-files [-s] [-z] [--others] [--ignored] [--exclude-standard] — list files in the index or untracked worktree files, like git ls-files.

ls_tree

mkit ls-tree [-r] [-z] <tree-ish> [<path>...] — list the entries of a tree, like git ls-tree.

mcp

mkit mcp — a local Model Context Protocol server over stdio.

merge

mkit merge <branch> | --continue | --abort — merge a branch into HEAD, with a resolvable-conflict workflow (#177).

merge_base

mkit merge-base [--is-ancestor] <a> <b> — print the best common ancestor of two commits, or test ancestry. Reuses the merge engine’s find_merge_base / is_ancestor (the algorithms already power merge/rebase). Object ids are full 64-hex BLAKE3 (the documented hash-length divergence); everything else matches git.

mv

mkit mv <source>... <dest> — move or rename tracked paths, staging the change (like git mv).

pack_shard

mkit pack-shard <hash> — encode an existing pack into Reed-Solomon shards plus a manifest.

pull

mkit pull [<remote>] — fetch refs from the configured remote (named, or the flat default) and fast-forward the current branch.

push

mkit push — push refs/packs to a remote with CAS safety.

rebase

mkit rebase [-i] <revspec> | --continue | --abort | --skip — replay commits onto a different base. The target is resolved through the shared revspec resolver, so a branch, tag, HEAD~n, or full/short hash all work.

ref_cmd

mkit ref list [--pattern <glob>] / mkit ref cat <name> — stable ref-inspection plumbing (#652).

reflog

mkit reflog [<ref>] — read-only view over the persisted ref-history journal (issue #231).

remote

mkit remote — show / add / set the configured remote.

reset

mkit reset [--soft|--mixed] [<commit>] — move the current branch (or detached HEAD) to <commit>, optionally resetting the index.

restore

mkit restore [--staged] [--worktree] [--source <rev>] [-f] <path>... — discard worktree changes for path(s), or unstage them.

rev_list

mkit rev-list [--count] <rev> — list the commit ids reachable from <rev> in reverse-chronological (topological) order, or just their count. Reuses log’s ordered walk so ordering matches mkit log. Object ids are full 64-hex BLAKE3 (the documented divergence).

rev_parse

mkit rev-parse [--verify] [--short[=N]] [--abbrev-ref] [--show-toplevel] [<rev>...] — resolve revisions to object ids, like git rev-parse.

revert

mkit revert <commit> | --continue | --abort — create a new commit that undoes a previous commit, with the resolvable-conflict workflow.

revspec

Shared revision-spec resolver (issue #227, parent #226).

rm

mkit rm <pathspec>... — remove paths from the worktree and stage the deletion for the next commit.

self_update

mkit self — self-management of an installer-managed mkit binary.

serve

mkit serve <path> — speak the mkit-rpc SSH protocol on stdin/stdout against a local repository.

show

mkit show [<object>...] — display objects (default HEAD).

show_ref

mkit show-ref [--heads] [--tags] — list refs as <hash> <refname>, like git show-ref. Output is sorted by full ref name; the hash is a 64-hex BLAKE3 id (vs git’s 40-hex SHA-1).

sparse_checkout

mkit sparse-checkout set|list|disable|reapply — manage the sparse checkout pattern set at .mkit/sparse-checkout. Pattern parsing + tree-materialisation live in mkit_core::ops::restore.

stash

mkit stash save|list|pop|drop|show — stash working-directory changes. Backing logic lives in mkit_core::ops::stash.

status

mkit status — show working-tree changes relative to HEAD.

summary

Shared git-shaped post-commit summary: the [<branch> <hash>] <subject> headline, the diffstat, and the create/delete mode trailers. Used by commit / cherry-pick / revert / merge so their human output matches git’s. All lines go to the caller-provided writer (the commands route it to stderr, per mkit’s channel rule).

switch

mkit switch — git’s modern branch-switch UX, a thin front-end over mkit checkout. switch <branch> switches to an existing branch; switch -c <new> [<start>] creates a branch and switches to it; switch -C <new> [<start>] creates-or-resets it. All the safety guards and output strings come from checkout unchanged.

symbolic_ref

mkit symbolic-ref [--short] <name> [<ref>] — read or write a symbolic ref (currently only HEAD), like git symbolic-ref.

tag

mkit tag — list / create / delete tags.

tree

mkit tree — snapshot the working directory as a tree object, printing the resulting tree hash.

trust

mkit trust — manage the commit-history allowed-signers file that mkit verify --trusted cross-checks a commit/remix/tag’s signer against.

trust_roots

Shared trust-roots TOML file model.

update_ref

mkit update-ref [-d] <ref> [<newvalue> [<oldvalue>]] — low-level guarded ref write/delete, like git update-ref.

verify

mkit verify <rev> — verify the signature on a commit, remix, or signed tag.

verify_attest

mkit verify-attest — verify every attestation attached to a commit.

worktree

mkit worktree — manage linked working trees (#493 Phase 2).

Constants

WORKTREES_REGISTRY_LOCK

Basename of the common-dir lock serialising linked-worktree registry mutations (worktree add/remove/prune), the branch-checkout guard + HEAD-write critical sections (checkout/switch, branch -d/-m), and gc’s freeze of the worktree set. Distinct from WORKTREE_LOCK, which guards ONE tree’s worktree/index state.

WORKTREE_LOCK

Basename of the repo-level lock that serialises worktree/index read-modify-write commands (add, rm, commit, merge, checkout, rebase, cherry-pick, stash, sparse-checkout).

Functions

acquire_worktree_lock

Acquire the shared worktree/index lock for this worktree.

acquire_worktrees_registry_lock

Acquire the shared worktree-registry lock (common dir).

delete_ref_dropping_history

mkit branch -m helper: deletes the OLD name’s ref after a rename and, on --features history-mmr builds, also destroys its history-MMR journal partition (issue #648).

delete_ref_dropping_history_if_matches

CAS-guarded sibling of delete_ref_dropping_history (issue #658): only deletes branch (and, on --features history-mmr builds, destroys its journal) if its current value is exactly expected.

delete_ref_recording_history

mkit branch -d/-D helper: deletes a branch ref and, on --features history-mmr builds, also destroys its history-MMR journal partition (issue #648). Refuses the checked-out branch, same as plain refs::delete_ref_safe.

ensure_restore_safe

Refuse a destructive restore when the index/worktree contains user work.

ensure_restore_safe_with_options

Refuse a destructive restore when affected index/worktree paths contain user work.

head_branch_name

Current branch name for recovery logging — empty for a detached HEAD or an unreadable/symbolic-only HEAD.

not_yet_ported

Shared helper: emit a “not yet wired” notice and return the tempfail exit code. Commands whose backing state-machines haven’t been wired into the CLI yet say so honestly rather than pretending to work.

open_store_configured

batched default when the config cannot be read — a broken config must not change write semantics silently, and Batch is the default contract.

read_or_seed_index_from_head

Read the index, seeding an absent/empty one from HEAD when possible.

record_superseded

Record superseded (the old branch tip a history-rewriting op is about to replace) in the recovery log so mkit gc keeps it recoverable.

resolve_layout

Resolve the RepoLayout a command operates on (#493 Phase 1): pointer-following discovery. A .mkit DIRECTORY (or none at all) resolves to the classic single-worktree layout exactly as before; a .mkit pointer FILE resolves to the linked tree’s split layout. On a broken pointer the error has already been printed and the returned code is the exit status to propagate — a broken linked tree must never silently operate on the wrong directory. Command code must obtain its layout HERE and never construct one ad hoc.

restore_worktree_and_index

Materialise tree_hash and align the index while preserving .mkitignore entries.

stage_removed_tombstones

After staging a result_tree (which, being a tree, omits removed paths), add Removed tombstones to the index for every path present in base_tree but absent from result_tree.

sync_index_to_tree

Rewrite .mkit/index so it exactly mirrors tree_hash.

usage_error

Shared helper: print a usage error and return the USAGE exit code.

write_ref_recording_history

CLI-side ref-write helper that records every advance in the branch’s history MMR when history-mmr is enabled.