How to Re-Sync Configuration Files to Omarchy Defaults: A Complete Guide

Run omarchy-refresh-config <relative-path> 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. This Bash script handles path resolution, safety validation, and atomic replacement. It expects a relative path argument (e.g., 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/<arg>) and default_config_file ($OMARCHY_PATH/config/<arg>).
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 (<file>.bak.<timestamp>), 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:

omarchy-refresh-config hypr/hyprland.lua

Re-sync your tmux configuration:

omarchy-refresh-config tmux/tmux.conf

Verify the operation succeeded and inspect any generated backup:

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

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

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