How Omarchy Handles User Configuration and System Defaults: A Complete Guide

Omarchy separates configuration into two layers—system defaults shipped in config/ and user overrides in ~/.config—with the omarchy-refresh-config command syncing them while preserving customizations through automatic backups.

Omarchy's configuration system lets users customize their environment without losing access to upstream improvements. This dual-layer approach ensures that system defaults remain version-controlled while personal modifications survive updates. The mechanism relies on predictable file paths and a dedicated refresh command that handles merging safely.

The Two-Layer Configuration Model

Omarchy organizes settings into distinct system and user tiers that follow the same relative directory structure.

System-Default Configuration

Default configurations live in the config/ directory at the repository root. These files are read from $OMARCHY_PATH/config at runtime and serve as the authoritative baseline.

Key default locations include:

• config/hypr/hyprland.lua — default Hyprland compositor settings
• config/omarchy/shell.json — core Omarchy shell definition
• config/herdr/config.toml — Herdr service configuration

These paths mirror the standard XDG configuration layout, making overlay logic straightforward.

User-Specific Configuration

User overrides reside in ~/.config following identical relative paths. When Omarchy needs a configuration value, it checks the user location first, falling back to system defaults only when no custom file exists.

This design means:

• Users can copy and modify any default without touching repository files
• Upstream updates to defaults remain available for selective adoption
• No merge conflicts occur since files are never directly edited in place

The omarchy-refresh-config Command

The omarchy-refresh-config command is the core mechanism that synchronizes defaults to user space. Implemented in bin/omarchy-refresh-config, it handles three critical operations: existence checking, backup creation, and validation.

Copy-on-First-Run Behavior

When invoked, the command copies from $OMARCHY_PATH/config/<path> to $HOME/.config/<path> only if the target does not already exist. This ensures fresh installations receive working defaults while existing setups remain untouched.

Automatic Backup Before Overwrite

If a user file already exists, the command first creates a *.bak backup before writing the new default:

# The refresh command backs up existing files automatically

omarchy-refresh-config hypr/hyprland.lua

# Creates ~/.config/hypr/hyprland.lua.bak if user version exists

This guarantees no custom changes are lost during intentional refreshes.

Validation and Error Handling

The command validates that the requested configuration exists in the defaults directory. If the source file is missing, it aborts with an error rather than creating broken symlinks or empty files.

Working with omarchy-refresh-config

Basic Usage

Refresh a single default configuration into your user directory:

omarchy-refresh-config hypr/hyprland.lua

This creates ~/.config/hypr/hyprland.lua if absent, or backs up and replaces it if present.

Scripted Refresh with Environment Variables

For automation or testing, explicitly set the required paths:

HOME="$HOME" OMARCHY_PATH="$OMARCHY_PATH" \
omarchy-refresh-config hypr/bindings.lua

Migration Script Integration

The migrations/1786273938.sh file demonstrates how Omarchy uses refresh commands during system updates:

# From migrations/1786273938.sh

[[ -f "$HOME/.config/herdr/config.toml" ]] || \
omarchy-refresh-config herdr/config.toml

This pattern ensures new defaults propagate to existing installations without forcing overwrites.

Verifying Results

Confirm the refresh succeeded by checking the target location:

ls -la ~/.config/hypr/hyprland.lua

# Should show timestamp matching your refresh operation

Testing and Quality Assurance

The configuration refresh mechanism includes comprehensive test coverage in test/shell.d/refresh-config-test.sh. These automated tests verify:

• Correct copying behavior for missing user files
• Backup creation and naming conventions
• Proper error responses for invalid source paths
• Environment variable handling

Running this suite ensures the refresh command behaves predictably across shell versions and platform variations.

Configuration File Reference

Role	File Path	Description
Default configs	config/hypr/hyprland.lua	Shipped Hyprland compositor configuration
Default configs	config/omarchy/shell.json	Core Omarchy shell definition
Default configs	config/herdr/config.toml	Herdr service defaults
Refresh command	bin/omarchy-refresh-config	Implements copying, backup, and validation
Test suite	test/shell.d/refresh-config-test.sh	Automated behavior verification
Migration pattern	migrations/1786273938.sh	Production usage example

Summary

• System defaults live in config/ under the Omarchy installation path and ship with every version
• User overrides use matching paths in ~/.config and take precedence at runtime
• omarchy-refresh-config syncs defaults to user space with automatic backup protection
• Migration scripts leverage the refresh command to distribute new configuration options safely

This architecture gives Omarchy users full customization freedom while maintaining a clear upgrade path for system improvements.

Frequently Asked Questions

What happens to my custom settings when I run omarchy-refresh-config?

The command creates a *.bak backup of any existing user file before overwriting it. Your original configuration is preserved with a timestamped backup extension, allowing recovery if the new default causes issues.

Can I restore a previous configuration after refreshing?

Yes. Each refresh that overwrites an existing file generates a .bak version in the same directory. Simply rename or copy the backup file to restore your previous settings:

mv ~/.config/hypr/hyprland.lua.bak ~/.config/hypr/hyprland.lua

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

Examine the config/ directory in your Omarchy installation path. Any file or subdirectory there can be refreshed using its relative path as the argument to omarchy-refresh-config:

find "$OMARCHY_PATH/config" -type f

Does Omarchy automatically refresh configurations during updates?

No automatic refresh occurs during standard updates. However, migration scripts in the migrations/ directory selectively refresh specific files when new defaults are required for functionality. These migrations use the same omarchy-refresh-config command with existence checks to avoid overwriting user customizations.

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