equisdots
Menu

Updating and diagnosing

How dots update, list, doctor and uninstall keep the stack in sync and how to fix common failures.

dots manages the whole stack from a single command. Updating pulls every repository, redeploys the payload and keeps the wallpaper daemon aligned with the pinned release. Diagnosing is a separate read-only pass that tells you what is missing or out of sync.

Command reference

Command Action
dots install Clone or update every repo and place its payload.
dots update dots install plus the xwww release check.
dots system Run the hyprland installer (packages, fonts, login, PAM, sudo required).
dots doctor Check binaries, clones and installed paths. Exits non-zero on failure.
dots list Repository status: clean, dirty or missing.
dots plugins Installed plugins; available, add, remove, enable, disable subcommands.
dots reset Forced clean reinstall of the payload (user data kept).
dots uninstall Remove wrappers and the updater timer; configs and clones stay.
dots update
dots doctor
dots list

The niri stack (dotsniri)

The niri session has its own meta installer, dotsniri, parallel to dots. It uses a separate clone root (~/.local/share/equisdots-niri) and never touches a parallel dots install, so the two stacks coexist on one machine.

Command Action
dotsniri install Clone/update and deploy the niri stack (own repos + shared shell/nyx).
dotsniri update Pull the own repos plus the shared shell/nyx bases, then re-deploy.
dotsniri deploy Re-deploy from the existing clones (re-applies the overlays after a dots update).
dotsniri desktop <niri|hyprland|both> Set the default session and apply or remove the shell overlays.
dotsniri login <install|remove|status> Manage the display-manager session entry (via niri-login, sudo).
dotsniri system [--apply] Install distro packages (niri, portals, ...).
dotsniri doctor Check binaries, clones, deploy, the shell backend and niri validate.
dotsniri doctor --self-test Syntax-check the toolkit; works without niri.
dotsniri plugins [list|available|add|remove|enable|disable] Manage the plugin set with parity to dots plugins.
dotsniri reset Forced clean reinstall of the niri deploy (drops the own clones).
bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/niri-meta/main/bin/dotsniri) install
dotsniri doctor
dotsniri desktop niri

The shell overlays are conditional and reversible: a shared file is only replaced by its niri variant while the niri session is selected, and dotsniri deploy re-applies them whenever dots update rewrites the shell. See niri compositor.

What dots update does

For every repository in the org (dots, palettes, theme-sync, davinci, shell, nyx, hyprland, timex, xturing, login, plus the plugin standard and the default plugin sources):

  1. Fetch origin/main at depth 1 and hard-reset the managed clone to it. The hard reset also recovers from upstream force-pushes, where a fast-forward pull would fail forever.
  2. If dots itself changed during the fetch, the script re-executes with the new version before touching any payload.
  3. Deploy the payload for that repository, skipping clones with local changes.

After the payload phase, dots update checks the running xwww binary against the version pinned in scripts/install-xwww.sh and reinstalls when they differ (XWWW_VERSION overrides the pin). It also writes the version state used by the About page and the updater popup.

The default plugins are redeployed through the registry convention without writing their toggles, so existing users keep the features. User plugins in ~/.config/hypr/plugins-user/ are never touched, and a plugin with a violated compat is not mounted. Update or add an individual plugin with dots plugins add <id> (or the Plugins panel); see Plugins and extensions.

Local changes in managed clones

Managed clones are read-only from dots's point of view. A clone with uncommitted changes is kept exactly as it is and its payload is not deployed, so a stale checkout can never downgrade or delete live files.

dots list                                  # shows dirty clones
git -C ~/.local/share/equisdots/shell status

Reconcile by committing or stashing the changes, or by parking the clone:

mv ~/.local/share/equisdots/shell{,.local}
dots install

dots doctor flags every dirty clone so updates do not silently stall.

Forced reinstall with dots reset

dots reset is the escape hatch for a bad install: it deletes the managed files (Hyprland config/scripts, shell, app configs) and the managed clones, reinstalls everything from the latest origin/main and re-applies the active palette. It never touches your data: settings.json, config/ overrides, wallpapers/, the palette store (dock/palettes, including community and editor edits), display-config, idle-settings.json and the hyprland-backup-* snapshots survive. It is also the way to recover dirty managed clones that block their payload during update/install. The system stack (sudo) is out of scope: run dots system for packages, fonts, the login theme and PAM.

dots install, dots update and dots reset normalize a leading ~ in settings.json's wallpaperDir to an absolute path, so the wallpaper picker always finds the collection (a literal ~ left the grid empty and failed every apply with File not found).

settings.json merge rules

dots install never overwrites your settings. The file is seeded from default_settings.json only when missing, and on every update it is rewritten as shipped defaults plus your values with jq:

  1. The pre-equisdots dock object is migrated to the canonical bar key.
  2. Legacy keys nothing reads anymore are dropped.
  3. Shipped defaults are applied as the base; your values win, and user arrays such as bar.zones are kept as-is.

If the merge fails, the file is left untouched and dots prints a warning.

The monthly updater timer

dots install registers a systemd user timer that runs the dotfiles update monthly:

systemctl --user status dotfiles-update.timer
systemctl --user list-timers dotfiles-update.timer

dots uninstall removes the timer and the wrappers. The service points at ~/.config/hypr/scripts/dotfiles-update.sh; dots doctor warns when the unit points somewhere else.

dots doctor checks

The doctor is the first diagnostic to run. It reports, in order:

  • Required binaries: git, rsync, hyprland, qs, jq, curl, python3, cava, playerctl, wl-paste, cliphist, brightnessctl, pamixer, kitty, rofi, xwww-daemon, mpvpaper.
  • Optional binaries: grim, slurp, satty, hyprpicker, blueman-applet, nm-applet, gsettings, cargo.
  • Font check via fc-match "Hack Nerd Font".
  • The running xwww version against the pinned release.
  • Repository clones and dirty clones.
  • Installed payload paths (palettes, hyprland.lua, Shell.qml, wrappers, settings.json and more).
  • The plugin registry: duplicate ids, folder/manifest mismatches and runtime collisions.
  • Hyprland version (0.55+ required for Lua) and ~/.local/bin in PATH.
  • System pieces: /etc/pam.d/quickshell, the SDDM theme config, the static theme and the active display manager.
  • The monthly updater timer.
dots doctor; echo "exit: $?"

The command exits 1 when at least one item failed, which makes it usable in scripts.

Troubleshooting

  • Update reports local changes; skipping its payload: reconcile the clone as shown above, then run dots update again.
  • Fetch failed (network): the existing checkout is kept and the rest of the update continues; retry later.
  • settings.json could not be migrated: see the warning output; the file is intact. Check that jq is installed.
  • hyprland < 0.55: update the compositor package; the Lua config needs Lua support.
  • xwww mismatch: dots update (or scripts/install-xwww.sh) reinstalls the pinned release.
  • A plugin is listed but not mounted: check dots doctor for a compat violation or an id collision, then dots plugins add <id> --force only if the mismatch is intentional.
  • Active display manager is not SDDM: the static login theme will not show; dots system switches the display-manager link.
  • System phase failure: inspect the newest log with ls -t /tmp/hyprland-install-*.log | head -1.

Edit this page on GitHub