Afonso OliveiraandClaude Fable 5.1
13a4306a8e
Three review findings on the update-hook boundary: The pre-refresh-pacman hook had been moved after the refresh transaction and, during a channel switch, deferred to the very end. That defeated the hook's purpose: custom repositories and IgnorePkg entries were not in place when the downgrade-capable -Syyuu ran. Run the hook where it used to run, after the package config is re-synced and before the transaction, but cold: revoke the timestamp, run it behind the no-update wrapper with the caller's original PATH, and revoke again before continuing. Every later privileged command authenticates with --no-update, so a detached child left by the hook has no reusable timestamp to wait for. Channel switching hands the caller's PATH to the refresh the same way the updater receives it, and no longer defers or re-runs the hook. Stay Awake was released before AUR builds, hooks and mise, so the machine could sleep during the longest part of an update. Releasing the inhibitor needs no privilege because the held command already dropped to the user, so stop it after mise and before the reboot prompt, as before. A packaged channel destination cannot be inspected before its package is installed, and a transaction can replace the running tree with a release that predates the command-scoped wrapper; from then on a bare sudo would resolve to /usr/bin/sudo and publish a timestamp, and the destination's own updater authenticates the same way. The switch used to abort only after the packages had changed, with generic rerun advice. Now it checks for the wrapper after each transaction before any further privileged step, completes what it safely can, and stops cold with instructions to run that release's update from a fresh session instead of launching it. Boundary tests pin the hook between the config copies and the transaction with a cold timestamp on both sides, the older-destination stop with its guidance and no launched updater, the new inhibitor position, and the post-update hook staying unreached on failures and signals. Docs, the manual and the sample hook describe the restored timing. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
6.3 KiB
Dotfiles
Omarchy is primarily configured through the so-called dotfiles that live in ~/.config. Those are considered your files for your changes. The files that live in /usr/share/omarchy belong to Omarchy itself, and you shouldn't be messing with those. If you need to change anything in /usr/share/omarchy, you should be overwriting the value in ~/.config instead.
The key configs can be edited straight from the Omarchy menu (Super + Space), like Setup > Monitors, Setup > Keybindings, Setup > Input, and Setup > Config > [file]. When you do it this way, any process that needs restarting after config edits automatically will be after you quit the editor (Neovim by default — :wq, remember! — but you can change that via Setup > Defaults > Editor).
Here's a list of the key files in ~/.config and what they control:
| File | Purpose |
|---|---|
~/.config/hypr/hyprland.lua |
The main Hyprland config. Loads the Omarchy defaults plus your override files below. Learn more about Hyprland configs. |
~/.config/hypr/bindings.lua |
Your own keybindings and overrides of the defaults. |
~/.config/hypr/monitors.lua |
Controls your monitors, resolution, and position. |
~/.config/hypr/input.lua |
Controls your keyboard layout, mouse, and trackpad settings. |
~/.config/hypr/looknfeel.lua |
Controls gaps, borders, animations, and the rest of the look. |
~/.config/hypr/autostart.lua |
Controls extra processes started with the session. |
~/.config/omarchy/shell.json |
Controls the Omarchy shell: bar position, layout, and widgets, plus screensaver, lock, and idle timings. |
~/.config/foot/foot.ini |
Controls your terminal (foot is the default). |
~/.XCompose |
Defines your quick-access emoji and name/email autocomplete. Make sure to run omarchy-restart-xcompose after making changes. |
If you end up making a lot of changes to tweak your own setup, it's a good idea to backup all these dotfiles. Stow is a great way to do that.
Starting your own apps with the session
If you want something to run every time you log in — a sync daemon, a chat app, your own script — put it in ~/.config/hypr/autostart.lua:
o.launch_on_start("my-service")
That starts the command as part of the session, so it's properly cleaned up when you log out again.
Running scripts on system events
Omarchy fires hooks at a handful of moments, and you can hang your own scripts off them. They live in ~/.config/omarchy/hooks/<event>.d/, one directory per event, and every executable file in there runs when the event happens:
| Event | When it runs |
|---|---|
post-boot |
Right after the desktop has started |
post-update |
Near the end of omarchy update, after packages, migrations, and service restarts, before mise tools are updated |
pre-refresh-pacman |
After omarchy refresh pacman re-syncs the package config, before it updates packages; a channel switch runs it during that same refresh step |
theme-set |
After a theme change (theme name in $1) |
font-set |
After a font change (font name in $1) |
battery-low |
When the battery gets low (percentage in $1) |
The pre-refresh-pacman hook is where custom repositories or IgnorePkg lines belong, since it runs before the package transaction. Both update-related hooks run as your user after Omarchy clears its cached sudo authorization, so a hook that uses sudo needs its own authorization and may ask for your password.
Each of those directories already holds a .sample file showing the shape of a hook — drop the .sample from the name to put it to work. To install a script you've written elsewhere, use omarchy hook install post-boot ~/my-hook, which copies it in and makes it executable.
Adding your own menu entries
The Omarchy menu (Super + Space) can be extended with your own rows by editing ~/.config/omarchy/extensions/omarchy-menu.jsonc. Entries are keyed by a dotted id, and the id is what places them in the tree, so personal shows up on the root menu and personal.notes shows up inside it:
"personal": {"icon":"","label":"Personal"},
"personal.notes": {"icon":"","label":"Notes","action":"omarchy-launch-editor ~/notes"},
Reuse an existing id and you override that row instead of adding a new one. The file ships with all the available fields documented as comments.
Adding your own shell exports, functions, and aliases
Omarchy ships with a bunch of ergonomic aliases and helpful functions, but it's very common to want to add your own. You should add both aliases, functions, and exports in ~/.bashrc. This file will not be overwritten on updates. If you want to change any of the Omarchy defaults, you can also safely add them here.
Changing internal Omarchy files
Look, this is your computer. You can do whatever you want with it, but I would advise against making changes to the files in /usr/share/omarchy directly. They belong to the Omarchy pacman package, so your changes will simply be overwritten on the next update. You're better off just overwriting any default values you don't like in the ~/.config/* folder instead.
You can change just about everything that way, like the default keybindings. Just edit ~/.config/hypr/bindings.lua to, say, replace Obsidian with Joplin (install with omarchy-pkg-add joplin-bin):
o.rebind("SUPER + SHIFT + O", "Joplin", "joplin-desktop")
o.rebind removes the existing binding before adding its replacement. It takes the same arguments as o.bind, including launch helpers and binding options. Use o.bind to add a binding, or hl.unbind to remove one without replacing it.
If you insist on hacking on the internal Omarchy files, switch to the dev channel via Update > Channel > Dev. That links Omarchy to a git checkout of the source code in ~/omarchy, which you're free to change to your heart's content. Ain't nobody here to tell you what to do!
Resetting any changes
If you end up making a mess of the configurations, you can always revert them to the defaults via Update > Config in the Omarchy menu. Or by running omarchy reinstall configs to reset everything.