# Omarchy Refresh Pattern: How to Safely Restore Default Configuration Files

> Safely restore default config files with Omarchy's refresh pattern. It backs up your current settings, applies defaults, and shows changes, protecting your customizations.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** — Official documentation of the refresh pattern behavior
- **[`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.