Documentation
¶
Overview ¶
Package trunk reads entity ids visible in git refs for the allocator's cross-branch view. Its primary surface, Read, scans the configured trunk ref's tree, applying the policy from id-allocation.md:
Not a git repository at all → skip. Tooling that legitimately runs outside a repo (test fixtures, exploratory invocations on plain directories) has no cross-branch surface to police.
Configured trunk ref resolves → return the (kind, id, path) triples found under work/ and docs/adr/ in that ref's tree.
Trunk ref missing AND was explicitly set in aiwf.yaml → hard error. The user named a specific ref; if it doesn't exist they should fix the typo or fetch it. Silent degradation would defeat their explicit intent.
Trunk ref missing AND was the default (no allocate.trunk in aiwf.yaml) AND no refs/remotes/* tracking refs exist → skip. Covers "no remote configured" (sandbox repos), "remote configured but never fetched" (transient setup), and "freshly cloned an empty bare" (canonical first-push setup, where the bare has no branches so the clone has none either). None has anything to collide with.
Trunk ref missing AND was the default AND tracking refs DO exist → hard error. The remote has been populated; an unresolvable default trunk is a real misconfiguration (the team's trunk is named something other than main, or the consumer hasn't fetched it). Setting allocate.trunk in aiwf.yaml fixes it.
LocalRefIDs is the second surface: it widens that view to every local branch ref (refs/heads/*) for the allocator only — never the ids-unique check — so a sibling worktree's freshly-committed id is seen at allocation time (M-0212).
The package is read-only and has no per-process cache; callers invoke once per verb run.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LocalRefIDs ¶ added in v0.20.0
LocalRefIDs returns the entity id strings reachable from every local branch ref (refs/heads/*) in workdir's repository. It is the allocator's broadened cross-branch view (M-0212): a sibling git worktree's freshly-committed entity already lives in the shared local refs, so unioning these ids into the allocator's max keeps the next allocation from colliding with it (G-0272 class 1).
Best-effort and read-only: it never returns an error. On any odd repo state — not a git repository, no local branches, or a ref that lists but fails to read — it degrades to the ids it could collect (down to none), never blocking or failing the caller's allocation (M-0212/AC-2). The scan narrows the collision window; it is not a correctness gate, and the irreducible cross-machine race stays `aiwf reallocate`'s to cure.
Unlike Read, the result feeds the allocator ONLY — never the ids-unique trunk-collision check, which keeps its working-tree-vs- trunk basis. Folding every sibling branch into the uniqueness comparison would false-flag the same entity present on two branches (e.g. a feature branch forked from main); E-0052's decision is to take only the prevention half here.
Cost is one `git ls-tree` per local branch — O(local branches) subprocesses per call. Trivial at the solo / handful-of-branches scale this targets; it grows linearly, so a repo carrying hundreds of stale local branches would pay for them on every allocation.
func RemoteRefIDs ¶ added in v0.20.0
RemoteRefIDs returns the entity id strings reachable from every remote-tracking ref (refs/remotes/*) in workdir's repository — the remote-side mirror of LocalRefIDs (M-0214). An entity pushed to any remote branch (a teammate's not-yet-merged work, a CI checkout) is visible in the local remote-tracking refs, so unioning these ids into the allocator's max keeps the next allocation from colliding with it (G-0316).
Same best-effort, allocation-only contract as LocalRefIDs: it never returns an error, degrades to nil on odd repo states, and feeds the allocator ONLY — never the ids-unique check, which keeps its working-tree-vs-trunk basis.
Types ¶
type ID ¶
ID names one entity that exists in the trunk ref's tree, by kind, id string, and the repo-relative path the trunk has it at.
type Result ¶
Result carries the trunk ids visible to the allocator and the cross-tree check. Skipped is true when the repo has no remotes and the trunk read was deliberately bypassed.
Source Files