# How Omarchy Handles Configuration Updates for Existing Users

> Omarchy automatically refreshes user configurations safely. Learn how omarchy-refresh-config preserves your customizations with automatic backups.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Omarchy uses a built-in `omarchy-refresh-config` workflow that safely updates configuration files while preserving existing user customizations through automatic backups.**

The [omacom/omarchy](https://github.com/omacom/omarchy) repository implements a safe configuration update system designed specifically for users who have already customized their Linux environment. Rather than blindly overwriting files, the refresh workflow ensures no data loss through timestamped backups and idempotent operations.

## The `omarchy-refresh-config` Refresh Workflow

The core mechanism for handling configuration updates is the `omarchy-refresh-config` helper script located at `bin/omarchy-refresh-config`. This utility manages the entire lifecycle of updating default configurations while respecting user modifications.

### How the Refresh Process Works

When executed, the script follows a strict five-step safety protocol:

1. **Identifies the source file** — Locates the default configuration in the repository under `config/…` (e.g., `config/hypr/hyprland.jl`)
2. **Computes the target path** — Resolves the user's local config directory (`~/.config/hypr/hyprland.jl`)
3. **Checks for existing files** — Verifies whether the user has an existing customized version
4. **Creates a backup** — Preserves the existing file with a timestamp or `.bak` suffix before any modification
5. **Copies the new default** — Writes the updated configuration only if the target path is writable

This sequence guarantees that **no user customization is ever lost** without explicit recovery steps.

### Key Safety Guarantees

The `omarchy-refresh-config` implementation provides three critical protections for existing users:

- **Data preservation** — Previous versions are always retained as timestamped backups
- **Idempotent execution** — Repeated runs will not create duplicate backups or corrupt configurations
- **Customization integrity** — Users can manually merge changes from new defaults into their backed-up versions

## How to Refresh Configuration Files

### Refresh a Single Configuration File

Update one specific configuration file while preserving your existing version:

```bash
omarchy-refresh-config hypr/hyprland.jl

```

### Refresh Multiple Files with Wildcard Patterns

Apply updates to entire configuration directories in one operation:

```bash
omarchy-refresh-config "waybar/*.jsonc"

```

### Inspect and Recover from Backups

After a refresh, verify your backup files and restore if needed:

```bash
ls -l ~/.config/hypr/hyprland.jl.bak*

```

## Where Configuration Updates Originate

### Repository Default Configurations

Default configurations reside in the `config/` directory tree, as documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md). These paths map directly to user directories under `$HOME/.config/`.

| Repository Path | User Target Path |
|-----------------|------------------|
| `config/hypr/hyprland.jl` | `~/.config/hypr/hyprland.jl` |
| `config/waybar/config.jsonc` | `~/.config/waybar/config.jsonc` |

### Documentation and Testing Coverage

The update workflow is comprehensively documented and tested:

- **[`docs/update-process.md`](https://github.com/omacom/omarchy/blob/main/docs/update-process.md)** — Explains the refresh workflow and backup strategy in detail
- **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)** — Maps repository config locations to user directory structures
- **[`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh)** — Automated tests verifying safe updates and backup creation

## When to Run Configuration Updates

### After Repository Pulls

Execute `omarchy-refresh-config` after updating your local Omarchy installation to receive the latest default configurations.

### Before Major Customization Sessions

Run the refresh proactively to ensure your base configuration is current before making extensive personal modifications—this minimizes divergence from upstream defaults.

### During Troubleshooting

Refresh specific files to reset configurations to known-good states while retaining your original files for reference:

```bash

# Reset Hyprland configuration to defaults

omarchy-refresh-config hypr/hyprland.jl

# Compare with your backup to identify problematic changes

diff ~/.config/hypr/hyprland.jl.bak* ~/.config/hypr/hyprland.jl

```

## Summary

- **Configuration updates in Omarchy** are handled by the `omarchy-refresh-config` helper script at `bin/omarchy-refresh-config`
- **Automatic backups** preserve existing user customizations with timestamped or `.bak` suffixed files
- **Idempotent operations** ensure repeated refreshes never corrupt configurations or create backup clutter
- **Wildcard support** enables batch updates of related configuration files
- **Comprehensive testing** in [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh) validates the safety guarantees

## Frequently Asked Questions

### What happens if I run `omarchy-refresh-config` multiple times?

The refresh operation is **idempotent**. Running it repeatedly will not create duplicate backups or corrupt your configuration. If the target file already matches the source, no action is taken. If you've modified the file since the last refresh, a new backup is created with a fresh timestamp, preserving each prior state.

### Can I restore my previous configuration after a refresh?

Yes. The refresh process automatically generates timestamped backup files with `.bak*` suffixes. Locate your backup using `ls ~/.config/[app]/*.bak*` and restore by copying or moving the backup file over the refreshed configuration. No special restore command is required—standard shell operations suffice.

### Does Omarchy merge my customizations with new defaults automatically?

No. Omarchy deliberately **does not perform automatic merging** to prevent silent configuration conflicts. New defaults replace old defaults, with your previous version preserved as a backup. You must manually merge desired changes using standard diff and editing tools. This design prioritizes **predictability over convenience**.

### Which configuration files support the refresh workflow?

Any file under the `config/` directory tree supports refresh operations. Common examples include `hypr/hyprland.jl`, `waybar/config.jsonc`, [`foot/foot.ini`](https://github.com/omacom/omarchy/blob/main/foot/foot.ini), and `fish/config.fish`. Use wildcard patterns like `"hypr/*.conf"` to refresh entire configuration suites at once.