Documentation
¶
Overview ¶
Package wbhome resolves the directories WB uses to coordinate work across agents and sessions: task worktrees, operation locks, and reports.
Every one of those paths derives from a single projects root. --projects-root (the flag) wins over WB_PROJECTS_ROOT (the environment), which wins over the default root, ~/projects. Private state lives at <root>/.wb and the checkout store at <root>/.worktrees — both dot-named direct children of the root, siblings of the {host} directories, so a single-level enumeration of the root (a `*` glob, a bare `ls`) yields host directories only. WB_HOME no longer selects anything.
Index ¶
Constants ¶
const EnvMigrationCompat = "WB_HOME_MIGRATION_COMPAT"
EnvMigrationCompat is written only by a managed hook installed by an earlier release. It has no effect on path derivation any more; the constant remains until the hook shims stop emitting it.
const EnvOverride = "WB_PROJECTS_ROOT"
EnvOverride names the environment variable that selects WB's projects root. The --projects-root flag wins over it. WB_HOME is deliberately not consulted: it used to name the state directory directly, which made the state directory and the checkout store independent knobs.
Variables ¶
This section is empty.
Functions ¶
func EnsureHome ¶ added in v0.23.0
EnsureHome creates home (and any missing ancestor, e.g. a projects root a test fixture hasn't created yet) if it doesn't exist — refusing to accept a symlink already planted at that exact path — and seeds it with a README. It does not guard ancestor components against a symlink the way the worktree-create path's descriptor-anchored open does; its callers never had that guarantee before this function existed either.
func EnsureRoot ¶ added in v0.23.0
EnsureRoot resolves WB's authoritative write home exactly like Root, then ensures the directory exists and carries a README explaining what it is. Use this for callers about to create state under home with no home-directory hardening of their own; see Root's doc for the one caller that must not.
func Root ¶
Root resolves WB's authoritative write home: <root>/.wb. It remains for callers that only create state.
Root never creates the directory itself: worktrees.Create opens this same path through its own descriptor-anchored, symlink-rejecting check, and that check needs the first, unhardened look at whether anything already sits there. Callers with no hardening of their own should call EnsureRoot instead, so the home directory still stays self-documenting.
func SeedReadme ¶ added in v0.23.0
SeedReadme writes README.md into home if one isn't already there. An existing README — including one an operator customised — is left alone. Callers must have already established that home is a real directory.
func StoreRoot ¶ added in v0.135.0
StoreRoot returns the central checkout store for a projects root: <root>/.worktrees. It is the write layout's physical checkout root — the same value as Resolve(root).Write.WorktreesRoot — and the path a later store-mode implementation places task checkouts under. It does not create anything.
Types ¶
type Layout ¶ added in v0.22.2
type Layout struct {
Home string
WorktreesRoot string
Legacy bool
// Local is true only for a canonical repository's default
// <canonical>/.worktrees root. Home remains the state-directory authority.
Local bool
}
Layout is one supported on-disk WB location set. Home is the private coordination state directory (claims, locks, Work Logs, reports) and WorktreesRoot is where checkouts physically land for that layout. Legacy is true only for a retired home whose checkouts remain readable in place.
func (Layout) StateWorktreesRoot ¶ added in v0.135.0
StateWorktreesRoot is the logical task namespace inside the private state directory: <Home>/worktrees. It holds coordination state — task shells, locks, retired locks — and is deliberately distinct from WorktreesRoot, which is a physical checkout store and may sit outside the state directory.
type Resolution ¶ added in v0.22.2
type Resolution struct {
Write Layout
Read []Layout
// Root is the projects root every path above derives from.
Root string
}
Resolution is the layout for one projects root. Write is where new state may be created; Read contains Write plus any additional readable layout.
func Resolve ¶ added in v0.22.2
func Resolve(projectsRoot string) (Resolution, error)
Resolve returns the write layout and every compatible read layout for one projects root. An empty projectsRoot falls back to WB_PROJECTS_ROOT and then to the default root.
The write layout derives both paths from that one root: private state at <root>/.wb and the checkout store at <root>/.worktrees. A retired default state directory ($HOME/.wb) is added as a read-only legacy layout when it still holds checkouts, so guard, inventory, cleanup and relocate keep operating on existing placements in place instead of going blind to them.
Source Files