-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Four suspects, in order of how often they are the cause.
- No files matched. Shelf looks for
<name>.plugin.zsh,*.zsh,*.sh, and friends in zsh,<name>.plugin.bash,*.bash,*.shin bash. A repo whose only script isinit.zshundersrc/matches nothing. Setuse = ["src/*.zsh"]. - Wrong subdirectory. Add
dir = "...". - Shell mismatch. A
*.bashplugin in a zsh config matches nothing useful. Checkshellin the config. - Stale lock. Run
shelf lockand open a new shell.
shelf info NAME shows exactly which files the lock selected.
The lock no longer matches the config fingerprint, the profile, the shell, or the installed files. You edited the config, switched profile, or a plugin file disappeared. Running shelf lock fixes it, and plain shelf source fixes it too because it relocks automatically when verification fails.
--force only widens an existing operation, it updates frozen plugins during an update or reinstall. Alone it has nothing to widen, so shelf refuses instead of guessing. Write shelf lock --update --force.
Another shelf process holds the config directory lock, usually a concurrent shelf source from a shell that just started. It is not an error. The message comes from shelf's own file lock, and the process proceeds as soon as the lock frees. If it never clears, a crashed process left the lock behind, and the file lock releases when the holder exits.
--profile wrk with every plugin either unprofiled or profiled work means no plugin listed wrk. Shelf warns on stderr and loads the unprofiled plugins anyway. Compare against grep profiles config.toml.
No. The zsh scheduler drains when zle first goes idle, which requires a prompt. Non-interactive zsh never draws one, so deferred plugins stay unloaded. This is a limit of prompt-time loading in general, not a shelf bug. Use plain source for anything that must run non-interactively.
Both render as plain source lines. Bash has neither a prompt-time hook shelf can rely on nor a zcompile builtin. The point is that one config stays valid in both shells, nothing fails, nothing is compiled, nothing is deferred.
Commit the one in the config directory, it holds only plugin names and revisions and makes your setup reproducible. Do not commit the one in the data directory, it holds absolute paths and machine-specific state. shelf path prints the runtime lock's location for the active profile.
Clone options apply to fresh clones only. Re-clone with shelf lock --reinstall (or shelf source --reinstall). The new depth is recorded in the lock, so later reinstalls keep it.
shelf path # data_dir
shelf info zsh-autosuggestionsGit sources land in repos/<host>/<owner>/<repo>, downloads in downloads/<host>/<path>. shelf info sums the installed directory for you. shelf clean removes anything the config no longer owns.
Everything except the script goes to stderr: Loaded, Locked, warnings, errors. $(...) captures stdout only. Pipe it the other way by accident, shelf source 2>&1, and the diagnostics corrupt the script, which is the classic way to break this.
Any failure. Shelf prints error: <message> on stderr and exits 2, for every command. Exit 0 is success. There is no third code to special-case.
frozen = true is a per-plugin promise recorded in the lock. shelf update, shelf lock --update, and shelf source --update skip it and report Frozen. Skipping by hand, by just not running update, means the lock goes stale against upstream. Frozen keeps the lock honest while pinning the version.
The config's shell key wins. SHELF_SHELL is only consulted when the config omits it, which is how one config can serve both shells:
# no shell keySHELF_SHELL=bash shelf source
SHELF_SHELL=zsh shelf sourceAn unsupported SHELF_SHELL value is an error rather than a silent fallback to zsh.
Use shelf self-update for a standalone install, such as the one install.sh places at ~/.local/bin/shelf. If a package manager installed shelf, the AUR, deb, rpm, or apk version, update through that instead: those packages ship a .disable-self-update marker, so self-update warns and refuses rather than replacing the packager's binary. shelf self-update downloads the release archive, verifies its sha256, and swaps the binary atomically. Development builds refuse without --force.
No. The first lock records the response's ETag, and later lock, source, and update runs send If-None-Match. A 304 Not Modified answer skips the body entirely.
shelf remove zsh-autosuggestions
shelf locklock prunes the install directory because the config no longer owns it. shelf clean does the same sweep by hand. Comments and unrelated TOML around the removed table survive.
No. build runs only for plugins active in the selected profile, so a work-profiled plugin's build commands do not execute under the default profile.
Yes. Top-level match sets the file patterns for plugins without use, top-level apply sets the templates for plugins without apply. Both fall back to the shell's own defaults. A plugin's own use or apply replaces the default, the two never merge.
Clones key off the repository URL, not the plugin name. Two plugins with the same source and different dir values read from one clone under repos/. That saves space, and installs into that directory run one at a time.
Yes. local = "~/dotfiles/plugins" and local = "$HOME/dotfiles/plugins" both expand before shelf touches the path.
proto, rev, branch, tag, dir, file, use, apply, cloneopts, depth, and build. Inline plugins have no install step and no files to select. hooks, profiles, and frozen are fine.
[env] first with names sorted, then plugins in config declaration order, shelf add appends. Inside a plugin the apply templates run in list order.
Plain shelf lock re-applies pinned revisions from the manifest, so it restores recorded pins after a manual checkout change or a pin you expected to move. Use shelf lock --update when you mean to refresh pins and plain shelf lock when you mean to restore them. The command reference covers what update does today.
The fetch ran and moved origin/*, but the working tree stayed on its current commit. This is the known bug described under update behavior today. Until it is fixed, delete the manifest and shelf lock --reinstall to pick up new commits.