How Omarchy Manages Version and Release Channels

Omarchy determines its version and release channel at runtime through three Bash utilities that inspect Pacman package state, parse mirrorlist comments, and detect Git metadata for development checkouts.

The Omarchy framework—maintained by omacom/omarchy—implements a dynamic approach to version and release channel management that distinguishes between stable package installations and active development checkouts. Rather than hardcoding version strings, the system queries the underlying package manager (pacman) or Git repository state to generate accurate version reports. This design supports four distinct release channels—stable, rc, edge, and dev—while providing seamless fallback mechanisms when metadata is unavailable.

Version Detection Architecture

The bin/omarchy-version script serves as the primary interface for version reporting, implementing a hierarchical detection strategy that prioritizes package manager data over Git metadata.

Package-Based Resolution

When Omarchy is installed via Pacman, the script queries the package database to extract the installed version string. The implementation first attempts to locate the production package omarchy, followed by the development package omarchy-dev.

# From bin/omarchy-version

if pacman -Q omarchy >/dev/null 2>&1; then
    pacman -Q omarchy | awk '{print $2}'
    exit 0
fi

if pacman -Q omarchy-dev >/dev/null 2>&1; then
    pacman -Q omarchy-dev | awk '{print $2}'
    exit 0
fi

This approach returns canonical version strings such as 4.0.0-1 that align with Pacman’s package versioning schema.

Development Checkout Fallback

If no package is found, the script assumes a dev-linked checkout and queries the local Git repository for the current commit hash. This mechanism enables developers to identify exact code states without package overhead.

# From bin/omarchy-version

if [[ -d ".git" ]]; then
    hash=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
    echo "dev ($hash)"
    exit 0
fi

The output format dev (a1b2c3d) clearly distinguishes development builds from stable releases.

Release Channel Management

Channel identification operates separately from version detection through bin/omarchy-version-channel, which implements a dual-strategy approach combining mirrorlist inspection with package name heuristics.

Mirrorlist Inspection Method

The primary detection mechanism reads the Pacman mirrorlist generated by omarchy-update-pacman-guard, searching for embedded channel metadata. The script parses the output of pacman -Sy --print-format "%M" to locate comment lines indicating the active channel.

# From bin/omarchy-version-channel

mirrorlist=$(pacman -Sy --print-format "%M" 2>/dev/null || true)
if [[ -n "$mirrorlist" ]]; then
    channel=$(grep -E '^#\s*Channel:' <<<"$mirrorlist" | head -n1 | cut -d':' -f2 | tr -d '[:space:]')
    if [[ -n "$channel" ]]; then
        echo "$channel"
        exit 0
    fi
fi

This method detects channels such as stable, rc, edge, or dev based on the # Channel: <name> comment embedded in the mirrorlist configuration.

Package-Based Channel Fallback

When mirrorlist inspection fails, the script falls back to examining available package repositories. If the omarchy package is present, the system reports stable; if omarchy-dev is detected, it reports dev.

# From bin/omarchy-version-channel

if pacman -Ss "^omarchy$" >/dev/null 2>&1; then
    echo "stable"
    exit 0
fi

if pacman -Ss "^omarchy-dev$" >/dev/null 2>&1; then
    echo "dev"
    exit 0
fi

If neither method succeeds, the script returns unknown, ensuring the system degrades gracefully rather than reporting incorrect channel data.

Development Workflow Utilities

For developers working with linked checkouts, bin/omarchy-version-branch provides Git branch identification independent of the version string. This utility checks for the presence of a .git directory before attempting to parse branch information.

# From bin/omarchy-version-branch

if [[ -d ".git" ]]; then
    git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown"
else
    echo "unknown"
fi

This script enables automated workflows to distinguish between feature branches, main, or other development lines without parsing the full version output.

Practical Usage Examples

Query your current Omarchy installation using these standard commands:

# Display installed version (package or dev checkout)

$ omarchy-version
4.0.0-1

# Or for development checkouts:

$ omarchy-version
dev (a1b2c3d)

# Identify active release channel

$ omarchy-version-channel
stable

# Check current Git branch (dev checkouts only)

$ omarchy-version-branch
main

These utilities execute with set -euo pipefail for strict error handling, ensuring reliable operation in both interactive shells and automated deployment scripts.

Summary

• Version detection in bin/omarchy-version prioritizes Pacman package queries (omarchy or omarchy-dev) before falling back to Git commit hashes for development environments.
• Channel management via bin/omarchy-version-channel parses mirrorlist comments for precise channel identification, with package-name heuristics as a backup strategy.
• Supported release channels include stable, rc, edge, and dev, with unknown returned when detection fails.
• Branch detection in bin/omarchy-version-branch supports development workflows by exposing Git branch names for linked checkouts.
• All scripts implement strict Bash error handling (set -euo pipefail) and return machine-readable output suitable for scripting and status monitoring.

Frequently Asked Questions

How does Omarchy determine which release channel is active?

Omarchy checks the Pacman mirrorlist for a comment line formatted as # Channel: <name>, which is generated by the omarchy-update-pacman-guard utility. If this metadata is unavailable, the system falls back to checking which package repository is enabled—returning stable for the omarchy package and dev for omarchy-dev.

What is the difference between package-based and development checkout versioning?

Package-based installations report semantic version strings (e.g., 4.0.0-1) extracted via pacman -Q, while development checkouts report dev (<hash>) where <hash> represents the short Git commit hash from git rev-parse --short HEAD. This distinction allows administrators to immediately identify whether a system is running a released build or a development snapshot.

How does the version script handle missing Git repositories?

If bin/omarchy-version finds no installed package and no .git directory, it outputs unknown and exits with status 0. This ensures the utility remains non-breaking in containerized or minimal environments where neither packages nor source control are present.

What channels are supported in Omarchy's release system?

The system recognizes four primary channels: stable (production releases), rc (release candidates), edge (bleeding-edge updates), and dev (development checkouts). The detection logic in bin/omarchy-version-channel is extensible, returning any channel name found in the mirrorlist configuration while maintaining hardcoded fallbacks for stable and dev package repositories.

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