dots/HYDE-UPDATE.md

Updating HyDE on a host

Operational runbook for the framework these dots sit on top of. Carried over from dots-wm's HYDE-UPDATE.md before that repo was abandoned (2026-08-08); trimmed to the update itself, since the migration it was written for is done.

What HyDE is to this repo

GUI hosts hard-depend on it: hypr/hyprland.conf sources ~/.local/share/hyde/hyprland.conf, which defines $mainMod and the framework vars. Without it a GUI host dies with source globbing error + invalid mod $mainMod. That file is generated, not tracked here — see README's "HyDE dependency".

Should an old HyDE be updated?

Yes, once the host's dots are settled — an old HyDE paired with a current Arch Hyprland is a known-bad mix, and it fails silently. Symptoms actually observed on wm (HyDE from April 2025):

• ships the pre-0.45 layerrule = blur,waybar form, which current Hyprland rejects — HyDE wraps the source in hyprlang noerror true, so nothing is printed;
• hard-sources hypr/themes/{theme,colors,wallbash}.conf, which newer HyDE generates itself — missing them, Hyprland falls back to compositor defaults (border 1, rounding 0, gaps_out 20, no blur);
• animations/theme.conf is a source = ./HyDE.conf stub where HyDE.conf is a newer-HyDE artifact that does not exist there.

Upstream has since shipped config fixes for Hyprland 0.53 (windowrule overhaul), 0.54 (togglesplit binds) and 0.55 (config breaking changes). A 2025 HyDE predates all three.

Because of that old-HyDE behaviour, the wm overlay tracks wm/.config/hypr/themes/{colors,theme,wallbash}.conf and wm/.config/hypr/animations/theme.conf (force-added past the **/hypr/themes/ gitignore) — wm's HyDE hard-sources the former and never generates the HyDE.conf the gui animations stub points at. Theme switches on wm write through those symlinks and dirty the repo — expected; fl works the same way. When wm's HyDE is finally updated, delete all four from the overlay (newer HyDE generates its own) and let reconcile-hyde.sh sort out the rest.

Do it as its own change — never in the same sitting as a dots migration, or a single symptom is unattributable.

Can it be reverted? Only partially

~/HyDE/Scripts/install.sh overwrites ~/.config/hypr/*, replaces stow symlinks with real files, backs the old configs up to ~/.config/cfg_backups, and installs/upgrades packages.

• Recoverable: the config layer — dots are git-tracked, and ./bin/reconcile-hyde.sh --relink <host> re-stows the repo versions (backing severed files up to a timestamped dir).
• Not recoverable: packages it upgraded, and HyDE's generated state (~/.local/share/hyde/*, hyde/themes/, wallpapers) — overwritten in place.
• There are no system snapshots on these machines (no timeshift, no btrfs /.snapshots), so there is no whole-system rollback.

A real undo therefore requires the backup in step 1. It is not optional.

Procedure

1. Back up — this is the only revert path.

   tar czf ~/hyde-pre-update-(date +%F).tgz -C ~ .local/share/hyde .config/hypr .config/waybar
   pacman -Qe > ~/pkgs-pre-update.txt
   

2. Update (clone HyDE first if ~/HyDE is absent):

   ~/HyDE/Scripts/install.sh     # -r restore mode overwrites ~/.config/hypr/*
   

3. Reconcile the dots — HyDE has just severed the stow symlinks:

   cd ~/.dots
   git commit -am wip                    # so reconcile choices stay reviewable
   ./bin/reconcile-hyde.sh <host>        # report only, safe
   ./bin/reconcile-hyde.sh -i <host>     # interactive: keep/take/merge per file
   #   or: ./bin/reconcile-hyde.sh --relink <host>   # repo versions win, re-stow
   

   Note SUBTREES in that script covers .config/hypr and .config/waybar only.

4. Disable HyDE's own bar (one-time; gui's exec-once launches the custom cava rig):

   systemctl --user stop hyde-(echo $XDG_SESSION_DESKTOP)-bar.service
   systemctl --user mask hyde-(echo $XDG_SESSION_DESKTOP)-bar.service
   

5. Verify — hyprctl configerrors is not enough. It returns empty even for a missing source =, which is what hid every bug above. Check the log and the set: flag:

   grep -cE 'globbing error|Error parsing gradient' /run/user/1000/hypr/*/hyprland.log
   hyprctl getoption decoration:rounding   # set: false = nothing ever assigned it
   

   Then review git -C ~/.dots status after the reconcile.

6. Check the keybind scripts still exist — this is the one that bites. 24 binds in hypr/keybindings.conf exec scripts out of HyDE's $scrPath, which the repo does not define or ship. When HyDE renames or drops one, the bind stays valid, Hyprland logs nothing, and the key simply stops doing anything. (This is how the 2026-07-20 lw clash presented: "no keybinds, no errors".) dontkillsteam.sh is a known upstream deprecation, and it is bound to Super+Q and Alt+F4 — i.e. closing windows.

   set scr (grep -oP '(?<=\$scrPath\s?=\s?).*' ~/.local/share/hyde/hyprland.conf \
            | head -1 | string trim | string replace '$HOME' $HOME)
   echo "scrPath = $scr"
   for s in (grep -hoE '\$scrPath/[A-Za-z0-9._-]+' ~/.config/hypr/*.conf \
             | string replace '$scrPath/' '' | sort -u)
       test -e "$scr/$s"; or echo "MISSING: $s"
   end
   

   Anything listed MISSING needs its bind repointed at the current script name in gui/.config/hypr/keybindings.conf — that is a dots fix, not a HyDE one.

Reverting

Partial only: ./bin/reconcile-hyde.sh --relink <host> plus git restore bring back the config layer, and ~/.config/cfg_backups holds HyDE's own pre-update copies. Packages and ~/.local/share/hyde/* come back only from the step-1 tarball.