# How to Re-Sync Configuration Files to Omarchy Defaults: A Complete Guide > Restore Omarchy defaults easily. Learn how to re-sync configuration files using omarchy-refresh-config and automatically back up current settings. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **Run `omarchy-refresh-config ` to restore any shipped default from `$OMARCHY_PATH/config` to `~/.config` while automatically backing up your existing file.** Omarchy maintains a pristine set of upstream configuration files that evolve with the repository, but local customizations in your home directory can drift from these defaults. When you need to re-sync configuration files to Omarchy defaults—whether after a major update or to review upstream changes—the `omarchy-refresh-config` utility provides a safe, atomic mechanism to refresh your local environment while preserving your previous settings. ## Understanding the Configuration Architecture ### Where Defaults Are Stored Omarchy ships with a repository-wide **`$OMARCHY_PATH/config`** directory containing the canonical versions of all supported configuration files. This includes subdirectories for **Hyprland** (`hypr/`), **tmux** (`tmux/`), and other tools. These files represent the "source of truth" that the refresh system references. ### The Core Refresh Script The primary mechanism for re-syncing is located at [`bin/omarchy-refresh-config`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-refresh-config). This Bash script handles path resolution, safety validation, and atomic replacement. It expects a **relative path argument** (e.g., [`hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hypr/hyprland.lua)) that maps to both the source default and your local user configuration. ## How the Refresh Mechanism Works When you invoke the refresh command, the script executes a six-step safety pipeline: 1. **Argument Parsing** – Validates that you provided a relative path rather than an absolute one. 2. **Path Resolution** – Maps your argument to `user_config_file` (`$HOME/.config/`) and `default_config_file` (`$OMARCHY_PATH/config/`). 3. **Existence Guard** – Immediately exits with the error `Not a shipped user config` if the requested file does not exist in the shipped config tree, preventing accidental overwrites of unrelated files. 4. **Directory Preparation** – Creates the target parent directory structure using `mkdir -p` if it does not exist. 5. **Backup and Replace** – Copies your existing user file to a timestamped backup (`.bak.`), then replaces it with the default. 6. **Diff Analysis** – Runs a `diff` between the new default and your backup. If they are identical, the backup is automatically removed to prevent clutter. ### Safety Checks and Validation The script performs strict validation before any file operations occur. It refuses to proceed if the default configuration file is missing from the repository, ensuring you cannot accidentally refresh a custom file that Omarchy does not manage. This guardrail is critical for maintaining system stability. ### Backup Behavior and Diff Output The backup strategy is **intelligent**: backups persist only when the new default differs from your previous version. When differences exist, the script prints a diff to stdout so you can immediately see what has changed upstream. This makes the refresh operation **idempotent**—running it repeatedly on the same file will only generate a backup the first time a change is detected. ## Practical Usage Examples Refresh a single Hyprland configuration file: ```bash omarchy-refresh-config hypr/hyprland.lua ``` Re-sync your tmux configuration: ```bash omarchy-refresh-config tmux/tmux.conf ``` Verify the operation succeeded and inspect any generated backup: ```bash if [[ -e "$HOME/.config/hypr/hyprland.lua.bak."* ]]; then echo "Backup created:" ls -1 "$HOME/.config/hypr/hyprland.lua.bak."* fi ``` ## Integration with Wrapper Scripts While `omarchy-refresh-config` operates on individual files, Omarchy provides higher-level convenience wrappers for refreshing entire application suites. Scripts such as **`omarchy-refresh-hyprland`** and **`omarchy-refresh-tmux`** (located in the same `bin/` directory) invoke the core helper multiple times to refresh entire configuration directories at once. These wrappers ensure consistency across related config files without requiring you to specify each path manually. ## Testing and Validation The integrity of the refresh system is validated by an 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)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/refresh-config-test.sh). Running `./test/shell` executes this test to confirm: - Default files copy correctly to user directories. - Existing user files are backed up only when they differ from new defaults. - Missing default files trigger appropriate error messages. Additional architectural documentation regarding backup file handling and refresh patterns is available in [[`plans/dots.md`](https://github.com/omacom/omarchy/blob/main/plans/dots.md)](https://github.com/omacom/omarchy/blob/quattro/plans/dots.md). ## Summary - Omarchy stores pristine defaults in `$OMARCHY_PATH/config` and local copies in `~/.config`. - The **`omarchy-refresh-config`** script safely re-syncs individual files while creating timestamped backups. - The operation includes strict existence checks to prevent overwriting non-managed files. - Backups are automatically cleaned up when the new default matches your previous version. - Wrapper scripts like `omarchy-refresh-hyprland` provide batch refresh capabilities for entire application suites. - Run `./test/shell` to validate the refresh behavior against the test suite in [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh). ## Frequently Asked Questions ### What happens to my existing config when I run the refresh command? Your existing file is copied to a timestamped backup with the extension `.bak.` before being replaced with the Omarchy default. If the new default is identical to your previous version, the backup is automatically deleted to avoid clutter. ### Can I refresh multiple configuration files at once? While `omarchy-refresh-config` operates on single files, you can use wrapper scripts like **`omarchy-refresh-hyprland`** or **`omarchy-refresh-tmux`** to refresh entire configuration directories. Alternatively, you can script multiple calls to `omarchy-refresh-config` in sequence. ### How do I know if the default file has actually changed? The script prints a `diff` output comparing your backup (previous version) with the newly installed default. This allows you to immediately see exactly what has evolved in the upstream configuration. If no diff appears, your backup was removed because the files were identical. ### What if I try to refresh a file that isn't a shipped default? The script will exit with the error message `Not a shipped user config` if the requested file does not exist in `$OMARCHY_PATH/config`. This safety mechanism prevents you from accidentally overwriting files that Omarchy does not manage.