How to Run Pending Migrations in Omarchy: Complete Command Guide

Run omarchy-migrate to execute all pending configuration migrations, or use the --pending flag to list unapplied scripts without running them.

Omarchy, Basecamp's Arch Linux-based workstation configuration system, relies on a shell-based migration framework to evolve user configurations safely across updates. To run pending migrations in Omarchy, administrators invoke the omarchy-migrate command, which manages execution state through marker files and enforces atomic, idempotent configuration changes.

Understanding the Migration Architecture

Omarchy migrations are simple shell scripts stored in the migrations/ directory of the repository. Each script represents a discrete configuration change that must run exactly once per user environment.

According to the file layout documentation in docs/file-layout.md, the system tracks completion by creating marker files in the user's state directory:

• Source scripts: Located in migrations/ (e.g., migrations/1787494718.sh)
• Completion markers: Stored in $XDG_STATE_HOME/omarchy/migrations/ (typically ~/.local/state/omarchy/migrations/)

When omarchy-migrate executes, it compares the script names in the source directory against existing markers to determine pending work.

How to Run Pending Migrations in Omarchy

The primary interface is the omarchy-migrate command located at bin/omarchy-migrate.

Apply All Pending Migrations

To execute all unapplied migrations:

omarchy-migrate

This command:

1. Waits for any active Pacman transaction to complete (preventing package conflicts)
2. Scans the migrations/ folder for scripts lacking completion markers
3. Runs each pending script with bash -euo pipefail for strict error handling
4. Creates a marker file upon zero-exit status, or aborts on failure

List Pending Migrations Without Applying

To preview which migrations remain without executing them:

omarchy-migrate --pending

This is useful for CI pipelines, automated health checks, or verifying update readiness before applying changes.

Integration in Custom Scripts

Below is a robust pattern for incorporating migration checks into deployment automation:

#!/bin/bash
set -euo pipefail

# Check for pending work first

if omarchy-migrate --pending | grep -q "Pending migrations"; then
    echo "Applying Omarchy configuration migrations..."
    if ! omarchy-migrate; then
        echo "Migration failed. Manual intervention required."
        exit 1
    fi
fi

The Migration Execution Flow

As implemented in bin/omarchy-migrate, the execution process follows strict safety semantics:

Pacman Transaction Safety The runner first acquires the Pacman lock to ensure no package installation conflicts with configuration changes. This prevents race conditions during system updates.

Strict Execution Mode Each migration runs under bash -euo pipefail, meaning:

• -e: Exits immediately on command failure
• -u: Treats unset variables as errors
• -o pipefail: Propagates pipeline failures

Atomic Completion Tracking A zero exit status automatically creates a marker file in $XDG_STATE_HOME/omarchy/migrations/, permanently marking that migration as complete for the current user. A non-zero exit aborts the current run but leaves the migration pending for the next invocation.

Automatic Migration During Updates

According to docs/update-process.md, the omarchy update command automatically invokes omarchy-migrate after Pacman finishes updating packages. This ensures that configuration changes required by new Omarchy versions apply immediately after software updates.

To manually trigger the full update workflow including migrations:

omarchy update

Desktop Notifications for Pending Migrations

Omarchy includes a systemd-based notification system to alert users of pending work:

• default/systemd/user/omarchy-migrate-notify.service: A user service that triggers on graphical login
• bin/omarchy-migrate-notify: The wrapper script that executes omarchy-migrate --pending

When the notification service detects unapplied migrations, it surfaces a desktop toast prompting the user to run omarchy-migrate. This mechanism ensures that long-running desktop sessions do not miss critical configuration updates.

Summary

• Primary command: omarchy-migrate runs all pending migrations atomically
• Preview mode: omarchy-migrate --pending lists unapplied scripts without execution
• State tracking: Completion markers stored in $XDG_STATE_HOME/omarchy/migrations/
• Safety features: Waits for Pacman locks, uses bash -euo pipefail, aborts on first failure
• Automatic execution: omarchy update calls the migration runner after package updates
• Notification: omarchy-migrate-notify.service alerts users to pending work at login

Frequently Asked Questions

What happens if a migration script fails?

If a migration exits with a non-zero status, omarchy-migrate immediately aborts the current run. The script retains its "pending" status because no completion marker is created. You must fix the underlying issue and rerun omarchy-migrate to apply the failed migration and any subsequent ones.

Where are migration scripts stored in the Omarchy repository?

Migration scripts reside in the migrations/ directory at the repository root. For example, migrations/1787494718.sh demonstrates the standard pattern for marking completion on successful execution. The bin/omarchy-migrate command scans this directory to discover available migrations.

How can I check if migrations are pending without applying them?

Use the --pending flag: omarchy-migrate --pending. This checks $XDG_STATE_HOME/omarchy/migrations/ for missing completion markers and lists the corresponding script names without executing them. The omarchy-migrate-notify wrapper uses this flag to determine whether to display desktop notifications.

Does Omarchy run migrations automatically?

Yes, but only during the update workflow. When you run omarchy update, the command automatically invokes omarchy-migrate after Pacman completes package installations. However, migrations do not run automatically on login or at arbitrary intervals; they require either manual execution or the explicit update command sequence documented in docs/update-process.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}