projects

package
v0.21.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 23, 2026 License: MIT Imports: 8 Imported by: 0

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

func List(galeHome string) ([]string, error)

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

func Lives(path string) bool

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

func Prune(galeHome string) error

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.

func Register

func Register(galeHome, projectPath string) error

Register records projectPath in the registry if absent. Creates the gale home and registry file as needed. Callers on command hot paths should treat failures as best-effort — a read-only gale home must never block install or sync.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL