OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-theming medium occasional DISPUTE

Restore bar widgets and plugins wiped by the Quattro upgrade

omarchyomarchy-4hyprlandwayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked the shipped /usr/share/omarchy/bin/omarchy-upgrade-to-quattro on this workstation (omarchy 4.0.2-1) rather than the issue text. The mechanism holds: omarchy/shell.json is in always_copy_config_files at line 1670, copy_always_config_defaults runs it at line 1918, copy_config_default backs up via backup_config_file to <file>.omarchy-upgrade-to-quattro.<timestamp>.bak, and backup_suffix=$(date +%Y%m%d%H%M%S) is at line 387. Confirmed no log, warn or echo in the script mentions a .bak. Confirmed on this machine that shell.json, not shell.toml, is the file the record is about: /usr/share/omarchy/bin/omarchy-shell-config declares itself "Shared helpers for editing ~/.config/omarchy/shell.json", while shell.toml is theme styling generated from /usr/share/omarchy/default/themed/shell.toml.tpl and read by the Quickshell QML. Neither supersedes the other, so the record points at the right file.

Three things were wrong or missing. First, the record presents this as what a Quattro upgrade does to any customized install. It cannot happen on a genuine first upgrade from Omarchy 3.x, which has no ~/.config/omarchy/shell.json and configures the bar through waybar, so the precondition is that the script runs against a file that already exists, which in practice means a re-run. Second, the record misses that the cmp -s skip in copy_config_default can never fire again after one completed upgrade: omarchy-bar defaults writes through commit, which serialises with jq -S, and I confirmed locally that jq -S . of /usr/share/omarchy/config/omarchy/shell.json is byte-different from the shipped file. Third, the record misses a second independent reset. run_as_user_omarchy omarchy-bar defaults at line 2372 runs a commit program beginning .bar = $defaults[0].bar, replacing the whole bar subtree, which means the record's restore is incomplete advice for anyone re-running the script. always_copy_config_files also covers seven hypr/ files and omarchy/extensions/omarchy-menu.jsonc, which the fix now names.

The cited source URL was wrong. https://github.com/basecamp/omarchy/issues/8357 returns 404 (the issue was created 2026-08-26, after the repo rename), while https://github.com/omacom/omarchy/issues/8357 returns 200. Read the issue in full: it is OPEN, it supports the record's mechanism, and its own collaborator comment supplies the three corrections above. Frequency is dropped from very-common to occasional because the precondition is a re-run rather than an upgrade. Severity stays medium: the data is backed up and recoverable.

Not exercised: I did not run omarchy-upgrade-to-quattro, did not run omarchy bar defaults, and did not restore any file on this machine. The line numbers, the jq -S byte difference and the migration done-marker directory were all read or computed locally. Whether the restore then breaks a specific plugin was not tested.

The cause above was rewritten on 2026-09-13 to match this note; the fix was corrected by the audit itself.
RISK

Restoring a pre-Quattro shell.json wholesale reinstates whatever that file said, and update-time migrations do not re-run to correct it. They are marked done per user under ~/.local/state/omarchy/migrations/, so a restore can permanently bring back a widget or a format a migration removed, for example 1785189600.sh (removes the tmux alert bar indicator), 1784989000.sh (moves the bar indicators left of the clock) and 1786099804.sh (renames the model usage widget to agents). Keep shell.json.quattro-default so you can fall back, and do not delete the .bak files until you have confirmed the restore works.

Symptom

After running omarchy upgrade to quattro on a machine that already had a ~/.config/omarchy/shell.json, every bar customization is gone: extra bar widgets, the enabled-plugins list, transparent: true, and custom idle timers are all back to stock defaults. The plugin directories under ~/.config/omarchy/plugins/ are all still there, untouched. Only the config was reset, and nothing on screen says a backup was written.

A genuine first upgrade from Omarchy 3.x does not hit this, because 3.x has no shell.json to lose. What hits it is a second run of the upgrade script, which its own abort banner recommends after any failure.

Cause

omarchy-upgrade-to-quattro lists omarchy/shell.json in always_copy_config_files (line 1670 of the script shipped with omarchy 4.0.2-1, line 1641 in the Omarchy 3 master tree the issue was filed against). copy_always_config_defaults (line 1918) calls copy_config_default, which installs the stock Quattro default over the existing file unless the two are byte-identical. backup_config_file() does save the old one first, to ~/.config/omarchy/shell.json.omarchy-upgrade-to-quattro.<timestamp>.bak, where the timestamp is one per run from backup_suffix=$(date +%Y%m%d%H%M%S) at line 387. Nothing in the script ever prints that a .bak was written, for any of the places it writes one.

Two things narrow and widen that. It cannot bite a genuine first upgrade from Omarchy 3.x, because 3.x has no ~/.config/omarchy/shell.json at all and configures the bar through ~/.config/waybar/config.jsonc. With the file absent, copy_config_default just installs the default and writes no backup. The machines that lose a config are ones where the script runs against a shell.json that already exists, which means a re-run, and the script's own abort banner at line 374 says "Re-running is safe and resumes the remaining steps".

A re-run also cannot be skipped by the byte-identical guard. Every upgrade run finishes with run_as_user_omarchy omarchy-bar defaults at line 2372, which writes through omarchy-shell-config's commit helper. That serialises with jq -S, so the file comes back key-sorted while the shipped /usr/share/omarchy/config/omarchy/shell.json is not (confirmed on this workstation: jq -S . of the shipped file is byte-different from the shipped file). The cmp -s guard in copy_config_default therefore never fires again on a machine that has completed the upgrade once.

omarchy-bar defaults is a second, independent reset. Its commit program starts .bar = $defaults[0].bar, replacing the whole bar subtree, so layout, position, transparent and per-widget settings go regardless of what the copy step did. It leaves plugins and idle alone, so the copy step is what accounts for those two.

The list is wider than shell.json. always_copy_config_files also carries hypr/hyprland.lua, hypr/bindings.lua, hypr/monitors.lua, hypr/input.lua, hypr/looknfeel.lua, hypr/autostart.lua, hypr/.luarc.json, omarchy/extensions/omarchy-menu.jsonc and omarchy/hooks/pre-refresh-pacman.d/add-custom-repo.sample. A re-run resets a monitor layout and a keybinding set the same way it resets a bar, and backs each one up under the same suffix.

The shell.json schema itself is unchanged across the copy (version, idle, bar, plugins, with no new required keys), so a straight restore of the .bak parses and loads.

Fix

Find the backup. There is one per upgrade run, and the same suffix is on every other file the script replaced:


ls -la ~/.config/omarchy/shell.json*
ls -la ~/.config/hypr/*.omarchy-upgrade-to-quattro.*.bak

Keep the new default aside, then restore:


cp ~/.config/omarchy/shell.json ~/.config/omarchy/shell.json.quattro-default
cp ~/.config/omarchy/shell.json.omarchy-upgrade-to-quattro.<timestamp>.bak \
   ~/.config/omarchy/shell.json
omarchy restart shell

If you would rather merge only the parts you care about onto the new default:


jq -s '.[0] * {bar: .[1].bar, plugins: .[1].plugins, idle: .[1].idle}' \
  ~/.config/omarchy/shell.json.quattro-default \
  ~/.config/omarchy/shell.json.omarchy-upgrade-to-quattro.<timestamp>.bak \
  > ~/.config/omarchy/shell.json
omarchy restart shell

Check what else the same run replaced, and restore any of those you had customized:


for f in ~/.config/hypr/hyprland.lua ~/.config/hypr/bindings.lua \
         ~/.config/hypr/monitors.lua ~/.config/hypr/input.lua \
         ~/.config/hypr/looknfeel.lua ~/.config/hypr/autostart.lua \
         ~/.config/omarchy/extensions/omarchy-menu.jsonc; do
  ls "$f".omarchy-upgrade-to-quattro.*.bak 2>/dev/null
done

Before running the upgrade in the first place, take your own copy:


cp ~/.config/omarchy/shell.json ~/shell.json.pre-quattro

The restore survives ordinary omarchy update runs. Update-time migrations edit shell.json with targeted jq changes and never replace it, so nothing puts the default back. It does not survive another run of omarchy-upgrade-to-quattro: that run replaces the file again and, at line 2372, also runs omarchy bar defaults, which resets the whole bar subtree on its own. If you re-run the script, expect to restore again, and note that restoring the .bak does not undo the omarchy bar defaults step, so do the restore after the script has finished rather than in the middle of it.

Verify

jq '.bar.layout, .plugins, .bar.transparent' ~/.config/omarchy/shell.json shows your customizations back, jq . ~/.config/omarchy/shell.json parses, and after omarchy restart shell the extra widgets are visible in the bar again.

Sources

shell-json-reset-by-quattro-upgrade