# How to Resync User Configurations in Omarchy: The Complete Guide

> Resync Omarchy user configurations by running omarchy-refresh-config. This command copies defaults from the repository, backing up existing settings and preserving your preferences.

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

---

**To resync user configurations in Omarchy, run `omarchy-refresh-config <relative-path>` to copy default files from the repository to your home directory while preserving existing settings as timestamped backups.**

Omarchy manages default configuration files within the repository's `config/` directory, while user-specific modifications live in `~/.config/`. When upstream defaults change or you need to reset a configuration to its shipped state, the `omarchy-refresh-config` helper provides a safe, atomic way to synchronize these files without losing your previous customizations.

## Understanding Omarchy's Configuration Architecture

Omarchy separates immutable defaults from mutable user settings using two distinct locations:

- **Default configs**: Stored in `$OMARCHY_PATH/config/` (the repository's `config/` directory)
- **User configs**: Stored in `$HOME/.config/` following standard XDG conventions

When you first install Omarchy or update to a new version, the default files may contain new settings or bug fixes. The refresh mechanism ensures you can adopt these changes without manually diffing files or risking configuration drift.

## Using omarchy-refresh-config to Resync

The core utility for resyncing is `bin/omarchy-refresh-config`, a shell script that handles validation, copying, and backup creation atomically.

### Basic Syntax

The command accepts a single argument: the relative path from `$OMARCHY_PATH/config` to the file you want to resync:

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

```

This command:
1. Validates that `$OMARCHY_PATH/config/hypr/hyprland.lua` exists
2. Creates a timestamped backup if `~/.config/hypr/hyprland.lua` exists
3. Copies the default file to the user config location

### Resyncing Specific Files

You can target individual configuration files that have drifted from defaults:

```bash

# Refresh Hyprland bindings

omarchy-refresh-config hypr/bindings.lua

# Refresh tmux configuration

omarchy-refresh-config tmux/tmux.conf

# Refresh shell settings

omarchy-refresh-config shell/shell.json

```

### Resyncing Entire Configuration Groups

Omarchy ships convenience wrappers in `bin/` that refresh related files simultaneously. These scripts call `omarchy-refresh-config` with predefined paths for specific applications:

- **`omarchy-refresh-hyprland`**: Refreshes all Hyprland-related configs (hyprland.lua, bindings.lua, etc.)
- **`omarchy-refresh-tmux`**: Refreshes tmux configuration files
- **`omarchy-refresh-chromium`**: Refreshes Chromium browser policies and settings
- **`omarchy-refresh-shell`**: Refreshes omarchy's shell.json and related shell configs

To perform a full group resync:

```bash

# Refresh all Hyprland configurations

omarchy-refresh-hyprland

# Refresh tmux setup after an update

omarchy-refresh-tmux

```

## Backup Behavior and Safety Mechanisms

The refresh utility implements defensive copying to prevent data loss. When `omarchy-refresh-config` detects an existing user file, it creates a backup with a timestamped suffix before overwriting:

```bash

# Before: ~/.config/hypr/hyprland.lua

# After:  ~/.config/hypr/hyprland.lua.bak.20240115_143022

#         ~/.config/hypr/hyprland.lua (new copy from defaults)

```

The validation logic in `bin/omarchy-refresh-config` aborts immediately if the requested source file does not exist in `$OMARCHY_PATH/config/`, preventing the creation of orphaned configuration files in your home directory.

## Environment Variables and Custom Paths

The helper respects standard environment variables for testing and non-standard installations:

```bash

# Point to a custom Omarchy installation

OMARCHY_PATH=/opt/omarchy omarchy-refresh-config hypr/hyprland.lua

# Test resyncing to a temporary home directory

HOME=/tmp/test-home OMARCHY_PATH="$OMARCHY_PATH" omarchy-refresh-config shell/shell.json

```

This flexibility allows you to script configuration deployments or test changes in isolated environments before applying them to your live setup.

## Automated Testing and Validation

The correctness of the resync logic is validated by [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh), which verifies:

- Successful copying from defaults to user config
- Timestamped backup creation behavior
- Error handling for non-existent source files
- Proper handling of nested directory structures

These tests ensure that `omarchy-refresh-config` behaves predictably across different shell environments and filesystem states.

## Summary

- **Use `omarchy-refresh-config <path>`** to copy any default file from `$OMARCHY_PATH/config/` to `~/.config/` while preserving the existing file as a `*.bak.<timestamp>` backup.
- **Use group wrappers** like `omarchy-refresh-hyprland` or `omarchy-refresh-tmux` to resync entire application configuration sets with single commands.
- **The utility validates source existence** before copying, preventing the creation of stray configuration files.
- **Backups are automatic and timestamped**, allowing you to recover previous settings if needed.
- **Environment variables `HOME` and `OMARCHY_PATH`** control the source and destination for testing or custom installations.

## Frequently Asked Questions

### What happens to my existing configuration when I resync?

When you run `omarchy-refresh-config`, the utility first checks if a file exists at the destination path. If found, it renames that file using a timestamped backup suffix (e.g., `.bak.20240115_143022`) before copying the new default file into place. This ensures you never lose your customizations, even when forcing a reset to upstream defaults.

### Can I resync all Omarchy configurations at once?

While there is no single "resync everything" command, you can invoke the group-specific wrapper scripts sequentially to refresh all major subsystems. Run `omarchy-refresh-hyprland`, `omarchy-refresh-tmux`, `omarchy-refresh-shell`, and other available wrappers in `bin/` to comprehensively update your environment.

### Is it safe to run omarchy-refresh-config multiple times?

Yes, the operation is idempotent regarding safety. Each execution creates a new timestamped backup of the current user file before overwriting, so you can run the command repeatedly without losing the original configuration from the first run. However, you will accumulate multiple backup files if you resync frequently.

### How do I know which configuration files are available to resync?

The available files correspond to the directory structure inside `$OMARCHY_PATH/config/`. You can list the relative paths of all resyncable files by exploring that directory. The `omarchy-refresh-config` script will exit with an error if you attempt to resync a path that does not exist in the default configuration tree, preventing invalid operations.