Lock files

Lock files

Shelf keeps two kinds of lock.

Runtime lock, in the data directory:

~/.local/share/shelf/plugins.lock
~/.local/share/shelf/plugins.<profile>.lock

Holds resolved templates, installed paths, selected files, recorded revisions, clone options, and remote ETags. shelf source reads this and nothing else on its fast path, which is why startup does not touch the config. Never commit it, it contains absolute paths from your machine.

Revision manifest, next to the config file:

~/.config/shelf/plugins.lock
~/.config/shelf/plugins.<profile>.lock

Holds only git plugin names and their resolved revisions. Commit it alongside config.toml for reproducible versions. Local, remote, and inline plugins are omitted on purpose, they have no revision to pin.

Manifest flow: plain lock and source --relock apply pinned revisions from the manifest, so a fresh clone on another machine gets the same commits. lock --update and update --lock fetch current revisions and rewrite it.

Concurrent shelf processes coordinate through a lock on the config directory, shared for reads, exclusive for writes. A second process prints Blocking waiting for file lock on <dir> on stderr and waits instead of racing.