Omarchy File Layout Convention: Repository Structure and System Mapping

The Omarchy file layout convention organizes the repository into three logical layers—runtime binaries, pre-install configuration seeds, and repository-only assets—that map directly to the omarchy and omarchy-settings Arch packages and their final system paths.

The Omarchy project by Basecamp maintains a strict file layout convention that determines how source directories transform into system paths on Arch Linux. This architecture separates runtime executables from skeleton configuration templates and documentation, ensuring reproducible installs across the two distinct packages produced by the repository.

Three-Layer Repository Architecture

The repository structure follows a high-level mental model documented in docs/file-layout.md. These layers correspond to distinct installation phases and package boundaries.

Runtime Layer (omarchy Package)

The omarchy package contains active binaries and runtime resources installed after the base system exists. Key directories include:

• bin/ – Executable scripts installed to /usr/bin/omarchy-*
• install/ – System installation scripts copied to /usr/share/omarchy/install/
• migrations/ – Per-user migration scripts run by omarchy-migrate, installed to /usr/share/omarchy/migrations/
• themes/ – Built-in desktop themes deployed to /usr/share/omarchy/themes/
• shell/ – Quickshell desktop configuration installed to /usr/share/omarchy/shell/

Pre-Install Layer (omarchy-settings Package)

The omarchy-settings package provides files that must exist before the main omarchy package installs. These directories seed the user environment and system defaults:

• config/ – User configuration templates installed to /etc/skel/.config/, copied to new user $HOME directories via useradd -m
• etc/ – System-wide configuration drop-ins installed to /etc/
• default/ – Runtime assets and overrides installed to /usr/share/omarchy/default/

Repository-Only Assets

Files that never ship in either package include documentation, contributor guides, and test suites:

• manual/ – End-user documentation
• docs/ – Architecture documentation including the file layout specification
• test/, plans/, agents/skills/ – Development and planning artifacts

Three-Stage User Home Population

Omarchy populates user home directories through a deliberate multi-stage process documented in docs/file-layout.md (lines 35-44).

1. Seed Stage

The omarchy-settings package ships static defaults into /etc/skel/. When administrators create users with useradd -m, the standard Unix mechanism copies this tree into the new $HOME directory.

2. Finalize Stage

The omarchy-provision-user command runs once per user to complete setup. This script creates symlinks, executes xdg-user-dirs-update, applies runtime-only defaults, and installs per-user systemd units that persist across sessions.

3. Resync Stage

When users explicitly request a configuration reset, omarchy-reinstall-configs deliberately overwrites the existing $HOME with shipped defaults. This executes cp -af /etc/skel/. $HOME to restore the pristine state:

# Re-apply shipped defaults to an existing user

omarchy-reinstall-configs

Build-Time Path Transformation

During package construction, repository directories map to specific installation targets. The detailed mapping appears in the source file at lines 64-84 of docs/file-layout.md:

Repository Path              Installed Path
─────────────────────────────────────────────────────────
bin/omarchy-*               → /usr/bin/omarchy-*
install/**                  → /usr/share/omarchy/install/
migrations/**               → /usr/share/omarchy/migrations/
themes/**                   → /usr/share/omarchy/themes/
shell/**                    → /usr/share/omarchy/shell/
config/**                   → /etc/skel/.config/**
etc/**                      → /etc/**
default/**                  → /usr/share/omarchy/default/

Verify binary placement matches this mapping:

# Confirm runtime binaries install to the correct location

ls /usr/bin/omarchy-*

Handling Protected Configuration Files

Some /etc/ files such as bashrc and nsswitch.conf are owned by upstream Arch packages. Omarchy cannot replace these directly during package installation, so the repository uses an etc-overrides/ mechanism documented at lines 42-53 of the file layout specification.

Sources live under etc/ in the repository but install to /usr/share/omarchy/etc-overrides/. A post-install scriptlet then forcibly copies them into place using cp -f. This ensures upgrades always bring the latest defaults, though it overwrites any user edits made to those specific files.

Runtime Environment Bootstrap

All entry points source default/bash/env-bootstrap to establish consistent environment variables. This script sets OMARCHY_PATH, prepends $OMARCHY_PATH/bin to PATH when necessary, and adds user-specific shim directories. System login shells, user .bashrc, the uwsm session launcher, and SSH entry points all source this bootstrap file according to the implementation in lines 55-71 of the file layout documentation.

Inspect the top-level repository structure to understand these categories:

# Display the major directory categories

tree -L 2 .

Expected output includes bin/ for runtime binaries, config/ for user seeds, default/ for system overrides, docs/ for architecture documentation, and manual/ for end-user guides.

Summary

• The Omarchy repository organizes code into three layers: runtime (bin/, shell/), pre-install (config/, etc/), and repository-only (manual/, docs/)
• Two Arch packages emerge from this structure: omarchy (runtime) and omarchy-settings (configuration seeds)
• User homes populate in three stages: seed via /etc/skel/, finalize via omarchy-provision-user, and resync via omarchy-reinstall-configs
• Build-time mapping transforms repository paths like bin/ and config/ into system paths under /usr/bin/ and /etc/skel/ respectively
• The etc-overrides/ mechanism handles protected files by installing to /usr/share/omarchy/etc-overrides/ and copying into /etc/ post-install

Frequently Asked Questions

What is the difference between the omarchy and omarchy-settings packages?

The omarchy package contains runtime binaries, themes, and the Quickshell desktop installed to /usr/bin/ and /usr/share/omarchy/. The omarchy-settings package contains files that must exist before omarchy installs, including /etc/skel/ templates and system configuration drop-ins. This separation allows the base configuration to exist before the runtime system activates.

How does Omarchy handle user home directory initialization?

Omarchy uses a three-stage process documented in docs/file-layout.md. First, the seed stage copies static files from /etc/skel/ during user creation via useradd -m. Second, the finalize stage runs omarchy-provision-user to create symlinks and systemd units. Third, the resync stage via omarchy-reinstall-configs can overwrite an existing home with shipped defaults when requested.

Why does Omarchy use an etc-overrides/ directory instead of writing directly to /etc?

Certain files in /etc/ such as bashrc and nsswitch.conf are owned by upstream Arch packages. Omarchy cannot overwrite these directly during package installation without conflicts. Instead, these files install to /usr/share/omarchy/etc-overrides/ and a post-install scriptlet copies them into /etc/ using cp -f, ensuring the system receives updates while respecting package manager ownership rules.

Where can I find the canonical documentation for the file layout?

The complete file layout specification lives in docs/file-layout.md in the repository root. This document details the mapping between repository directories and installed system paths (lines 64-84), explains the three-stage user home population process (lines 35-44), and describes the etc-overrides mechanism for handling protected configuration files (lines 42-53).

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