Omarchy Migration Scripts: Location and Execution Guide

Omarchy migration scripts reside in the migrations/ directory at the repository root, utilize numeric filenames to determine execution order, and are processed by the omarchy-migrate command which tracks completion status in $XDG_STATE_HOME/omarchy/migrations/.

Omarchy, the open-source system configuration framework maintained by omacom, relies on a structured migration system to apply system updates reliably across different environments. Understanding where these Omarchy migration scripts are located and how the execution engine processes them is critical for system administrators troubleshooting update failures or extending the platform.

Where Omarchy Migration Scripts Are Located

The migration infrastructure lives in the migrations/ directory at the root of the omacom/omarchy repository. Each migration is a self-contained Bash script whose filename consists of a numeric Unix timestamp followed by the .sh extension (e.g., 1788124236.sh). This numeric prefix ensures deterministic ordering when sorted lexicographically.

According to the source tree, the directory structure follows this pattern:

• Directory: migrations/ — Contains all system-wide migration scripts
• Example file: migrations/1788124236.sh — Demonstrates privileged action handling

All scripts in this directory are plain text and executable, designed to run with bash -euo pipefail to ensure strict error handling during system modifications.

How the omarchy-migrate Command Executes Scripts

Execution is handled by the omarchy-migrate wrapper script installed under bin/ in the repository. This command serves as the orchestration layer between the raw migration scripts and the system's state tracking mechanism.

The Execution Workflow

When invoked without arguments, omarchy-migrate performs the following steps:

1. Discovery: Scans the migrations/ directory for files matching the *.sh pattern.

2. Sorting: Orders discovered scripts lexicographically by filename, ensuring ascending numeric execution (e.g., 1788124235.sh runs before 1788124236.sh).

3. Execution: Runs each pending script using bash -euo pipefail to enforce strict error handling and pipeline failure detection.

4. Completion Tracking: If a script exits with status zero, omarchy-migrate creates a marker file under $XDG_STATE_HOME/omarchy/migrations/ to prevent re-execution on subsequent runs.

Command-Line Interface

The migration runner supports operational flags for administrative visibility:

# Execute all pending migrations (standard post-update flow)

omarchy-migrate

# Display pending migrations without executing them

omarchy-migrate --pending

Systemd Integration and Notifications

The migration system integrates with omarchy-migrate-notify, a systemd service that monitors for pending migrations. When unapplied scripts exist, this service displays desktop notifications prompting the user to execute omarchy-migrate manually, typically from a terminal where privilege escalation is possible.

Anatomy of an Omarchy Migration Script

Migration scripts follow a standardized Bash template. As implemented in migrations/1788124236.sh, scripts must handle both standard system modifications and privilege escalation gracefully:

#!/usr/bin/env bash

# Example migration – file name: 1788124236.sh

set -euo pipefail

# … perform actions, e.g. modify config files, adjust system settings …

# If privileged actions are required, print a helpful message:

echo "Administrator privileges are required to apply this migration. Run omarchy-migrate again from a terminal." >&2

The set -euo pipefail directive ensures that any command failure, unset variable, or pipeline error immediately terminates the script, preventing partial system states. Scripts requiring root access should output clear instructions to stderr rather than failing silently.

Summary

• Omarchy migration scripts are stored in the migrations/ directory at the repository root, using numeric filenames (Unix timestamps) to determine execution sequence.
• The omarchy-migrate command in bin/ handles execution, sorting scripts lexicographically and running them with bash -euo pipefail.
• Completion state is tracked via marker files in $XDG_STATE_HOME/omarchy/migrations/, preventing duplicate execution.
• Use omarchy-migrate --pending to audit unapplied migrations before execution.
• The omarchy-migrate-notify systemd service alerts users when manual migration intervention is required.

Frequently Asked Questions

Where are Omarchy migration scripts stored in the repository?

Omarchy migration scripts are located in the migrations/ directory at the root of the omacom/omarchy repository. Each file uses a numeric naming convention (e.g., 1788124236.sh) to ensure proper ordering during execution.

How does Omarchy determine which migration scripts to run?

The omarchy-migrate command sorts all *.sh files in the migrations/ directory lexicographically by filename. It then compares these against completion markers stored in $XDG_STATE_HOME/omarchy/migrations/. Only scripts lacking marker files are executed, ensuring each migration runs exactly once.

Can I check for pending migrations without executing them?

Yes. Run omarchy-migrate --pending to list all migration scripts that have not yet been applied to the system. This displays the numeric identifiers without triggering execution, allowing administrators to review pending changes.

What happens if a migration script requires administrator privileges?

If a script encounters a privileged operation, it should print an informative message to stderr (as seen in migrations/1788124236.sh) and exit. The omarchy-migrate-notify systemd service will then prompt the user to re-run omarchy-migrate from an interactive terminal where they can provide credentials.

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