Project Layout (Where Things Live)

This section covers the migrations/ directory, which houses Omarchy’s one-time update scripts. These scripts apply incremental fixes, improvements, and configuration tweaks across releases. A dedicated migration runner executes them and tracks their state to ensure each runs exactly once.

Overview

The migrations/ directory contains timestamped shell scripts.
Each script encapsulates a discrete, one-off change for existing installations.

Automate incremental updates without manual intervention.
Handle package installs, config edits, service toggles, etc.
Run once per user; tracked to avoid re-execution.

Directory Structure

Below is the key layout for migrations:

Path	Description
migrations/	Repository directory of migration scripts.
bin/omarchy-migrate	Migration runner CLI.
install/preflight/migrations.sh	Marks migrations as applied during a fresh install.
.local/share/omarchy/migrations/	Installed copy of scripts for end users.
.local/state/omarchy/migrations/	Records which migrations have already run or been skipped.

Migration Scripts

Each file in migrations/ follows the naming convention <unix-timestamp>.sh. The timestamp orders scripts chronologically.

# Example: migrations/1751134560.sh
echo "Add UWSM env"
export OMARCHY_PATH="$HOME/.local/share/omarchy"
export PATH="$OMARCHY_PATH/bin:$PATH"
mkdir -p "$HOME/.config/uwsm/"
omarchy-refresh-config uwsm/env
echo "Reload Hyprland to apply new PATH"  
# Mark this migration as applied (state tracking)  
mkdir -p ~/.local/state/omarchy/migrations  
gum confirm "Ready to relaunch Hyprland?" && touch ~/.local/state/omarchy/migrations/1751134560.sh && uwsm stop

Each script typically:

Begins with echo describing its purpose.
Performs idempotent checks (e.g., if ! grep -q ...).
Invokes Omarchy helper functions (omarchy-pkg-add, omarchy-refresh-config, etc.).
Optionally restarts services or prompts the user.

Migration Runner

Omarchy includes a dedicated runner in bin/omarchy-migrate:

#!/bin/bash
# bin/omarchy-migrate

STATE_DIR="$HOME/.local/state/omarchy/migrations"
mkdir -p "$STATE_DIR"
mkdir -p "$STATE_DIR/skipped"

for file in ~/.local/share/omarchy/migrations/*.sh; do
  filename=$(basename "$file")
  if [[ ! -f "$STATE_DIR/$filename" && ! -f "$STATE_DIR/skipped/$filename" ]]; then
    echo -e "\e[32m\nRunning migration (${filename%.sh})\e[0m"
    if bash "$file"; then
      touch "$STATE_DIR/$filename"
    else
      if gum confirm "Migration ${filename%.sh} failed. Skip and continue?"; then
        touch "$STATE_DIR/skipped/$filename"
      else
        exit 1
      fi
    fi
  fi
done

Iterates all scripts in the installed migrations/ path.
Checks against applied and skipped markers.
Executes pending migrations and records outcomes.

State Tracking

Omarchy tracks migration execution in ~/.local/state/omarchy/migrations/:

An empty file named after each migration marks applied migrations.
A skipped/ subdirectory holds files for migrations that failed and were deliberately bypassed.
Ensures idempotency and prevents duplicate runs.

Preflight Integration

During a fresh installation, Omarchy pre-marks all migrations as applied to avoid retroactive changes:

#!/bin/bash
# install/preflight/migrations.sh

OMARCHY_MIGRATIONS_STATE_PATH=~/.local/state/omarchy/migrations
mkdir -p "$OMARCHY_MIGRATIONS_STATE_PATH"

for file in ~/.local/share/omarchy/migrations/*.sh; do
  touch "$OMARCHY_MIGRATIONS_STATE_PATH/$(basename "$file")"
done

This script runs before any user-level configuration, effectively skipping migrations on new installs.

Developer Tooling

To aid contributors, Omarchy provides bin/omarchy-dev-add-migration:

#!/bin/bash
# bin/omarchy-dev-add-migration

cd ~/.local/share/omarchy
migration_file="$HOME/.local/share/omarchy/migrations/$(git log -1 --format=%cd --date=unix).sh"
touch "$migration_file"
vim "$migration_file"

Automatically names the new migration using the latest Git commit timestamp.
Opens the file in the editor for immediate implementation.

With this structured approach, migrations/ enables smooth upgrades and consistent configuration across Omarchy releases.

Search this space