How Omarchy Populates the User Home Directory: The Three-Layer System

Omarchy uses a three-layer process—Seed, Finalize, and Resync—to populate user home directories, combining static skeleton files, dynamic runtime provisioning, and destructive refresh capabilities.

Populating the user's home directory in Omarchy requires more than a simple copy operation. The basecamp/omarchy repository implements a structured three-stage approach that separates static defaults from dynamic configuration, ensuring new users receive consistent setups while allowing existing users to reset their environments safely.

The Three Layers of Home Directory Population

Omarchy’s architecture divides home directory setup into three distinct stages, each documented in docs/file-layout.md within lines 33-45.

1. Seed – Static Defaults via /etc/skel/

The Seed layer provides static defaults shipped in the omarchy-settings package. These files reside under /etc/skel/ and are copied automatically when creating a new user account. According to the documentation in docs/file-layout.md#L33-L38, this is the only stage that touches a brand-new user's files during account creation.

When you execute useradd with the -m flag, Arch Linux copies the entire /etc/skel/ tree into the fresh home directory:

# Seed happens automatically on user creation

sudo useradd -m alice   # copies /etc/skel/* into /home/alice

2. Finalize – Dynamic Per-User Provisioning

The Finalize layer handles items that cannot be pre-seeded because they require runtime expansion of variables like $HOME or $OMARCHY_PATH. As documented in docs/file-layout.md#L39-L42, this stage runs via the omarchy-provision-user command, exposed through the omarchy finalize user interface.

This script executes once per user to handle system state detection and path-specific configurations:

# Finalize – run once after first login or manually

omarchy finalize user   # internally calls omarchy-provision-user

The implementation in bin/omarchy-provision-user includes a safety check ensuring it runs as the target user rather than root:

# Inside bin/omarchy-provision-user

echo "Error: run omarchy-provision-user as the user being configured, not as root." >&2

3. Resync – Destructive Configuration Refresh

The Resync layer provides an explicit, destructive refresh mechanism for existing users who want to revert all customizations. As noted in docs/file-layout.md#L43-L45, the omarchy-reinstall-configs command clobbers current $HOME contents with the original configuration templates.

# Resync – reset an existing home to defaults (DESTRUCTIVE)

omarchy-reinstall-configs   # overwrites $HOME with shipped defaults

Key Implementation Files

Three primary files implement this stratified approach to populating the user's home directory:

• default/** → /etc/skel/ – Provides the static skeleton copied during account creation via the omarchy-settings package.
• bin/omarchy-provision-user – Executes dynamic per-user runtime setup with user-context validation, requiring execution as the target user.
• bin/omarchy-reinstall-configs – Handles the destructive overwrite of $HOME with shipped defaults.

Summary

• Seed uses /etc/skel/ static files copied automatically by useradd -m for new accounts.
• Finalize runs omarchy-provision-user once per user to handle dynamic $HOME expansion and runtime detection.
• Resync executes omarchy-reinstall-configs to destructively reset existing home directories to defaults.
• All three layers are documented in docs/file-layout.md within the basecamp/omarchy repository.

Frequently Asked Questions

What triggers the Seed layer in Omarchy?

The Seed layer triggers automatically when creating a new user account with the -m flag via useradd -m. Arch Linux copies the contents of /etc/skel/—populated by the omarchy-settings package—into the newly created home directory according to docs/file-layout.md#L33-L38.

Can I run omarchy-provision-user as root?

No. The script in bin/omarchy-provision-user explicitly checks its execution context and aborts if run as root, displaying an error message directing you to run it as the user being configured. This ensures proper file ownership and $HOME resolution.

Is omarchy-reinstall-configs safe to run?

No, it is destructive by design. This command overwrites existing files in your home directory with the default templates shipped in the Omarchy package. Use it only when you intend to reset all customizations and return to the shipped defaults.

Where are the three layers documented?

The three-layer system is documented in docs/file-layout.md at lines 33-45, which details the Seed (lines 33-38), Finalize (lines 39-42), and Resync (lines 43-45) stages and their respective responsibilities in populating the user's home directory.

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