How omarchy update Works in Omarchy: A Deep Dive into the System Update Orchestrator

The omarchy update command is a Bash orchestration script that executes a 14-step pipeline to safely upgrade both Omarchy and the underlying Arch Linux system, utilizing file-based locking, automatic conflict resolution, and modular helper binaries to ensure reliable, unattended-capable system maintenance.

The omarchy update command serves as the central maintenance interface for the Omarchy desktop environment. Implemented in the omacom/omarchy repository as a modular Bash architecture, this command coordinates complex system-wide updates while ensuring data safety through snapshots, preventing concurrent executions via file locking, and handling package manager conflicts automatically.

The Core Architecture of omarchy update

The main orchestrator resides in bin/omarchy-update, which coordinates a series of specialized helper scripts located in the bin/ directory. This modular design isolates distinct concerns—such as locking, logging, and package management—into separate executables, making the system easier to maintain and test. The command is also integrated into the Omarchy menu system via default/omarchy/omarchy-menu.jsonc, which launches the update in a floating terminal using omarchy-launch-floating-terminal-with-presentation omarchy-update.

Step-by-Step Execution Flow

The update process follows a strict sequence designed to maximize safety and recoverability.

1. Concurrency Control via File Locking

Before performing any operations, the script invokes omarchy-update-lock to acquire a file-based lock using flock -n (non-blocking). This guarantees that only one update process runs at a time, preventing race conditions with package manager operations. If the lock is already held, the helper re-executes the command within the lock context.

2. Logging and Restart-Safe Execution

The first invocation re-executes under the script command to capture a complete log at /tmp/omarchy-update.log. The script checks for the OMARCHY_UPDATE_LOGGED environment variable (lines 10-13 of bin/omarchy-update) to skip recursive logging on subsequent runs. This ensures a full audit trail even if the process later execs another binary.

3. Pre-Update Validation

The pipeline verifies system readiness through two checks:

• Disk space: omarchy-update-requires-free-space aborts early if insufficient free space exists.
• Interactive confirmation: Unless the -y flag is passed, omarchy-update-confirm prompts the user via gum. The -y flag sets OMARCHY_UPDATE_UNATTENDED=1, enabling fully automated operation.

4. System Preparation

Before modifying system packages, the script prepares the environment:

• Cache pruning: omarchy-update-pkg-prune runs paccache -rk2 to retain only the two most recent versions of each package, freeing disk space.
• Snapshot creation: omarchy-snapshot create generates a system snapshot if Snapper is available; if missing, the update proceeds without error.
• Suspend prevention: omarchy-update-stay-awake start activates a systemd inhibitor to block suspend or hibernate during the update process.

5. Core Package Updates

The actual upgrade happens in several phases:

• Development tools: omarchy-update-dev updates internal development utilities.
• Pacman keyring: omarchy-update-keyring refreshes the package manager's keyring.
• System packages: omarchy-update-system-pkgs executes pacman -Syu --noconfirm with an overwrite rule for /usr/share/omarchy/*.
• Conflict resolution: If pacman reports file conflicts, omarchy-update-system-pkgs-when-conflicted automatically removes the offending files and retries, eliminating manual intervention.

6. Post-Update Processing

After system packages upgrade, the script applies configuration changes and cleans up:

• Migrations: omarchy-migrate applies pending database or configuration migrations.
• Hooks: omarchy-hook post-update executes user-defined post-update scripts.
• AUR packages: omarchy-update-aur-pkgs updates packages from the Arch User Repository.
• Mise tools: omarchy-update-mise updates tools managed by the mise version manager.
• Orphan cleanup: omarchy-update-orphan-pkgs detects and optionally removes packages with no remaining dependents.

7. Finalization and Reboot

The final phase handles reporting and system restart:

• Log analysis: omarchy-update-analyze-logs parses /tmp/omarchy-update.log for errors.
• Status reporting: omarchy-update-status prints a concise summary of the update outcome.
• Reboot prompt: omarchy-update-restart releases the stay-awake inhibitor and offers a system reboot or user session restart.

Key Design Patterns and Safety Mechanisms

Several architectural decisions ensure omarchy update remains robust across diverse system states:

• File-based locking: The flock -n implementation in omarchy-update-lock guarantees atomic lock acquisition, preventing corruption from overlapping package operations.
• Idempotent logging: The outer script wrapper ensures log capture persists across exec calls, providing complete forensic data even if the main script is replaced mid-execution.
• Pacman conflict resolution: The omarchy-update-system-pkgs-when-conflicted helper detects when pacman cannot overwrite Omarchy-owned files and automatically clears the obstruction before retrying.
• Modular architecture: Each distinct task (pruning, snapshots, stay-awake) lives in its own binary, simplifying unit testing and debugging.

Usage Examples

# Standard interactive update with confirmation prompt

omarchy update

# Fully unattended update for automation or scripts

omarchy update -y

# Force snapshot creation even if Snapper is missing

OMARCHY_SNAPSHOT_FORCE=1 omarchy update

# Run a custom command within the update lock context

omarchy-update-lock run my-custom-script.sh

Summary

• The omarchy update command in omacom/omarchy orchestrates a 14-step Bash pipeline for system maintenance.
• File-based locking via omarchy-update-lock prevents concurrent update attempts using flock -n.
• Restart-safe logging captures all output to /tmp/omarchy-update.log using the script command.
• The -y flag enables unattended mode by setting OMARCHY_UPDATE_UNATTENDED=1 and bypassing the gum confirmation UI.
• Automatic conflict resolution in omarchy-update-system-pkgs-when-conflicted handles pacman file ownership issues without manual intervention.
• The process includes safety checks for disk space, optional Snapper snapshots, and a systemd stay-awake inhibitor to prevent suspend during critical operations.

Frequently Asked Questions

What happens if I run omarchy update while another update is in progress?

The omarchy-update-lock helper prevents concurrent executions by using flock -n (non-blocking) on a file descriptor. If the lock is already held, the command re-executes through the lock helper, ensuring only one update process runs at a time and preventing race conditions with package manager operations.

How does omarchy update handle pacman file conflicts?

When pacman -Syu encounters files in /usr/share/omarchy/* that it cannot overwrite, the omarchy-update-system-pkgs-when-conflicted helper automatically removes the offending files and retries the operation. This avoids manual intervention during system updates while preserving Omarchy's custom configurations.

Can omarchy update run unattended in scripts?

Yes. Passing the -y flag sets OMARCHY_UPDATE_UNATTENDED=1, which bypasses the interactive gum confirmation prompt in omarchy-update-confirm. This enables fully automated updates suitable for provisioning scripts or scheduled maintenance windows.

Where are omarchy update logs stored?

The outermost script execution captures all output to /tmp/omarchy-update.log using the script command. Subsequent invocations check for the OMARCHY_UPDATE_LOGGED environment variable to avoid recursive logging. After completion, omarchy-update-analyze-logs parses this file for errors and omarchy-update-status displays the final results.

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