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

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.

# 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

# 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].

# First-time installation path

cp "$default_config_file" "$user_config_file"

---

Practical Usage Examples

Refreshing a Window Manager Configuration

# Update Hyprland config while preserving custom keybindings

omarchy-refresh-config hypr/hyprland.conf

Refreshing Theme Configuration

# Sync GTK theme defaults

omarchy-refresh-config gtk/gtk.css

Observing What Would Change

# 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, 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 for the complete configuration structure and intended usage patterns.

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