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):
- Fetch
origin/mainat 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. - If
dotsitself changed during the fetch, the script re-executes with the new version before touching any payload. - 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:
- The pre-equisdots
dockobject is migrated to the canonicalbarkey. - Legacy keys nothing reads anymore are dropped.
- Shipped defaults are applied as the base; your values win, and user arrays
such as
bar.zonesare 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
xwwwversion against the pinned release. - Repository clones and dirty clones.
- Installed payload paths (palettes,
hyprland.lua,Shell.qml, wrappers,settings.jsonand more). - The plugin registry: duplicate ids, folder/manifest mismatches and runtime collisions.
- Hyprland version (0.55+ required for Lua) and
~/.local/bininPATH. - 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 rundots updateagain. - 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 thatjqis installed.hyprland < 0.55: update the compositor package; the Lua config needs Lua support.- xwww mismatch:
dots update(orscripts/install-xwww.sh) reinstalls the pinned release. - A plugin is listed but not mounted: check
dots doctorfor acompatviolation or an id collision, thendots plugins add <id> --forceonly if the mismatch is intentional. - Active display manager is not SDDM: the static login theme will not show;
dots systemswitches the display-manager link. - System phase failure: inspect the newest log with
ls -t /tmp/hyprland-install-*.log | head -1.
Related pages
- Installation for the first setup.
- Architecture and repositories for the install layout and contracts.
- Contributing and security for reporting problems.