Expand description
mkit reflog [<ref>] — read-only view over the persisted
ref-history journal (issue #231).
§What the journal actually records
mkit’s ref-history is the per-branch, append-only commit-history
MMR (mkit_core::history::CommitHistory, the refs-history.lock
journal written by write_ref_recording_history). On every branch
advance — commit, branch creation, merge, rebase, cherry-pick,
amend, fetch/pull tip update — the new tip hash is appended as one
leaf. The journal therefore stores:
- the count of recorded advances (
len()), and - a tamper-evident root plus per-leaf inclusion proofs.
It deliberately does not store what a Git reflog stores: there
is no op label, no old→new pair, no per-entry timestamp or message,
and — crucially — the leaf digests are BLAKE3 values with the leaf
position mixed in, so the original commit hashes cannot be read
back out of the MMR. The MMR can only confirm a hash you already
hold (via verify_inclusion).
§What mkit reflog therefore surfaces
Because the readable hashes can only come from the object store, not
the MMR, reflog walks the branch tip’s first-parent chain
(newest → oldest) — the same reconstruction
history::rebuild_from_chain uses — and presents it as the branch’s
movement history, addressed <branch>@{N} with @{0} = current
tip. On a build with --features history-mmr it additionally
cross-checks each commit against the journaled MMR root: it asks
the journal to confirm, via an inclusion proof, that the commit was
recorded as a branch advance at some leaf position. The
recorded-advance count is reported in the summary line. The check is
rewrite-robust — a reachable commit shows [journaled] as long as it
was journaled at some point, even after a later amend/reset shifted
the journal’s leaf count past the reachable chain length.
This is not a full Git reflog: @{N} indexes the reachable
first-parent chain (which drops superseded commits — e.g. after an
--amend or a reset the old tip is no longer listed), not the raw
append log of every movement. See the help text / man mkit for the
exact contract.
Read-only: this command never mutates refs, the journal, or any object.