Troubleshooting

Start here:

dotfix doctor

Most of what goes wrong is one of the things it checks.

The status line never appears

The hourly agent runs with a minimal environment and does not inherit your interactive PATH. If dotfix moved — a reinstall to a different location, a cargo clean — the agent can no longer find it.

dotfix doctor --install-agent

This rewrites the plist with the current location.

The background check cannot reach the repository

An agent has no terminal, so it cannot unlock a passphrase-protected SSH key. Either let macOS hold the key:

Host *
  AddKeysToAgent yes
  UseKeychain yes

…or set the machine up with a deploy key, which dotfix generates without a passphrase and scopes to the one repository.

Setup was interrupted and will not start again

Run it again. dotfix reuses a repository already at ~/dotfiles rather than refusing. On the clone path it first confirms the remote is the repository you asked for; if something else is there, it names what it found and stops. Move that directory aside to continue.

A secret cannot be resolved

dotfix doctor reports the tooling for the provider this machine uses — op for 1Password, age and ~/.config/dotfix/age.key for age. A provider recorded in machines/<name>.toml whose tool is not installed is the usual cause.

My .zshrc is listed as edited and never changes

That is intended. dotfix did not write that file, so it will not overwrite it. The assembled .zshrc cannot be written back to either, because it is the concatenation of every active set’s shell/*.zsh fragments — there is no single file behind it. Move your configuration into fragments; see Files and shell configuration.

A package keeps reappearing as unmanaged

Adopt it into a set, or ignore it on this machine:

dotfix adopt

Ignoring is recorded per machine, so the package stays visible on your other Macs.

Two menubar icons

Older builds could start twice. Quit both and launch the copy in /Applications; a second launch now brings the running window forward instead.