# How omarchy‑refresh‑config Copies Defaults with Backup in Omarchy

> Discover how omarchy-refresh-config safely synchronizes user configs with defaults. It preserves customizations by creating timestamped backups, ensuring your settings are never lost.

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

---

**`omarchy-refresh-config`** is a Bash utility that synchronizes a user's configuration file with the shipped default while preserving any existing customizations through timestamped backups.

In the Omarchy Linux distribution (source: `omacom/omarchy`), configuration files live in two locations: user customizations in `~/.config/` and pristine defaults under `$OMARCHY_PATH/config/`. The `omarchy-refresh-config` script bridges these worlds safely, ensuring users never lose their tweaks when updating to newer defaults. This guide explains exactly how this backup-and-restore mechanism works under the hood.

---

## Core Workflow of omarchy-refresh-config

The `bin/omarchy-refresh-config` script follows a six-step pipeline that prioritizes data safety.

### Step 1: Argument Validation

The script requires a single relative path argument pointing to a config file within the standard structure.

```bash

# Valid: relative path to a config file

omarchy-refresh-config hypr/hyprland.conf

# Invalid: no argument triggers usage message

```

If no argument is provided, the script prints usage information and exits [L8-L16].

### Step 2: Path Resolution

The script constructs three absolute paths from the input:

| Variable | Construction | Purpose |
|----------|-----------|---------|
| `user_config_file` | `~/.config/<provided-path>` | Where user customizations live |
| `default_config_file` | `$OMARCHY_PATH/config/<provided-path>` | Pristine upstream default |
| `backup_config_file` | `<user_config_file>.bak.<timestamp>` | Timestamped safety copy |

The timestamp uses `$(date +%s)` for epoch-based uniqueness [L20-L22].

### Step 3: Default Existence Check

Before any filesystem operations, the script verifies the default file actually exists at `$OMARCHY_PATH/config/<path>`. If missing, it aborts with an error message [L24-L27].

### Step 4: Target Directory Creation

The script ensures the parent directory structure exists using `mkdir -p` before attempting any file operations [L29].

---

## The Backup and Copy Logic

The heart of `omarchy-refresh-config` lives in its conditional file handling. The behavior branches based on whether the user already has a configuration file.

### When a User Config Exists

If `-f "$user_config_file"` evaluates true, the script executes a careful three-phase replacement:

1. **Backup creation** — Copy existing file to timestamped backup location [L31-L33]
2. **Default installation** — Copy default file to user location (overwriting)
3. **Change detection** — Compare backup against new file using `cmp`

```bash

# The actual logic from bin/omarchy-refresh-config

if [ -f "$user_config_file" ]; then
    cp "$user_config_file" "$backup_config_file"
fi

```

The `cmp` comparison drives user-facing output:

- **Identical files**: Backup is automatically removed to reduce clutter [L35-L40]
- **Different files**: A colored notice prints and `diff` output displays exactly what changed

### When No User Config Exists

For first-time setups, the script skips backup creation entirely and simply copies the default to the user location [L41-L43].

```bash

# First-time installation path

cp "$default_config_file" "$user_config_file"

```

---

## Practical Usage Examples

### Refreshing a Window Manager Configuration

```bash

# Update Hyprland config while preserving custom keybindings

omarchy-refresh-config hypr/hyprland.conf

```

### Refreshing Theme Configuration

```bash

# Sync GTK theme defaults

omarchy-refresh-config gtk/gtk.css

```

### Observing What Would Change

```bash

# Run on a modified file to see the diff output

omarchy-refresh-config waybar/config.jsonc

```

The script will display colored output showing additions and removals compared to your backed-up version.

---

## Why This Backup Strategy Matters

The Omarchy project implements several protective design decisions in this script:

- **Timestamped naming** (`.bak.1672531200`) prevents backup collisions during rapid successive runs
- **Conditional cleanup** removes unnecessary backups when defaults match user files exactly
- **Diff transparency** shows users precisely what they're gaining or losing in each refresh
- **Directory autocreation** eliminates "parent directory missing" failures

According to the repository's [`plans/dots.md`](https://github.com/omacom/omarchy/blob/main/plans/dots.md), this backup naming convention and testing strategy was intentionally designed for a system where configurations evolve frequently and user modifications must survive updates.

---

## Summary

- **`omarchy-refresh-config`** safely updates user configs from Omarchy defaults using timestamped backups
- **Three paths constructed**: user location, default location, and `.bak.<timestamp>` backup
- **Conditional behavior**: creates backup only when user file exists; skips for first-time installs
- **Change detection via `cmp`**: identical files trigger backup cleanup; differences trigger colored notice and `diff` output
- **Source location**: `bin/omarchy-refresh-config` [L8-L43]

---

## Frequently Asked Questions

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

Each execution generates a new timestamped backup (`.bak.$(date +%s)`), so you retain multiple recovery points rather than overwriting a single backup. If the latest default matches your backed-up version exactly, the script automatically removes the redundant backup to prevent clutter.

### Can I recover my original configuration after refreshing?

Yes. The timestamped backup persists at `~/.config/<path>.bak.<timestamp>` unless the files were identical. Simply `mv` the backup over your current file to restore, or reference the backup path shown in the script's output.

### What if the default configuration file doesn't exist?

The script validates `$OMARCHY_PATH/config/<provided-path>` before any operations and exits with an error message if the default is missing [L24-L27]. This prevents creating broken symlinks or empty files.

### Does omarchy-refresh-config work with directories or only files?

The script operates on individual files specified by relative path. For directory-level synchronization, Omarchy uses separate utilities; consult [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) for the complete configuration structure and intended usage patterns.