How to Check for Pending Migrations in Omarchy

Use omarchy-migrate --pending to list incomplete migrations by scanning for shell scripts in the migrations/ directory that lack corresponding marker files in ~/.local/state/omarchy/done/.

Omarchy handles system configuration changes through versioned migration scripts stored in the basecamp/omarchy repository. When you need to check for pending migrations in Omarchy, the migration runner inspects which scripts have already been executed by looking for completion markers, allowing you to audit system state before applying changes.

How the Migration Tracking System Works

Omarchy stores migration scripts as individual shell files in the migrations/ directory. Each script receives a numeric prefix (e.g., 100-first.sh, 200-second.sh) to determine execution order. When a migration runs successfully, the omarchy-migrate runner creates a corresponding marker file in ~/.local/state/omarchy/done/ with the naming pattern {migration-name}.sh.done.

The migration runner (bin/omarchy-migrate) determines pending status by comparing the list of scripts in migrations/ against the markers in the done directory. Any script without a marker is considered pending.

Checking for Pending Migrations with --pending

The omarchy-migrate command provides a dedicated flag for auditing migration state without executing changes.

Listing Pending Migrations

To view a human-readable list of pending migrations:

omarchy-migrate --pending

This command outputs the filenames of migrations lacking completion markers:

100-first.sh
200-second.sh

The runner exits with a non-zero status if any pending migrations exist, making it suitable for conditional scripting.

Scripting with Exit Codes

You can integrate the pending check into automation scripts using the exit status:

if omarchy-migrate --pending >/dev/null; then
    echo "All migrations are up-to-date."
else
    echo "There are pending migrations – run them now."
    omarchy-migrate   # executes all pending migrations

fi

This pattern allows shell scripts to detect drift between the desired configuration state and the current system state before proceeding with other operations.

Automatic Desktop Notifications

When you invoke omarchy-migrate --pending and incomplete migrations exist, the runner automatically triggers a desktop notification via omarchy-notification-send. According to the test suite in test/shell.d/migrate-notify-test.sh, the notification displays:

• Title: "Pending Omarchy Migrations"
• Body: The list of pending migration filenames

This integration ensures users receive visual alerts when system updates require attention.

Key File Locations

Understanding where Omarchy stores migration artifacts helps with troubleshooting and manual verification.

Component	Path	Purpose
Migration scripts	migrations/	Source shell scripts (e.g., 100-setup.sh) that perform system changes
Completion markers	~/.local/state/omarchy/done/	Marker files (e.g., 100-setup.sh.done) indicating successful execution
Migration runner	bin/omarchy-migrate	Executable that scans, reports, and executes pending migrations
Notification helper	bin/omarchy-notification-send	Utility invoked by the runner to display desktop alerts

Testing Pending Migration Detection

The Omarchy test suite validates the pending migration workflow through dedicated test scripts. The file test/shell.d/migrate-notify-test.sh verifies that the notification system correctly identifies pending migrations and formats the alert with the proper title and filename list. Additionally, test/shell.d/migrate-wrapper-test.sh ensures that omarchy-migrate --pending accurately lists pending items and remains silent when all migrations are current.

Summary

• Check for pending migrations by running omarchy-migrate --pending, which scans the migrations/ directory and compares it against completion markers in ~/.local/state/omarchy/done/.
• The command exits with non-zero status when migrations are pending, enabling reliable scripting and conditional logic.
• Desktop notifications trigger automatically when pending migrations are detected, alerting users via the system notification daemon.
• Migration scripts follow a numeric prefix convention (e.g., 100-, 200-) to ensure deterministic execution order.
• The implementation resides in bin/omarchy-migrate with validation tests in test/shell.d/migrate-notify-test.sh and test/shell.d/migrate-wrapper-test.sh.

Frequently Asked Questions

How does Omarchy determine if a migration is pending?

Omarchy scans the migrations/ directory for all *.sh files sorted by numeric prefix, then checks for corresponding marker files in ~/.local/state/omarchy/done/. If a migration script lacks a .done marker file, the migration runner classifies it as pending. This state is exposed through the omarchy-migrate --pending command.

What exit code does omarchy-migrate --pending return?

The command returns a non-zero exit status when pending migrations exist and zero when the system is up-to-date. This behavior allows shell scripts to branch logic based on migration state using standard conditional operators.

Where are migration completion markers stored?

Completion markers reside in $HOME/.local/state/omarchy/done/ as empty files named after their corresponding migration scripts with a .done suffix appended. For example, completing migrations/100-first.sh creates ~/.local/state/omarchy/done/100-first.sh.done.

Does checking for pending migrations send a notification?

Yes. When omarchy-migrate --pending detects incomplete migrations, it automatically invokes omarchy-notification-send to display a desktop notification titled "Pending Omarchy Migrations" containing the list of pending filenames. This occurs according to the implementation in bin/omarchy-migrate and is verified by test/shell.d/migrate-notify-test.sh.

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