# How to Check for Pending Migrations in Omarchy

> Easily check for pending migrations in Omarchy using the omarchy-migrate --pending command. Discover incomplete migrations efficiently by scanning your project.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/basecamp/omarchy/blob/main/100-first.sh), [`200-second.sh`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/migrate-notify-test.sh) and [`test/shell.d/migrate-wrapper-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/migrate-notify-test.sh).