Documentation
¶
Overview ¶
Package gitstate reads what the repository was, so a checkpoint does not have to rely on being told.
Everything else logos records is model-initiated: an agent decides to call checkpoint, and if it does not, nothing happens. That is the single largest reliability gap in the product — the core promise depends on a host model remembering a tool at the one moment it is least likely to.
Git state is the part that needs no cooperation. Branch, commit, dirty files and diffstat are all questions `git` will answer whether or not the agent thought to mention them. So a checkpoint gets two halves:
what the agent said — task, decisions, dead ends, next step what the repo was — branch, sha, dirty files, diffstat
Only the first can be forgotten. The second is why an arriving agent can trust "this was true at a3f9c2" rather than "this was true at some point".
Everything here degrades to the zero value. A directory that is not a repo, a git that is not installed, a detached HEAD, a repo with no commits: each returns an empty State and no error, because a checkpoint that refuses to save because git was unavailable would be worse than one without a sha.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Head ¶ added in v0.4.5
Head is the branch and short commit of the tree at dir, each "" when git will not say. It exists for readers that only need to know whether the tree has moved since a checkpoint: Read shells out five more times for a diffstat and a file list nobody is going to look at on that path.
func Identity ¶
Identity is origin's URL and the main checkout's path for the repository at dir, each "" when git will not say.
Both, because either alone misjudges an ordinary case: a clone on another machine has a different path and the same remote, and a repository that got its remote after its first checkpoint has the same path and a new remote.
func WorktreeName ¶
WorktreeName is git's own name for the linked worktree at dir, and "" when dir is the main checkout, is not a repository, or git will not answer.
It is the name and not the path because this is what continuity is scoped by — a folder that gets moved is the same worktree, exactly as a project that gets moved is the same project. Git allocates the name itself, in the admin directory it keeps per worktree (<repo>/.git/worktrees/<name>), and guarantees it is unique inside the repository: two worktrees whose folders happen to share a basename still get distinct names, which a scope derived from the folder could not promise.
Types ¶
type State ¶
type State struct {
// Branch is the current branch, or "" when detached or unavailable.
Branch string
// Commit is the short HEAD sha. The field that makes everything else
// verifiable — a decision recorded against a commit can be checked out.
Commit string
// Subject is HEAD's commit subject, so the sha means something to a reader.
Subject string
// Dirty is the count of files with uncommitted changes. Zero means clean,
// which is itself worth recording: "clean at this sha" is a much stronger
// handoff than "somewhere near this sha".
Dirty int
// Files are the paths with uncommitted changes, capped. These are what the
// session actually touched, observed rather than reported — an agent's own
// Files list is a claim, and this is evidence.
Files []string
// Insertions and Deletions summarise the uncommitted diff.
Insertions int
Deletions int
// Worktree is set when this is a linked worktree rather than the main one,
// because "same project, divergent parallel state" is exactly where
// continuity breaks and the checkpoint should say which one it meant.
Worktree string
// Remote and Root say which repository this was, because a project is only
// a name and "api" is two unrelated repositories on most machines. Remote
// is origin's URL; Root is the main checkout, shared by its worktrees.
Remote string
Root string
}
State is the repository as it stood when a checkpoint was written.
func Read ¶
Read gathers the repository state at dir. Never returns an error: absence of git state is a normal condition, not a failure.
Source Files