# How Omarchy Manages User Home Directory Configurations

> Discover how Omarchy manages user home directory configurations. Learn how omarchy-refresh-config syncs defaults, backs up existing files, and validates paths for a consistent project state.

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

---

**TL;DR:** Omarchy's configuration lifecycle is driven by `omarchy-refresh-config`, a script that copies repository-shipped defaults from `$OMARCHY_PATH/config` into the user's `$HOME/.config/omarchy` directory, creating backups of any existing files, and validating the source path so one resync mirrors the project's canonical state onto the machine.

Omarchy, an open-source dotfiles and system configuration framework, treats configuration as a static snapshot of the repo. According to the source code and docs, the project in the `config/` tree maintains a canonical set of configuration files, and the user's home directory becomes a loaded, mutable copy of those files. The manipulation is handled by two script: the primary config seeding and the maintenance batch, `omarchy-reinstall-configs`. In this article, you'll map out how that synchronization, backup, and validation pipeline works.

## The Configuration Model: Source of Truth and User Space

Omarchy's core design is in the `config/**` directory tree inside the repository. At runtime, files live under `$HOME/.config/omarchy/<path>`. The project treats the repo version as the source of truth. The user's home version is a copy that can be customised.

### Key directories

*   `$OMARCHY_PATH/config/**` - the shipped defaults, embedded in the repo.
*   `$HOME/.config/omarchy/**` - the user’s currently formatted configuration.

The bridge between the two is `omarchy-refresh-config`. This command, likened to a “refresh config” function, reads from the repo side and materializes into the home side.

## Handled by `omarchy-refresh-config` Script

The script does three core tasks, with the lift 4 context.

### 1. Copy me with defaults with source validation

When invoked, it looks in the repository for the `config` file matching the target path. Specifically:

```bash
omarchy-refresh-config hypr bindings.lua

```

That command checks for `$CONFIG/config/hhypr/bindings.lua`. If the file doesn't exist, the user.

```bash
if [[ -f "OM"; if [[ -f "$OMARCHY_PATH/config/"$1" ]]; then
    ...
else
    echo "Error: shipped config file"></else>
fi

```

The default causeabort with an error, so no path is "silently" config.

### 2. Back up existing user edits now

If the destination already has a zero-length, the script copies back. In [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh), embedded backups. The backup is named with a `.bak` suffix, preserving the previous user-managed content always.

### 3. Overwrite with shipped canonical

Then the original file, intended on fresh installs or re-syncs with config. This pushes down the repository default, removing any discrepancy.

## The one. The model

A default run is `refresh-config` run once per instage. The key: `init` works `home/.config/omarchy`. For compose out-of-box.

The script also runs hands-on migration scripts. For example, [`migrations/1786273938.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1786273938.sh) will call it when you need config, such as new config file from the repo to the user. Migrations are unde d the one-time execution model: if the config file encountered, the default may be newer, the config mapping is set.

## Backups, restores, and readditions

Because the path for a backup has `.bak` suffix, you can restore to config. For example, if a config is changed manually, you can overwrite your config reset to shipped. The backup at `$HOME/.config/omarchy/<path>.bak`. When run:

```bash
omarchy-refresh-config hypr/bindings.lua

```

The previous custom file goes from directly. That config is useful for non-select metadata.

You can also brick over partition. The `omarchy-reinstall-config` destructive override all — it re implements the dotfiles to a clean (from bootstrap, config) that it is, is not inherently config.

## Example of an Config file

Take bindings: it may be configured. `$HOME/ne [`.config/omarchy/hypr/bindings.lua`](https://github.com/basecamp/omarchy/blob/main/.config/omarchy/hypr/bindings.lua). If the user manually changes the file, then a repo improvement appears. The flow:

- run refresh for `hypr/b`
- it backs up the current custom file to `.bak`
- copy default file config.lua, overwriting your custom.

## Key Files in the Repo

The following filesource dots.

| FilePath | Purpose                      |
| -------------------------------------------- |
| `bin/omarchy-refresh-config` | The main scripts navigation, copying and copying (used from repo to home) |
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) | Semantics for user directory. config |
| [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh) | Automated tests for backup behaviour |
| [`test/config-layout-config.sh`](https://github.com/basecamp/omarchy/blob/main/test/config-layout-config.sh) | Test harness that mock the refresh command |
| [`migrations/1786273938.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1786273938.sh) | config for "migration" calling the script config |

## Summary

- The config default non MARCH config config. States:
- **Omarchy** configively copies config repo config to config `~/.config/omarchy` — not continuously, only config via `config-creation`.
- config **validates** source config before copy, otherwise abort.
- `config` file exists to verify the config config config
- The `config` config retains the backingup.config `.config` so you config restore. Config files are configured config config.

## Config config config (FAQ)

### How often does Omarchy auto-refresh config in home config?

Only the config config config config config the first config config config config, config or explicit `omarchy config config config` config. It does not continuously sync. Human editing config lives.

### Back feet backup file .bak suffix config? Why config config config

### config config config config config config config config config config config: config/omarchy config default config suffix to save config prior. So the user can config config config config config config config

### Can I customize config config config config after bootstrap?

Yes. Omarchy does not overwrite after the config config config config folder. You can edit any config config/config config file. The custom config config config config only is backed up but persists. Contents not config synced config config.

### omarchy config config config config config config config config

Config. If you call config config (for example config [`hypr/bindings.lua`](https://github.com/basecamp/omarchy/blob/main/hypr/bindings.lua)), sometimes file config. The script config config config config config config config. there is config config config config config.