gitstate

Documentation

Overview

Package gitstate reads what the repository was, so a checkpoint does not have to rely on being told.

Everything else brain 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

• func WorktreeName(dir string) string
• type State
  • func Read(dir string) State
  • func (s State) Empty() bool
  • func (s State) Summary() string

Functions

func WorktreeName

func WorktreeName(dir string) string

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
}

State is the repository as it stood when a checkpoint was written.

func Read

func Read(dir string) State

Read gathers the repository state at dir. Never returns an error: absence of git state is a normal condition, not a failure.

func (State) Empty

func (s State) Empty() bool

Empty reports whether anything was learned. Callers use it to decide whether to record a git section at all rather than writing an empty one.

func (State) Summary

func (s State) Summary() string

Summary renders the state as one line for a checkpoint's frontmatter or a report. Empty when there is nothing to say.