Glossary

hav's vocabulary is small and precise. These terms mean exactly this everywhere: in the CLI and in these docs.

base

The origin link of an untied knot: the knot-and-snap it grew from (the buoy head at fork or last sync). Ancestry, log, and diff treat the base as a parent edge, and tie converts it into the real parent.

buoy

A named pointer to a knot: git's branch, minus checkout state. Buoys reference tied knots only, so knots name work and buoys name published history. Nobody is ever "on" a buoy; workspaces track them. Default: main.

capture

The scan that begins every command: walk the workspace, hash the files, record a new version of its knot if anything changed. The mechanism behind "the working copy is the knot."

cascade (auto-rebase cascade)

When a knot's snap is rewritten (edit capture, squash), every unheld descendant re-merges automatically and atomically, conflicts stored as data, buoy heads keeping their ids. Workspace-held knots are exempt, since files never move uninvited.

conflict (cf-…)

An object stored inside a snap: base plus both sides. Merges never block on one. It materializes as markers when projected and resolves by editing the file. Conflicts never nest.

crew

An immutable slug plus member public keys, the unit of sealing. Buoys under private-<slug>/ and knots born on them store encrypted, readable only by members. Creation wraps its key to the creator alone, and it answers only to its members. Beneath the slug sits a write-once random identity, so two crews created independently under one slug are different crews and never merge.

harbor

A thin HTTP server over a directory of bare hubs, the HTTP equivalent of a path remote. It holds no keys and validates pushes ciphertext-blind. Reads are anonymous, and one bearer token gates every push.

hub

A bare repo (hav init --bare) with no working tree and no workspace: a push/pull rendezvous point.

knot (kn-…)

The stable identity of a unit of work. A random id whose hash-chained versions carry snap + description + ancestry. The working copy is a knot, and curation appends versions without ever changing the id.

op (op-<n>)

One journal event per mutating command, carrying complete before/after views of the repo's mutable state. Powers undo/redo and atomic rollback.

pack

The compact storage form produced by hav pack: small objects solid-compressed together, large blobs content-defined chunked. Storage only: ids never depend on it, and packs never travel the wire.

pinned

A workspace tracking no buoy (after edit, or its buoy was deleted). It names its sync/tie targets explicitly.

projection

Writing a snap into a workspace directory. Differing files are written, vanished tracked files deleted, untracked files left alone (collisions backed up as .hav-saved). Happens only when asked.

retired

The state of squashed and discarded knots: hidden from log, not deleted. Objects remain until they age out of the journal and sweep runs.

reveal

Publishing sealed history by tying it into a public buoy with tie --reveal. Content re-homes as plaintext with ids unchanged. It is monotone: undo restores pointers but cannot unpublish bytes.

sealed

Stored encrypted under a crew's key. Sealed rows are ciphertext to non-members, hubs, and harbors alike.

variant set

The per-path set of variants a tree entry holds: at most one public variant (ordinary plaintext) plus any number of sealed variants, at most one per crew (variant sets). No crew owns a path, and each variant merges independently. A sealed variant is named by a keyed commitment rather than the plaintext hash, which would be a guessing oracle. Members resolve commitment → content, and everyone else sees an opaque stub that captures carry through untouched. A conflict variant is the same idea for a conflict: a public conflict object over commitments, resolvable by members, opaque to the rest.

active crew

The crew whose variants a workspace materializes and edits, set by hav crew use <slug> (cleared with --none). Local workspace state that never travels. Fresh workspaces and clones start with none.

snap (sn-…)

An immutable, content-addressed root tree, and parentless: no author, date, message, or ancestry in the hash. The record plane's only citizen.

stale base

An untied knot whose base knot was rewritten beneath it while a workspace held it (the cascade skips held knots). st points at hav sync, which refreshes in place.

sweep

The explicit space reclaimer: drops knot versions and objects nothing retained can reach, then compacts the database. The physical complement of journal retention.

tie

The one merge verb. Lands untied work onto a buoy (linear), fast-forwards or merges tied history (merge knots for genuinely diverged histories only), or joins two knots detached.

tied

Having parents written: landed, published history.

untied knot

A knot with no parents yet, only a base. Work in progress: fully navigable, never travels on push, history unwritten until tie. Invariant: parents == [] ⟺ base set (sole exception: the init root).

view

The complete mutable state recorded in every op: buoy positions, knot current-versions, workspace rows. Restoring a view restores the repo.

workspace (ws-<n>)

A directory plus a row {knot, base buoy, working-copy snap}. Any number per buoy; one per knot, ever. The place where drafts live and the unit that files-never-move protects.

Id grammar

<path>@N tags a hunk (1-based, per file, in diff order, recomputed per invocation and not stable across edits). main@sn-8c31 pins a buoy at a snap. Timestamps display as compact UTC (YYYY-MM-DDTHH:MMZ), and an unset time renders undated. All id arguments accept unique prefixes.