How omarchy-refresh-config Handles Default Configurations and Backups in Omarchy

omarchy-refresh-config is a Bash utility that synchronizes shipped configuration files from the Omarchy repository into the user's ~/.config directory while automatically backing up existing customizations and displaying diffs of any changes.

The omarchy-refresh-config script serves as the backbone of Omarchy's configuration management strategy, ensuring users can safely update to new defaults without losing personal modifications. Located at bin/omarchy-refresh-config in the omacom/omarchy repository, this tool implements a transactional copy-and-backup pattern that validates source files, preserves existing state with timestamped backups, and provides visual feedback through diff output when changes occur.

Path Resolution and Environment Setup

The script begins by constructing three critical file paths based on the user's input argument.

When invoked with a relative path such as hypr/hyprland.lua, the script defines:

• user_config_file – resolves to $HOME/.config/<provided-path> 【line 20】
• default_config_file – resolves to $OMARCHY_PATH/config/<provided-path> 【line 21】
• backup_config_file – set to $user_config_file.bak.<timestamp> using the current Unix timestamp 【line 22】

This triad of paths establishes the source of truth (the repository's defaults), the destination (user's live configuration), and the safety net (the backup location).

Input Validation and Directory Preparation

Before any file operations occur, the script enforces strict validation to prevent corruption or invalid states.

First, it verifies that the default_config_file actually exists on disk. If the shipped configuration is missing, the script aborts immediately with an error message, preventing attempts to refresh non-existent defaults 【lines 24-27】. This check ensures that only officially supported configuration files can be refreshed.

Next, the script guarantees the target directory hierarchy exists by executing mkdir -p "$(dirname "$user_config_file")" 【line 29】. This step prevents copy failures when the user has not yet created the specific configuration subdirectory (e.g., ~/.config/hypr/).

Backup-and-Replace Logic

The core functionality distinguishes between updating existing configurations and performing first-time installations.

When an existing file is detected at user_config_file 【line 31】:

1. Preserve: The current user configuration is copied to the backup_config_file location using cp -f "$user_config_file" "$backup_config_file" 【line 32】
2. Replace: The default configuration is force-copied over the user file with cp -f "$default_config_file" "$user_config_file" 【line 34】
3. Compare: The script checks if the new content differs from the backup 【line 35】
   • If identical, the backup is removed with rm "$backup_config_file" to avoid clutter 【line 37】
   • If different, a colored success message is printed and a diff between the backup and new file is displayed to show exactly what changed 【lines 38-40】

This workflow ensures users always have a rollback path and full visibility into upstream changes.

First-Time Configuration Installation

If the user has no existing configuration file at the target location, the script bypasses the backup logic entirely.

In this case, it simply executes cp -f "$default_config_file" "$user_config_file" to install the default configuration 【lines 41-43】. No backup is created since there was no previous state to preserve, making initial setup clean and efficient.

Practical Usage Examples

Refresh an existing Hyprland configuration to receive upstream updates while preserving your current setup:

omarchy-refresh-config hypr/hyprland.lua

If the file exists, this creates a backup like ~/.config/hypr/hyprland.lua.bak.1728394000, copies the new default, and displays a diff of changes.

For first-time installation of a configuration file that doesn't exist yet:

omarchy-refresh-config kitty/kitty.conf

This simply copies the default into place without creating a backup, since there is no previous state to preserve.

Testing and Automated Verification

The behavior of omarchy-refresh-config is validated by the automated test suite located at test/shell.d/refresh-config-test.sh.

These tests verify:

• Correct copying of default files to user directories
• Proper backup creation with valid timestamps when updating existing configs
• Appropriate error handling when the requested default file does not exist in the repository

This comprehensive test coverage ensures the script behaves predictably across edge cases and system updates.

Summary

• omarchy-refresh-config constructs three paths: the user's live config, the repository default, and a timestamped backup location.
• The script validates that default files exist before proceeding and creates parent directories as needed.
• Existing configurations are backed up before replacement, with automatic cleanup if the new file matches the old one.
• Users receive immediate visual feedback through colored messages and diff output when upstream changes occur.
• First-time installations skip backup creation to avoid empty backup files.

Frequently Asked Questions

Where does omarchy-refresh-config store backup files?

Backup files are stored in the same directory as the original user configuration, using the naming pattern <original-filename>.bak.<timestamp>. For example, refreshing ~/.config/hypr/hyprland.lua creates a backup at ~/.config/hypr/hyprland.lua.bak.1728394000, allowing easy restoration if the new defaults break functionality.

What happens if the default configuration file is missing from the Omarchy repository?

The script aborts immediately with an error message. At lines 24-27, the script checks if default_config_file exists using a conditional test, and exits if the file is not found. This prevents the utility from attempting to copy non-existent defaults and potentially leaving the user with broken configuration paths.

Does omarchy-refresh-config show what changes were made during a refresh?

Yes. When an existing configuration is updated, the script compares the new file against the backup. If changes are detected, it prints a colored success message and executes a diff command between the backup and the updated file, displaying exactly which lines were added, removed, or modified in the default configuration.

How does the script handle directories that don't exist yet?

The script automatically creates the necessary parent directories before copying any files. Using mkdir -p "$(dirname "$user_config_file")" at line 29, it ensures the full path structure exists, preventing errors when refreshing configurations for applications the user hasn't configured before or when installing Omarchy on a fresh system.

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