# How the Omarchy Refresh Pattern Copies Default Configs: A Complete Technical Guide

> Discover how the Omarchy refresh pattern safely copies default configs to your user directory. Learn about its backup and diff process to preserve customizations. Complete technical guide.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-28

---

**The Omarchy refresh pattern is a "copy-with-backup-and-diff" operation that safely copies default configuration files from `$OMARCHY_PATH/config` to the user's `~/.config` directory while preserving existing customizations as timestamped backups.**

The **refresh pattern** in basecamp/omarchy allows users to synchronize their local configurations with upstream defaults without losing personal modifications. This mechanism relies on the `omarchy-refresh-config` helper script to manage file operations atomically, ensuring that every overwrite creates a recoverable backup and displays changes for review.

## How the Refresh Pattern Works

At its core, the **refresh pattern for copying default Omarchy configs** follows a six-step safety protocol implemented in `bin/omarchy-refresh-config`. The script interprets command arguments as paths relative to the user's `.config` directory, locating source files within the system's default configuration repository while protecting existing user data.

### Locating Source and Target Paths

When you invoke the refresh command, the script constructs two critical file paths. The target is interpreted as a relative path within `~/.config`, while the source resolves against the `$OMARCHY_PATH` environment variable injected by the runtime environment:

```bash
default_config_file="$OMARCHY_PATH/config/$config_file"

```

This design allows users to reference configurations naturally—such as [`hypr/hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hypr/hyprland.lua)—while the system maintains strict separation between shipped defaults in `default/config/` and active user configurations.

### Safety Checks and Directory Preparation

Before any copy operation, the script validates that the source file exists within Omarchy's shipped defaults. If the requested file is missing, the operation aborts immediately with the error message **"Not a shipped user config"**.

Once validated, the script ensures the destination directory hierarchy exists using standard POSIX utilities:

```bash
mkdir -p "$(dirname "$user_config_file")"

```

This prevents errors when refreshing configurations for applications where the user has not yet created the necessary subdirectory structure under `~/.config`.

### Backup and Diff Strategy

The refresh pattern implements a sophisticated mechanism to protect user customizations through three distinct phases:

1. **Timestamped Backup Creation** – If a user configuration exists, the script copies it to a backup file suffixed with the current Unix timestamp: `$user_config_file.bak.$(date +%s)`.
2. **Atomic Replacement** – The default file overwrites the user configuration immediately after the backup completes successfully.
3. **Change Visualization** – Using `cmp`, the script compares the new file against the backup. If identical, it removes the redundant backup; otherwise, it executes `diff` to display exactly what changed between versions.

For first-time installations where no user file exists, the script bypasses backup creation and copies the default directly.

## Using the omarchy-refresh-config Command

The `omarchy-refresh-config` utility provides a POSIX-compliant interface for updating configurations across any shell environment. Because it relies only on standard Unix utilities—`cp`, `cmp`, `diff`, and `mkdir`—it operates reliably across diverse Linux distributions without external dependencies.

### Refreshing an Existing Configuration

To update a Hyprland configuration while preserving your current settings as a recoverable backup:

```bash
$ omarchy-refresh-config hypr/hyprland.lua

```

If `~/.config/hypr/hyprland.lua` exists, this command creates a backup such as `~/.config/hypr/hyprland.lua.bak.1730845602`, installs the fresh default from `$OMARCHY_PATH/config/hypr/hyprland.lua`, and displays a diff highlighting the differences between your version and the upstream default.

### Handling Missing Default Files

Attempting to refresh a configuration not included in the shipped defaults triggers an immediate validation error:

```bash
$ omarchy-refresh-config unknown/file.toml
Not a shipped user config: unknown/file.toml

```

This safety check prevents users from accidentally triggering file operations for non-existent templates.

### First-Time Configuration Installation

When the target configuration does not exist, the refresh pattern performs a simple copy without backup overhead:

```bash
$ omarchy-refresh-config hypr/bindings.lua

```

The script detects the absence of `~/.config/hypr/bindings.lua` and copies the default directly from the Omarchy repository without creating unnecessary backup files.

## Implementation Details in bin/omarchy-refresh-config

According to the basecamp/omarchy source code, the core logic resides in `bin/omarchy-refresh-config`, which orchestrates file operations through shell commands rather than complex library dependencies. The script receives the `$OMARCHY_PATH` variable from the runtime environment (as documented in the project's Runtime Environment section), ensuring consistent path resolution across different installation methods.

The implementation emphasizes **atomicity** and **reversibility**: every overwrite operation is preceded by a complete file copy to a backup location, ensuring that even catastrophic failures during the refresh process leave the previous configuration intact on disk. The use of timestamped backups rather than simple `.bak` extensions allows users to maintain multiple historical versions of their configurations.

## Testing the Refresh Pattern

The [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh) file contains automated verification of the refresh behavior, validating backup handling, diff output formatting, and error conditions for missing files. These tests ensure that the **refresh pattern** remains consistent across releases, particularly regarding the timestamp generation logic and the `cmp` comparison that determines whether to preserve or discard backup files.

## Summary

- The **Omarchy refresh pattern** copies default configs from `$OMARCHY_PATH/config` to `~/.config` using a backup-and-diff strategy that preserves user customizations.
- The `bin/omarchy-refresh-config` script interprets paths relative to the user's `.config` directory and validates them against shipped defaults before performing any file operations.
- Existing configurations are backed up with Unix timestamps (`.bak.$(date +%s)`) before being overwritten, with automatic cleanup if the new file is identical to the previous version.
- The pattern uses only POSIX utilities (`cp`, `cmp`, `diff`, `mkdir`), ensuring compatibility across different shell environments and Linux distributions.
- Automated tests in [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh) verify backup creation, diff output, and error handling for files not present in the default configuration set.

## Frequently Asked Questions

### What happens to my existing config when I run omarchy-refresh-config?

If a configuration file already exists at the target location, the script creates a timestamped backup using `date +%s` (e.g., `config.lua.bak.1730845602`) before overwriting it with the default version. After copying, it compares the new file against the backup using `cmp`; if they differ, it displays a `diff` showing the changes, otherwise it removes the redundant backup file to conserve space.

### How does Omarchy handle missing default config files?

The refresh script validates that the requested file exists within `$OMARCHY_PATH/config` before performing any operations. If the specified file is not part of the shipped defaults, the script aborts immediately with the error message "Not a shipped user config", preventing accidental file creation or corruption of user data.

### Where are the default configuration files stored in Omarchy?

Default configurations are stored in the `default/config/` directory within the Omarchy repository, referenced at runtime through the `$OMARCHY_PATH/config` environment variable. This path contains the upstream templates for all supported applications, organized in subdirectories matching standard XDG configuration paths like `hypr/` and `waybar/`.

### Is the refresh pattern safe to use with custom modifications?

Yes, the **copy-with-backup-and-diff** pattern is specifically designed to protect customizations. By creating timestamped backups before any overwrite and displaying differences afterward, users can always revert to their previous configuration by restoring the `.bak.*` file if the new defaults introduce unwanted changes or break existing functionality.