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

> Discover how Omarchy manages user configuration files using the omarchy-refresh-config workflow. Learn how it safely copies defaults and backs up existing files.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

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

```

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

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json)** – Example of a shipped configuration that can be refreshed to user directories.
- **[`config/hypr/hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/config/hypr/hyprland.lua)** – Default Hyprland window manager configuration maintained by Omarchy.
- **[`config/starship.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.