Documentation
¶
Overview ¶
Package projects maintains the machine-local project registry at <gale home>/projects: one absolute project path per line, appended as a side effect of normal project-scoped use (env activation, sync, install, ...).
The registry exists for gc liveness (gh#115): without it, gc can only see the global generation and the generation of the project it happens to run from, so it sweeps store versions that OTHER projects' active generations still link. gc unions retention across every registered project instead.
Concurrency model: mutations serialize on <gale home>/projects.lock (flock), so a Register racing a Prune can never append to the inode Prune just replaced or be overwritten by the rewrite — a silently dropped entry would let a later gc sweep that project's store versions, the exact bug the registry exists to prevent (gh#115). The lock is held only around the file writes, never across liveness stats: Register runs on command hot paths (direnv's gale env, sync), so it dedup-checks lock-free and locks only to append, and Prune stats liveness before locking — a stat on a dead network mount must not wedge every concurrent gale command. Under the lock each re-reads the file, so decisions made on the lock-free read stay sound: Prune drops only entries dead at scan time (anything appended since survives until the next prune), and Register's lock-free dedup hit is safe because a project being registered exists, so Prune keeps it. List stays lock-free: Prune rewrites via atomic rename, so a plain read always sees a complete file.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func List ¶
List returns the registered project paths, in file order, with blank lines and duplicates dropped. A missing registry is an empty list, not an error (fresh install).
func Lives ¶
Lives reports whether path still looks like a gale project: a gale.toml, or the .tool-versions fallback gale's config loading honors. Prune keeps live paths; gc retains live projects' generations.
Dead means provably absent: every stat fails with fs.ErrNotExist. Any other stat error (EACCES, EIO, a flaky network mount) does not prove the project vanished, so it counts as live — gc's principle is conservative retention, and a transient error must never let the store sweep delete a still-active project's versions. This includes ENOTDIR (project path replaced by a regular file), which is not fs.ErrNotExist: treating it as live merely delays pruning of a rare stale entry, so simplicity wins over a special case.
func Prune ¶
Prune rewrites the registry dropping only provably vanished projects: paths whose gale.toml AND .tool-versions (gale's config fallback) stat as fs.ErrNotExist. A vanished project needs no gc retention, so gc calls this before computing liveness. Entries whose liveness stat fails any other way (see Lives) stay registered — keeping them is safe, dropping them is not.
Types ¶
This section is empty.