Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The held state

headwater keeps a little of its own for each repository: the held state. It holds what headwater needs to answer without asking a source again, and the acknowledgements people give.

Outside the repository, shared by every checkout

headwater keeps its held state outside the repository’s content (28). A checkout’s status never shows it, and no commit carries it. Every checkout of one repository shares one held state, so an agent in one worktree and a pane in another read the same report and see the same acknowledgements.

The first store keeps it in the files under <git common dir>/headwater/, which every worktree of the repository shares, and keeps notes whole in the same directory (C.6).

CHECKOUTS ONE GIT COMMON DIRECTORY TWO SCANS AT ONCE main/ a person's checkout fix-acme-ui/ an agent's worktree bump-acme-client/ another agent's worktree the held state is in none of them (28) acme-app.git/ shared by every worktree headwater/ the held state, at a version notes, kept whole acknowledgements scan A reads at version 7 writes at 7: a new version scan B reads at version 7 writes at 7: refused (49) never half written (30)
Every worktree of a repository resolves to one git common directory, so every checkout shares one held state, and none of them holds it (28, 50). A write succeeds only while the held state is still at the version its scan read, all or nothing (49), so two scans at once never leave it half written (30).

Disposable, except acknowledgements

Everything in the held state but acknowledgements can be discarded, and the next scan rebuilds it with no report changed but the times it gives (29). A person who deletes the held state apart from its acknowledgements loses nothing a scan cannot fetch again: the next scan reports exactly what the last one did, at a new time (S9). Acknowledgements are the one thing no source can give back.

Two scans at once

Agents in many checkouts of one repository scan at once (section 9). Two scans of one repository at once leave the held state as one or the other would have left it. Neither leaves it half written, and no acknowledgement is lost (30, S8).

The store has two operations (B.5). A read returns a repository’s held state and the version it was read at (48). A write takes the version read and the next held state; it is all or nothing, and succeeds only if the held state is still at the version read (49). The first store writes a new file beside the old and renames it over the old, under a lock held for the write (C.6).

One reading per report

Every report is made from one reading of the repository state (31). A report never mixes the declarations of two repository states, so a scan that runs while a checkout moves reports one state whole.

No credentials

headwater reaches a source with the asker’s own credentials or with none, and never keeps a credential in its held state (38). Every checkout of the repository shares the held state, and nothing in it signs in anywhere.

Still to rule: questions 1, 28 and 31, and the statement’s own question on where the held state lives when several hosts share one repository, in Open questions.