Idempotency Marker for omarchy-provision-user: File Location and Implementation Guide

The idempotency marker for omarchy-provision-user is the file ~/.local/state/omarchy/done/finalize-user, which prevents duplicate execution of user finalization steps unless the script is invoked with the --force flag.

The omarchy-provision-user script in the basecamp/omarchy repository implements idempotent per-user provisioning by tracking completion state through a marker file. This mechanism ensures that potentially destructive or time-consuming setup steps run exactly once per user account, making the script safe to execute repeatedly in automated workflows.

What Is the Idempotency Marker for omarchy-provision-user?

The marker is a zero-byte or timestamp file located at:

~/.local/state/omarchy/done/finalize-user

According to the source code at line 22 of bin/omarchy-provision-user, this file serves as a persistent flag indicating that user finalization has completed successfully. When present, the script exits early to avoid re-running configuration steps that might overwrite custom user settings or regenerate credentials unnecessarily.

How the Idempotency Check Works in bin/omarchy-provision-user

The script checks for the marker at startup using the omarchy-done helper utility. The logic explicitly tests for the marker and a non-forced execution state:

if omarchy-done check finalize-user && (( force == 0 )); then
    echo "User finalization already complete (rerun with --force to refresh)."
    exit 0
fi

omarchy-done check finalize-user returns a zero exit code if the marker file exists, causing the script to print a status message and terminate immediately. This check runs before any provisioning logic executes, guaranteeing that idempotency is enforced at the entry point.

Marking Completion with omarchy-done mark

After successfully completing all provisioning steps, the script creates the idempotency marker:

omarchy-done mark finalize-user

This command ensures that subsequent invocations of omarchy-provision-user will detect the existing state and skip to completion. The marker persists in the user's home directory under .local/state/, following the XDG Base Directory Specification for state data.

Bypassing the Marker with --force

Administrators can override the idempotency protection to re-provision a user or refresh configurations:

# Force re-provisioning regardless of marker status

omarchy-provision-user --force

When --force is supplied, the script sets force=1, which causes the conditional (( force == 0 )) to evaluate as false. This bypasses the early exit and executes the full provisioning routine, eventually rewriting the marker upon successful completion.

Key Files and Helper Utilities

The idempotency system relies on three components documented in the basecamp/omarchy repository:

• bin/omarchy-provision-user – The main provisioning script that defines the marker logic at line 22 and orchestrates the user setup workflow.

• bin/omarchy-done – A helper utility that abstracts marker file operations, providing check, mark, and directory-creation subcommands for state management.

• docs/file-layout.md – Documentation specifying the location and purpose of marker files within the ~/.local/state/omarchy/ directory hierarchy.

Summary

• The idempotency marker for omarchy-provision-user is the file ~/.local/state/omarchy/done/finalize-user.
• The script checks this marker via omarchy-done check finalize-user at line 22 of bin/omarchy-provision-user.
• If the marker exists and --force is not provided, the script exits immediately without performing work.
• Use omarchy-provision-user --force to ignore the marker and re-run all provisioning steps.

Frequently Asked Questions

What is the exact file path of the idempotency marker?

The marker file is located at ~/.local/state/omarchy/done/finalize-user. This path is hardcoded in bin/omarchy-provision-user and managed through the omarchy-done helper script.

How do I force omarchy-provision-user to run again?

Invoke the script with the --force flag: omarchy-provision-user --force. This overrides the idempotency check and executes all provisioning steps regardless of whether the marker file exists.

What is the omarchy-done utility?

omarchy-done is a helper program in the basecamp/omarchy repository that manages state markers. It provides subcommands like check to test for file existence and mark to create marker files, ensuring consistent state tracking across omarchy scripts.

Where is the state directory for these markers documented?

The file layout and state directory structure are documented in docs/file-layout.md within the omarchy repository. This file specifies that runtime state, including idempotency markers, belongs in ~/.local/state/omarchy/.

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