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

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:

default_config_file="$OMARCHY_PATH/config/$config_file"

This design allows users to reference configurations naturally—such as 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:

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:

$ 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:

$ 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:

$ 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 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 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.

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