# How Omarchy System Defaults Are Managed for New Users > Learn how Omarchy manages system defaults for new users. Discover how omarchy-refresh-config copies version-controlled configurations and preserves customizations. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **Omarchy provisions system defaults for new users by copying version-controlled configuration files from `$OMARCHY_PATH/config` to `~/.config` via the `omarchy-refresh-config` utility, automatically preserving existing customizations through backups before overwriting.** The `omacom/omarchy` repository implements a deterministic provisioning pipeline that eliminates manual configuration for first-time users. This approach delivers a complete, tested desktop environment—including Hyprland window manager settings, tmux configurations, and shell integration—while maintaining safety mechanisms that protect user modifications. ## The Configuration Provisioning Pipeline The default management system relies on a reference-and-refresh architecture that separates pristine defaults from active user configurations. ### Reference Defaults Storage All shipped defaults reside in `$OMARCHY_PATH/config`, organized by subsystem to facilitate modular provisioning: - **`config/hypr/`** – Contains Hyprland window manager configurations including [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) and [`bindings.lua`](https://github.com/omacom/omarchy/blob/main/bindings.lua) - **[`config/tmux/tmux.conf`](https://github.com/omacom/omarchy/blob/main/config/tmux/tmux.conf)** – Provides the default terminal multiplexer setup - **[`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json)** – Defines core shell behavior and Omarchy-specific settings - **`config/omarchy/hooks/`** – Stores optional post-refresh automation scripts ### The Core Refresh Mechanism The `bin/omarchy-refresh-config` script functions as the low-level provisioning engine. When invoked with a relative path, it executes a strict three-phase operation: 1. **Validation** – Verifies the requested file exists in `$OMARCHY_PATH/config`, aborting immediately if the source is missing to prevent typos or missing dependencies 2. **Backup** – Detects existing files at the destination (`$HOME/.config/`) and creates preservation copies in `~/.config/.backup/` before any modifications 3. **Provisioning** – Copies the default from the repository to the user's active configuration directory ```bash # Refresh a specific Hyprland keybinding configuration omarchy-refresh-config hypr/bindings.lua # Refresh the Omarchy shell settings file omarchy-refresh-config omarchy/shell.json ``` ## Wrapper Commands for Bulk Provisioning While `omarchy-refresh-config` handles individual files, convenience wrappers in `bin/` orchestrate complete subsystem refreshes for common use cases: - **`omarchy-refresh-hyprland`** – Provisions the entire Hyprland stack from `config/hypr/`, synchronizing all window manager defaults simultaneously - **`omarchy-refresh-tmux`** – Refreshes the terminal multiplexer configuration specifically via [`config/tmux/tmux.conf`](https://github.com/omacom/omarchy/blob/main/config/tmux/tmux.conf) - **`omarchy-refresh-shell`** – Updates the Omarchy shell JSON configuration and related integration components ```bash # Refresh the complete Hyprland configuration suite omarchy-refresh-hyprland # Update tmux defaults independently omarchy-refresh-tmux # Synchronize shell integration settings omarchy-refresh-shell ``` ## Safety Mechanisms and Backup Strategy The provisioning system implements defensive safeguards to prevent configuration loss. Before overwriting any existing user file, `bin/omarchy-refresh-config` automatically archives the current version to `~/.config/.backup/`, enabling rollback if the new defaults conflict with established workflows. The command also enforces strict source validation. Attempting to refresh a non-existent default path causes immediate termination with an error status, protecting against the creation of empty or corrupted configuration files due to path typos. ## Post-Refresh Hooks and Customization Following successful file provisioning, the system executes optional hook scripts located in `config/omarchy/hooks/`. These hooks enable automation such as displaying desktop notifications when themes change, triggering battery-low warnings, or restarting dependent services. Users extend default behavior by adding executable scripts to this directory, which run automatically after any refresh operation completes. ## Testing and Reliability The [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh) test suite validates the entire provisioning pipeline across release cycles. These automated checks confirm that: - Files copy correctly from repository defaults to user directories - Backup creation triggers properly when destination files pre-exist - Missing source files cause graceful, noisy failures rather than silent corruption This coverage ensures that new users receive reliable, predictable configuration states regardless of installation environment. ## Summary - Omarchy stores pristine defaults in `$OMARCHY_PATH/config`, with discrete subdirectories for Hyprland (`config/hypr/`), tmux (`config/tmux/`), and shell settings (`config/omarchy/`) - The `bin/omarchy-refresh-config` script copies individual files while validating sources exist and backing up existing user configs to `~/.config/.backup/` - Wrapper commands (`omarchy-refresh-hyprland`, `omarchy-refresh-tmux`, `omarchy-refresh-shell`) simplify bulk provisioning of related configuration sets - Post-refresh hooks in `config/omarchy/hooks/` enable custom automation triggered by default updates - Automated tests in [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh) ensure the provisioning system remains reliable across different system environments ## Frequently Asked Questions ### What happens to my existing configuration when I run omarchy-refresh-config? The command automatically detects existing files in your `~/.config/` directory and archives them to `~/.config/.backup/` before applying new defaults. Your previous settings remain recoverable, making the refresh process safe to execute repeatedly without risking permanent loss of customizations. ### Where are the default configuration files stored in the Omarchy repository? All default configurations live in the `config/` directory at the repository root, referenced via the `$OMARCHY_PATH/config` environment variable. This includes `config/hypr/` for window manager settings, [`config/tmux/tmux.conf`](https://github.com/omacom/omarchy/blob/main/config/tmux/tmux.conf) for terminal multiplexer defaults, and [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) for shell integration parameters. ### Can I customize what happens after a config refresh? Yes. Place executable scripts in `config/omarchy/hooks/` to trigger custom actions following any refresh operation. These hooks can display system notifications, restart services, or perform other post-provisioning tasks automatically when the system updates its defaults. ### How do I refresh only the Hyprland configuration without affecting other settings? Run `omarchy-refresh-hyprland` to update exclusively the Hyprland-related defaults, or use `omarchy-refresh-config hypr/` to refresh specific individual files such as [`hypr/bindings.lua`](https://github.com/omacom/omarchy/blob/main/hypr/bindings.lua). This targeted approach leaves your tmux, shell, and other subsystem configurations completely untouched.