# How Omarchy Manages Version and Release Channels

> Discover how Omarchy manages version and release channels using Bash utilities that inspect Pacman package state, parse mirrorlist comments, and detect Git metadata for development checkouts.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-13

---

**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`.

```bash

# 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.

```bash

# 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.

```bash

# 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**.

```bash

# 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.

```bash

# 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:

```bash

# 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.