How to Resync User Configurations in Omarchy: The Complete Guide

To resync user configurations in Omarchy, run omarchy-refresh-config <relative-path> to copy default files from the repository to your home directory while preserving existing settings as timestamped backups.

Omarchy manages default configuration files within the repository's config/ directory, while user-specific modifications live in ~/.config/. When upstream defaults change or you need to reset a configuration to its shipped state, the omarchy-refresh-config helper provides a safe, atomic way to synchronize these files without losing your previous customizations.

Understanding Omarchy's Configuration Architecture

Omarchy separates immutable defaults from mutable user settings using two distinct locations:

• Default configs: Stored in $OMARCHY_PATH/config/ (the repository's config/ directory)
• User configs: Stored in $HOME/.config/ following standard XDG conventions

When you first install Omarchy or update to a new version, the default files may contain new settings or bug fixes. The refresh mechanism ensures you can adopt these changes without manually diffing files or risking configuration drift.

Using omarchy-refresh-config to Resync

The core utility for resyncing is bin/omarchy-refresh-config, a shell script that handles validation, copying, and backup creation atomically.

Basic Syntax

The command accepts a single argument: the relative path from $OMARCHY_PATH/config to the file you want to resync:

omarchy-refresh-config hypr/hyprland.lua

This command:

1. Validates that $OMARCHY_PATH/config/hypr/hyprland.lua exists
2. Creates a timestamped backup if ~/.config/hypr/hyprland.lua exists
3. Copies the default file to the user config location

Resyncing Specific Files

You can target individual configuration files that have drifted from defaults:

# Refresh Hyprland bindings

omarchy-refresh-config hypr/bindings.lua

# Refresh tmux configuration

omarchy-refresh-config tmux/tmux.conf

# Refresh shell settings

omarchy-refresh-config shell/shell.json

Resyncing Entire Configuration Groups

Omarchy ships convenience wrappers in bin/ that refresh related files simultaneously. These scripts call omarchy-refresh-config with predefined paths for specific applications:

• omarchy-refresh-hyprland: Refreshes all Hyprland-related configs (hyprland.lua, bindings.lua, etc.)
• omarchy-refresh-tmux: Refreshes tmux configuration files
• omarchy-refresh-chromium: Refreshes Chromium browser policies and settings
• omarchy-refresh-shell: Refreshes omarchy's shell.json and related shell configs

To perform a full group resync:

# Refresh all Hyprland configurations

omarchy-refresh-hyprland

# Refresh tmux setup after an update

omarchy-refresh-tmux

Backup Behavior and Safety Mechanisms

The refresh utility implements defensive copying to prevent data loss. When omarchy-refresh-config detects an existing user file, it creates a backup with a timestamped suffix before overwriting:

# Before: ~/.config/hypr/hyprland.lua

# After:  ~/.config/hypr/hyprland.lua.bak.20240115_143022

#         ~/.config/hypr/hyprland.lua (new copy from defaults)

The validation logic in bin/omarchy-refresh-config aborts immediately if the requested source file does not exist in $OMARCHY_PATH/config/, preventing the creation of orphaned configuration files in your home directory.

Environment Variables and Custom Paths

The helper respects standard environment variables for testing and non-standard installations:

# Point to a custom Omarchy installation

OMARCHY_PATH=/opt/omarchy omarchy-refresh-config hypr/hyprland.lua

# Test resyncing to a temporary home directory

HOME=/tmp/test-home OMARCHY_PATH="$OMARCHY_PATH" omarchy-refresh-config shell/shell.json

This flexibility allows you to script configuration deployments or test changes in isolated environments before applying them to your live setup.

Automated Testing and Validation

The correctness of the resync logic is validated by test/shell.d/refresh-config-test.sh, which verifies:

• Successful copying from defaults to user config
• Timestamped backup creation behavior
• Error handling for non-existent source files
• Proper handling of nested directory structures

These tests ensure that omarchy-refresh-config behaves predictably across different shell environments and filesystem states.

Summary

• Use omarchy-refresh-config <path> to copy any default file from $OMARCHY_PATH/config/ to ~/.config/ while preserving the existing file as a *.bak.<timestamp> backup.
• Use group wrappers like omarchy-refresh-hyprland or omarchy-refresh-tmux to resync entire application configuration sets with single commands.
• The utility validates source existence before copying, preventing the creation of stray configuration files.
• Backups are automatic and timestamped, allowing you to recover previous settings if needed.
• Environment variables HOME and OMARCHY_PATH control the source and destination for testing or custom installations.

Frequently Asked Questions

What happens to my existing configuration when I resync?

When you run omarchy-refresh-config, the utility first checks if a file exists at the destination path. If found, it renames that file using a timestamped backup suffix (e.g., .bak.20240115_143022) before copying the new default file into place. This ensures you never lose your customizations, even when forcing a reset to upstream defaults.

Can I resync all Omarchy configurations at once?

While there is no single "resync everything" command, you can invoke the group-specific wrapper scripts sequentially to refresh all major subsystems. Run omarchy-refresh-hyprland, omarchy-refresh-tmux, omarchy-refresh-shell, and other available wrappers in bin/ to comprehensively update your environment.

Is it safe to run omarchy-refresh-config multiple times?

Yes, the operation is idempotent regarding safety. Each execution creates a new timestamped backup of the current user file before overwriting, so you can run the command repeatedly without losing the original configuration from the first run. However, you will accumulate multiple backup files if you resync frequently.

How do I know which configuration files are available to resync?

The available files correspond to the directory structure inside $OMARCHY_PATH/config/. You can list the relative paths of all resyncable files by exploring that directory. The omarchy-refresh-config script will exit with an error if you attempt to resync a path that does not exist in the default configuration tree, preventing invalid operations.

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