# Omarchy File Layout Convention: Repository Structure and System Mapping

> Discover the Omarchy file layout convention. Learn how the repository structure maps to system paths for runtime binaries, configuration seeds, and assets. Understand the basecamp/omarchy organization.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: architecture
- Published: 2026-08-29

---

**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](https://github.com/basecamp/omarchy/blob/quattro/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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).