Documentation
¶
Overview ¶
Package wbhome resolves the directories WB uses to coordinate work across agents and sessions: task worktrees, operation locks, and reports.
That directory used to live at <projects-root>/.wb. A recursive tool that doesn't know WB's exclusion rules — a search indexer, backup, an ad-hoc grep — walks straight into it and double-counts every in-flight worktree as a separate repository. Moving the default to the user's home directory makes "don't walk into WB's state" the default for every tool, not a rule each one has to learn.
Index ¶
Constants ¶
const EnvMigrationCompat = "WB_HOME_MIGRATION_COMPAT"
EnvMigrationCompat is written only by a managed hook that pinned the normal default home at installation time. Its value must be that resolved default home, rather than a generic boolean. This lets the resolver distinguish the one migration-compatible hook context from an arbitrary explicit WB_HOME.
const EnvOverride = "WB_HOME"
EnvOverride names the environment variable that pins WB's home directory, overriding both the new default and legacy detection. Tests use it to stay hermetic; operators use it for unusual layouts.
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. It remains for callers that only create state; worktree migration-aware callers must use Resolve.
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.
Types ¶
type Layout ¶ added in v0.22.2
Layout is one supported on-disk WB state layout. Home is the parent of its worktrees, locks, and reports. Legacy is true only for the historic <projects-root>/.wb layout that remains readable during the migration.
type Resolution ¶ added in v0.22.2
Resolution makes the migration policy explicit. Write is the only layout where new state may be created; Read contains Write plus a discovered legacy layout when the default migration path can safely support it.
An explicit WB_HOME is intentionally authoritative: it is commonly used by parallel agents and hermetic tests, neither of which may accidentally scan or mutate a neighbouring projects-root legacy directory.
func Resolve ¶ added in v0.22.2
func Resolve(projectsRoot string) (Resolution, error)
Resolve returns the write home and every compatible read layout for one projects root. New state always belongs under ~/.wb by default; the legacy projects-root directory is never selected as a silent write fallback.
Source Files