Where Are Omarchy Migration Completion Markers Stored? A Complete Guide

Omarchy stores migration completion markers as empty files in /var/lib/omarchy/migrations/, using each migration's numeric identifier as the filename, with optional environment variable overrides for custom paths.

Omarchy is an open-source system configuration framework that applies incremental updates through numbered shell scripts. Understanding where Omarchy migration completion markers are stored is essential for troubleshooting stuck migrations, testing changes, or manually resetting system state.

Default Storage Location and Naming Convention

By default, Omarchy writes all completion markers to the system-wide data directory /var/lib/omarchy/migrations/. Each marker is an empty file whose name matches the migration's numeric identifier.

When a migration completes successfully, the framework creates or touches this file. The mere existence of the file signals to the Omarchy runtime that the migration has already been applied, preventing re-execution on subsequent runs.

How Migration Scripts Define Markers

Each migration script in the migrations/ directory defines a variable named machine_marker (or a similarly descriptive name) that specifies the completion marker path. The pattern consistently uses environment variable expansion with a fallback to the default directory.

In migrations/1787815267.sh, the CUPS migration defines its marker as:

machine_marker="${OMARCHY_CUPS_MIGRATION_MARKER:-/var/lib/omarchy/migrations/1787815267}"

Similarly, migrations/1788009111.sh for the CUPS browsed removal uses:

machine_marker="${OMARCHY_CUPS_BROWSED_REMOVAL_MARKER:-/var/lib/omarchy/migrations/1788009111}"

This pattern repeats across the codebase. For example, migrations/1786380259.sh uses OMARCHY_BLUETOOTH_MIGRATION_MARKER, while migrations/1786605598.sh references OMARCHY_KMS_REBUILD_MARKER.

Overriding Marker Paths with Environment Variables

You can override the default storage location for any specific migration by setting its corresponding environment variable before execution. If the variable is present, Omarchy uses the custom path; otherwise, it falls back to /var/lib/omarchy/migrations/{ID}.

This flexibility allows testing migrations in isolated environments or storing markers on separate partitions.

Checking and Managing Markers Manually

Verifying Migration Status

To check whether a specific migration has already run, test for the existence of its marker file:

MIG_ID=1787815267
MARKER="/var/lib/omarchy/migrations/${MIG_ID}"
if [[ -e "$MARKER" ]]; then
    echo "Migration $MIG_ID already completed."
else
    echo "Running migration $MIG_ID..."
    # …run migration logic…

    touch "$MARKER"
fi

Customizing Marker Locations

To redirect a specific migration marker to a custom path:

export OMARCHY_CUPS_MIGRATION_MARKER="/tmp/omarchy/migrations/1787815267"

# The migration will now use /tmp instead of /var/lib/omarchy/…

Removing Stale Markers

During testing or recovery, you can force a migration to re-run by deleting its marker:

rm -f /var/lib/omarchy/migrations/1787815267

Summary

• Omarchy migration completion markers reside in /var/lib/omarchy/migrations/ by default.
• Each marker filename matches its migration's numeric ID (e.g., 1787815267).
• Migration scripts define paths via variables like machine_marker with environment variable fallbacks.
• Override paths using specific environment variables (e.g., OMARCHY_CUPS_MIGRATION_MARKER).
• Manual deletion of marker files forces migrations to re-execute on the next run.

Frequently Asked Questions

What happens if I delete a migration marker file?

Deleting a marker file removes the completion signal. On the next Omarchy run, the framework will detect the missing file and re-execute the corresponding migration script, reapplying any changes defined in that migration.

Can I change the default migrations directory for all markers?

There is no global configuration for the default directory in the current implementation. You must override each migration individually using its specific environment variable (e.g., OMARCHY_CUPS_MIGRATION_MARKER, OMARCHY_BLUETOOTH_MIGRATION_MARKER).

How do I find which migration ID corresponds to a specific change?

Examine the filenames in the migrations/ directory of the Omarchy repository. Each script is prefixed with a Unix timestamp or sequential numeric identifier. Reading the script contents reveals the specific system changes implemented by that migration.

Why does Omarchy use empty files instead of a database?

Empty files provide a simple, portable, and filesystem-native mechanism for tracking state. This approach requires no external dependencies, works across different Linux distributions, and allows administrators to easily inspect and manipulate migration status using standard shell commands like ls, test, and rm.

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