How Omarchy Handles Configuration Updates for Existing Users

Omarchy uses a built-in omarchy-refresh-config workflow that safely updates configuration files while preserving existing user customizations through automatic backups.

The omacom/omarchy repository implements a safe configuration update system designed specifically for users who have already customized their Linux environment. Rather than blindly overwriting files, the refresh workflow ensures no data loss through timestamped backups and idempotent operations.

The omarchy-refresh-config Refresh Workflow

The core mechanism for handling configuration updates is the omarchy-refresh-config helper script located at bin/omarchy-refresh-config. This utility manages the entire lifecycle of updating default configurations while respecting user modifications.

How the Refresh Process Works

When executed, the script follows a strict five-step safety protocol:

1. Identifies the source file — Locates the default configuration in the repository under config/… (e.g., config/hypr/hyprland.jl)
2. Computes the target path — Resolves the user's local config directory (~/.config/hypr/hyprland.jl)
3. Checks for existing files — Verifies whether the user has an existing customized version
4. Creates a backup — Preserves the existing file with a timestamp or .bak suffix before any modification
5. Copies the new default — Writes the updated configuration only if the target path is writable

This sequence guarantees that no user customization is ever lost without explicit recovery steps.

Key Safety Guarantees

The omarchy-refresh-config implementation provides three critical protections for existing users:

• Data preservation — Previous versions are always retained as timestamped backups
• Idempotent execution — Repeated runs will not create duplicate backups or corrupt configurations
• Customization integrity — Users can manually merge changes from new defaults into their backed-up versions

How to Refresh Configuration Files

Refresh a Single Configuration File

Update one specific configuration file while preserving your existing version:

omarchy-refresh-config hypr/hyprland.jl

Refresh Multiple Files with Wildcard Patterns

Apply updates to entire configuration directories in one operation:

omarchy-refresh-config "waybar/*.jsonc"

Inspect and Recover from Backups

After a refresh, verify your backup files and restore if needed:

ls -l ~/.config/hypr/hyprland.jl.bak*

Where Configuration Updates Originate

Repository Default Configurations

Default configurations reside in the config/ directory tree, as documented in docs/file-layout.md. These paths map directly to user directories under $HOME/.config/.

Repository Path	User Target Path
config/hypr/hyprland.jl	~/.config/hypr/hyprland.jl
config/waybar/config.jsonc	~/.config/waybar/config.jsonc

Documentation and Testing Coverage

The update workflow is comprehensively documented and tested:

• docs/update-process.md — Explains the refresh workflow and backup strategy in detail
• docs/file-layout.md — Maps repository config locations to user directory structures
• test/shell.d/refresh-config-test.sh — Automated tests verifying safe updates and backup creation

When to Run Configuration Updates

After Repository Pulls

Execute omarchy-refresh-config after updating your local Omarchy installation to receive the latest default configurations.

Before Major Customization Sessions

Run the refresh proactively to ensure your base configuration is current before making extensive personal modifications—this minimizes divergence from upstream defaults.

During Troubleshooting

Refresh specific files to reset configurations to known-good states while retaining your original files for reference:

# Reset Hyprland configuration to defaults

omarchy-refresh-config hypr/hyprland.jl

# Compare with your backup to identify problematic changes

diff ~/.config/hypr/hyprland.jl.bak* ~/.config/hypr/hyprland.jl

Summary

• Configuration updates in Omarchy are handled by the omarchy-refresh-config helper script at bin/omarchy-refresh-config
• Automatic backups preserve existing user customizations with timestamped or .bak suffixed files
• Idempotent operations ensure repeated refreshes never corrupt configurations or create backup clutter
• Wildcard support enables batch updates of related configuration files
• Comprehensive testing in test/shell.d/refresh-config-test.sh validates the safety guarantees

Frequently Asked Questions

What happens if I run omarchy-refresh-config multiple times?

The refresh operation is idempotent. Running it repeatedly will not create duplicate backups or corrupt your configuration. If the target file already matches the source, no action is taken. If you've modified the file since the last refresh, a new backup is created with a fresh timestamp, preserving each prior state.

Can I restore my previous configuration after a refresh?

Yes. The refresh process automatically generates timestamped backup files with .bak* suffixes. Locate your backup using ls ~/.config/[app]/*.bak* and restore by copying or moving the backup file over the refreshed configuration. No special restore command is required—standard shell operations suffice.

Does Omarchy merge my customizations with new defaults automatically?

No. Omarchy deliberately does not perform automatic merging to prevent silent configuration conflicts. New defaults replace old defaults, with your previous version preserved as a backup. You must manually merge desired changes using standard diff and editing tools. This design prioritizes predictability over convenience.

Which configuration files support the refresh workflow?

Any file under the config/ directory tree supports refresh operations. Common examples include hypr/hyprland.jl, waybar/config.jsonc, foot/foot.ini, and fish/config.fish. Use wildcard patterns like "hypr/*.conf" to refresh entire configuration suites at once.

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