How to Update Omarchy Plugins: A Complete Guide to Git-Managed Extensions

Omarchy plugins are updated via the omarchy plugin update command, which performs safe Git fast-forwards from ~/.config/omarchy/plugins while preserving local modifications and showing diffs for confirmation.

Omarchy, the extensible shell environment from Basecamp, manages plugins as Git repositories in ~/.config/omarchy/plugins. Understanding how to update Omarchy plugins ensures you receive the latest features and security patches without overwriting your custom configurations.

Understanding the Omarchy Plugin Update Architecture

The plugin update system is implemented in bin/omarchy-plugin-update, which orchestrates Git operations across your local plugin directories. Although the command is marked as hidden (# omarchy:hidden=true) in the GROUP_DESCRIPTIONS table—indicating it is designed for power users and scripts—it remains fully documented in the shell README and manual pages.

The system treats each plugin as an independent Git repository, allowing granular control over updates while maintaining safety guarantees that prevent accidental data loss.

The Six-Stage Update Process

When you run omarchy plugin update, the command executes a rigorous validation pipeline:

1. Plugin Discovery

The command enumerates all installed plugins by reading manifest.json files located in ~/.config/omarchy/plugins/*/. This discovery phase identifies which extensions are eligible for updates.

2. Fetching Upstream Changes

For each discovered plugin, the system executes git fetch to retrieve the latest commits from the upstream repository. If a fetch fails, the command reports the error immediately:

fetch failed for '<plugin-id>'

This error handling occurs at Line 44 of bin/omarchy-plugin-update, ensuring network or permission issues are surfaced before any local modifications occur.

3. Fast-Forward Validation

Before applying changes, the command verifies that the plugin can be fast-forwarded safely. If you have uncommitted local changes, the update aborts with a clear message:

cannot fast-forward '<plugin-id>'; you have local changes in /home/user/.config/omarchy/plugins/<plugin-id>

This safety check, implemented at Line 68, prevents the system from overwriting your customizations.

4. Diff Review and Confirmation

When fast-forwarding is possible, the command displays a diff between your current HEAD and the fetched upstream commits. You must explicitly confirm the update:

Apply this update? [y/N]

This interactive step ensures you review changes to files like Panel.qml or configuration scripts before they are applied.

5. Fast-Forward Execution

Upon confirmation, the plugin repository is fast-forwarded to the new commit. If post-update validation fails, the system automatically rolls back the changes and reports:

update of '<plugin-id>' failed validation; rolled back

This rollback mechanism, found at Line 74, protects against corrupted or incomplete updates.

6. Post-Update Reload

Once all plugins are processed, the Omarchy shell automatically reloads the updated extensions. New functionality appears immediately without requiring a session restart.

Running omarchy plugin update: Command Reference

The omarchy plugin update command supports several modes of operation:

Update all installed plugins interactively:

omarchy plugin update

Update a specific plugin by its identifier:

omarchy plugin update acme.weather

Run updates non-interactively (automatically applies after diff review):

omarchy plugin update --yes

Handling Conflicts and Local Modifications

The update process respects the same safety guarantees as the core Omarchy update pipeline. The system refuses to modify any plugin that would cause a merge conflict or overwrite local customizations without explicit confirmation.

If you encounter the "cannot fast-forward" error, you have two options:

1. Commit or stash your local changes using standard Git commands in the plugin directory, then re-run the update.
2. Clone the plugin manually to a different location if you intend to maintain a permanent fork.

Summary

• Omarchy plugins reside in ~/.config/omarchy/plugins as Git-managed repositories.
• The omarchy plugin update command automates fetching, diffing, and fast-forwarding from upstream sources.
• Safety checks at Line 44, Line 68, and Line 74 of bin/omarchy-plugin-update prevent data loss and handle network failures.
• Updates require explicit confirmation unless using the --yes flag, and local changes block automatic updates to prevent overwriting customizations.
• The shell automatically reloads plugins after updating, applying changes immediately.

Frequently Asked Questions

What happens if I have local changes in a plugin?

The update command aborts with the message cannot fast-forward '<id>'; you have local changes in $dir. You must commit, stash, or revert your local changes using standard Git operations in the plugin directory before the update can proceed.

Can I update Omarchy plugins automatically without prompts?

Yes. Append the --yes flag to omarchy plugin update to run non-interactively. The system will still fetch and diff changes, but will automatically confirm and apply updates. Use this flag with caution in automated scripts.

Where are Omarchy plugins stored locally?

All plugins are stored in ~/.config/omarchy/plugins/, with each plugin occupying its own subdirectory containing a manifest.json file and a full Git repository. This location is consistent across all Omarchy installations.

What should I do if an update fails validation?

If the post-update validation fails, the system automatically rolls back the plugin to its previous state and reports update of '<id>' failed validation; rolled back. Check the plugin's upstream repository for breaking changes or consult the plugin's documentation for migration steps before attempting the update again.

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