Omarchy Refresh Pattern: How to Safely Restore Default Configuration Files

Omarchy's refresh pattern backs up your existing config, copies the default in place, and shows a diff of changes—keeping your customizations safe while letting you restore shipped defaults.

The Omarchy desktop environment uses a refresh pattern for restoring default configuration files without destroying user customizations. This pattern, implemented in the omarchy-refresh-config helper script, ensures you can always revert to upstream defaults while retaining a complete backup of your previous settings.

How the Omarchy Refresh Pattern Works

The refresh pattern follows a strict six-step process defined in bin/omarchy-refresh-config. When you run the command with a relative config path, the script:

1. Locates both files — the default at $OMARCHY_PATH/config/<path> and your current file at ~/.config/<path>
2. Validates the default exists — aborts with an error if the source file is missing
3. Ensures the target directory exists — creates parent directories with mkdir -p "$(dirname "$user_config_file")"
4. Backs up your existing config — saves to a timestamped copy at $user_config_file.bak.<epoch>
5. Copies the default over your file — replaces your current config with the shipped default
6. Compares and reports changes — removes the backup if identical, or displays a diff when files differ

This process is documented in AGENTS.md under the Refresh Pattern section and fully implemented in the bin/omarchy-refresh-config source file.

Running the Refresh Pattern

Use omarchy-refresh-config with any config file path relative to the config root:

# Restore the default Hyprland configuration

omarchy-refresh-config hypr/hyprland.lua

The script resolves two locations:

• Source: $OMARCHY_PATH/config/hypr/hyprland.lua (the shipped default)
• Target: ~/.config/hypr/hyprland.lua (your current configuration)

What Happens During Execution

# Example output when changes are detected

Replaced /home/user/.config/hypr/hyprland.lua with new Omarchy default.
Saved backup as /home/user/.config/hypr/hyprland.lua.bak.1724529801.

Changes:
--- /home/user/.config/hypr/hyprland.lua.bak.1724529801
+++ /home/user/.config/hypr/hyprland.lua
@@ -1,5 +1,5 @@
-# old setting

+# new default setting

The diff output lets you immediately see exactly what Omarchy changed, making it easy to re-apply any lost customizations.

Backup Behavior in the Refresh Pattern

The Omarchy refresh pattern uses intelligent backup handling based on file comparison results:

Scenario	Result
Default equals backup	Backup file is automatically deleted (no clutter)
Default differs from backup	Backup preserved with timestamp, diff displayed

This prevents accumulation of unnecessary backup files when you refresh a config you never modified, while ensuring you never lose work when defaults have evolved.

Refresh Pattern Test Coverage

The Omarchy repository includes comprehensive test coverage in test/shell.d/refresh-config-test.sh. This automated test suite validates:

• Correct path resolution for source and target files
• Proper backup creation with valid timestamps
• Correct backup removal when files are identical
• Accurate diff generation when files differ
• Proper error handling when default files are missing

Key Files for the Omarchy Refresh Pattern

• bin/omarchy-refresh-config — Core implementation of the refresh helper
• AGENTS.md — Official documentation of the refresh pattern behavior
• test/shell.d/refresh-config-test.sh — Automated regression tests

Summary

• The Omarchy refresh pattern restores default configs via omarchy-refresh-config <relative-path>
• Every refresh creates a timestamped backup at ~/.config/<path>.bak.<epoch>
• Identical files trigger automatic backup cleanup; differing files preserve backups with diff output
• The pattern is fully tested and documented in the Omarchy source tree

Frequently Asked Questions

What happens if I run omarchy-refresh-config on a file I never modified?

If your current config matches the default exactly, the script copies the default (which is identical), compares the files, finds no differences, and removes the backup file automatically. You get a clean restore with no leftover backups.

Can I restore my custom configuration after refreshing to defaults?

Yes. The timestamped backup file remains in your ~/.config directory after any refresh that detected changes. Simply copy or move the .bak.<timestamp> file back to the original filename to restore your previous settings.

Does omarchy-refresh-config work with nested configuration directories?

Yes. The script uses mkdir -p to create any necessary parent directories in ~/.config. You can refresh configs at any depth, such as hypr/monitors/work.lua, and the path structure is preserved and created as needed.

What error handling does the refresh pattern include?

The script validates that the default source file exists before making any changes. If $OMARCHY_PATH/config/<path> is missing, the script aborts immediately with an error message, protecting your existing configuration from partial or failed operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}