How Omarchy Manages User Configuration Files: The omarchy-refresh-config Workflow Explained

Omarchy manages user configuration files through the omarchy-refresh-config command, which copies default configurations from the repository's config/ directory to ~/.config while automatically backing up existing files with a .bak suffix.

The basecamp/omarchy repository implements a straightforward yet robust system for synchronizing default application configurations to user directories. This approach ensures that shipped updates can be applied safely without destroying custom user modifications. All configuration management revolves around a single shell command that handles validation, backup, and deployment in an idempotent manner.

The Configuration Storage Architecture

Omarchy stores all default configuration files inside the repository under the config/ directory. These files represent the canonical, shipped configurations for supported applications including Hyprland, Alacritty, Starship, and other tools.

The system relies on the $OMARCHY_PATH environment variable, which points to the repository checkout location. This variable allows the refresh command to locate source files at $OMARCHY_PATH/config/<relative-path>, enabling users to reference configurations using simple relative paths regardless of where Omarchy is installed.

How the omarchy-refresh-config Command Works

Located in bin/omarchy-refresh-config, the core command executes a five-step process:

Locating Source Configuration Files

When invoked, the command constructs the source path by appending the user-provided relative path to $OMARCHY_PATH/config/. For example, calling omarchy-refresh-config hypr/hyprland.lua targets $OMARCHY_PATH/config/hypr/hyprland.lua.

Validating Config Existence

Before performing any operations, the command verifies that the requested file exists in the shipped configuration. If the source file is missing, the command aborts immediately with a non-zero exit status and reports the error. This validation logic is thoroughly tested in test/shell.d/refresh-config-test.sh, which ensures the command fails gracefully when referencing non-existent paths.

Backing Up Existing User Configurations

If a file already exists at the target location in the user's $HOME/.config directory, Omarchy renames it with a .bak suffix before overwriting. This safeguarding mechanism protects any customizations the user may have made, creating a restore point that can be manually recovered if needed.

Copying Defaults and Preserving Metadata

The default file is copied to the user's config directory using operations that preserve original permissions and timestamps. This ensures the deployed configuration maintains the same attributes as the version controlled source.

Reporting and Exit Status

On successful completion, the command returns a zero exit status. On failure—such as missing source files or copy errors—it returns a non-zero status and prints a descriptive error message to stderr.

Practical Usage Examples

Refresh a single configuration file for Hyprland:

OMARCHY_PATH="$HOME/.local/share/omarchy" \
omarchy-refresh-config hypr/hyprland.lua

Refresh all default configurations at once using a repository-aware loop:

for cfg in $(git ls-files "config/**" | cut -d'/' -f2-); do
    omarchy-refresh-config "$cfg"
done

Example output when the command creates a backup and copies the new file:

Backup created: /home/joe/.config/hypr/hyprland.lua.bak
Copied: /home/joe/.config/hypr/hyprland.lua

Example error when requesting a non-existent configuration:

Error: Config file 'hypr/missing.lua' does not exist in $OMARCHY_PATH/config

Key Implementation Files

Several files in the basecamp/omarchy repository support this configuration management system:

• bin/omarchy-refresh-config – The core executable that implements the copy, backup, and validation logic.
• test/shell.d/refresh-config-test.sh – Automated test suite verifying proper handling of existing files, backup creation, and error conditions.
• config/omarchy/shell.json – Example of a shipped configuration that can be refreshed to user directories.
• config/hypr/hyprland.lua – Default Hyprland window manager configuration maintained by Omarchy.
• config/starship.toml – Default Starship prompt configuration available for refresh.
• install/config/ – Helper scripts used during system installation to establish system-wide configurations, such as theme-system.sh.

Summary

• Omarchy stores default configurations in the repository's config/ directory, referenced via $OMARCHY_PATH.
• The omarchy-refresh-config command is idempotent: running it repeatedly replaces the user config with the shipped version but only backs up the previous version once.
• Existing user configurations are automatically preserved with .bak extensions before overwriting.
• The command validates source file existence before attempting copies, preventing partial or broken deployments.
• Exit codes indicate success (zero) or specific failure modes (non-zero), enabling reliable scripting and automation.

Frequently Asked Questions

What happens to my existing config files when I run omarchy-refresh-config?

Omarchy automatically renames any existing file at the target location with a .bak suffix before copying the new default. For example, ~/.config/hypr/hyprland.lua becomes ~/.config/hypr/hyprland.lua.bak. This ensures your customizations are preserved and can be manually restored if the new default configuration introduces unwanted changes.

Where does Omarchy store the default configuration templates?

Default configurations are stored in the config/ directory at the repository root. When you run omarchy-refresh-config, it reads from $OMARCHY_PATH/config/<relative-path>, where $OMARCHY_PATH is an environment variable pointing to your Omarchy installation. This design allows the command to work regardless of whether Omarchy is installed in ~/.local/share/omarchy, /opt/omarchy, or another location.

How can I refresh all Omarchy configuration files at once?

You can batch-refresh all configurations by combining git ls-files with a loop that strips the config/ prefix. The command git ls-files "config/**" lists all tracked configuration files, and piping through cut -d'/' -f2- removes the top-level directory, yielding paths suitable for omarchy-refresh-config. Run this from within the Omarchy repository to update all application configs simultaneously.

Why does omarchy-refresh-config require the $OMARCHY_PATH environment variable?

The $OMARCHY_PATH variable decouples the command from hardcoded installation paths, making the system portable across different directory structures. According to the source code in bin/omarchy-refresh-config, this variable must point to the repository checkout so the command can locate source files under config/. If unset, the command cannot resolve the default configuration sources and will fail with an error.

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