# How omarchy-refresh-config Handles Default Configurations and Backups in Omarchy > Discover how omarchy-refresh-config synchronizes default configs, backs up customizations, and shows diffs in Omarchy. Learn about its intelligent file handling. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-13 --- **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`](https://github.com/omacom/omarchy/blob/main/hypr/hyprland.lua), the script defines: - `user_config_file` – resolves to `$HOME/.config/` 【line 20】 - `default_config_file` – resolves to `$OMARCHY_PATH/config/` 【line 21】 - `backup_config_file` – set to `$user_config_file.bak.` 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: ```bash 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: ```bash 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`](https://github.com/omacom/omarchy/blob/main/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 `.bak.`. 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.