How Omarchy Seeds New User Environments Using `/etc/skel`

Omarchy uses the standard Unix skeleton directory mechanism via /etc/skel to populate new user home directories with default dotfiles, configurations, and theme assets when accounts are created.

The Omarchy desktop environment implements a three-phase provisioning model that starts with static file seeding through /etc/skel. This approach ensures every new user begins with a consistent, preconfigured environment derived directly from the omarchy-settings package.

The Three-Phase User Provisioning Model

Omarchy divides environment setup into distinct phases: Seed, Finalize, and Resync. Each phase addresses different constraints in Unix user management.

Phase	Purpose	Trigger
Seed	Copy static defaults into new home directories	User creation via useradd -m
Finalize	Execute runtime-dependent configuration	First user login
Resync	Restore original defaults for existing users	Manual invocation

Only the Seed phase modifies /etc/skel directly. The other phases operate after the initial home directory exists.

How the Seed Phase Works in /etc/skel

The omarchy-settings package installs a complete file tree under /etc/skel/ based on a build-time mapping defined in docs/file-layout.md. When Arch Linux's useradd runs with the -m (create home) flag, it automatically copies this entire tree to the new user's $HOME.

Key mappings from the Omarchy source:

• config/** → /etc/skel/.config/** — default application configurations
• applications/*.desktop → /etc/skel/.local/share/applications/ — desktop entry files
• default/bashrc → /etc/skel/.bashrc — baseline shell initialization

This implementation lives in the Omarchy repository at basecamp/omarchy, specifically documented in the Seed section of file-layout.md.

Creating a New User

The system installer and administrative tools use standard Linux commands:

sudo useradd -m alice

After execution, /home/alice contains the exact file tree from /etc/skel/, including all dotfiles and directory structures shipped by omarchy-settings.

The Finalize Phase: What /etc/skel Cannot Do

Static files in /etc/skel cannot handle dynamic content: path expansion, hardware detection, or user-specific symlinks. Omarchy addresses this with omarchy-provision-user, which runs automatically on first login.

This script, located at bin/omarchy-provision-user in the repository, performs actions such as:

• Expanding $OMARCHY_PATH variables in configuration files
• Creating skill-based symlinks that depend on installed packages
• Setting MIME type associations based on available applications

Separate from the initial seed, Finalize ensures the environment adapts to actual runtime conditions without polluting /etc/skel with template variables.

The Resync Phase: Restoring Defaults for Existing Users

Because /etc/skel is only consulted at account creation, existing users do not automatically receive updated defaults when omarchy-settings changes. The omarchy-reinstall-configs command provides an explicit reset mechanism.

From bin/omarchy-reinstall-configs (lines 14-20):

#!/bin/bash

# Force-reinstall all skel defaults, overwriting current user configs

cp -af /etc/skel/. ~/

Run this as the target user:

omarchy-reinstall-configs

This destructively restores the original seed state, useful for troubleshooting or adopting breaking configuration changes.

Key Source Files and Their Roles

File Path	Responsibility
docs/file-layout.md	Documents the three-phase model and build-time file mappings
bin/omarchy-reinstall-configs	Implements resync via cp -af /etc/skel/. ~/
bin/omarchy-provision-user	Performs per-user finalization after skel copy
default/bashrc	Source for /etc/skel/.bashrc
config/**	Default user configurations installed under /etc/skel/.config

Design Implications of the /etc/skel Approach

Omarchy's reliance on standard Unix mechanisms provides several advantages:

• Predictability: New users receive identical starting states regardless of installation timing
• Tool compatibility: Works with any user creation tool that respects useradd conventions
• Clear upgrade path: Separates immutable defaults (skel) from mutable user data
• Explicit reset: The resync command makes configuration recovery intentional rather than automatic

The trade-off is that existing users must consciously opt into configuration updates via omarchy-reinstall-configs, preventing unexpected disruption of customized environments.

Summary

• /etc/skel in Omarchy contains the complete default user environment shipped by omarchy-settings
• New users receive these files automatically via useradd -m during account creation
• omarchy-provision-user handles dynamic configuration that static files cannot express
• omarchy-reinstall-configs allows existing users to restore original defaults when needed
• The build-time mapping in docs/file-layout.md explicitly defines which source files populate /etc/skel

Frequently Asked Questions

What files does Omarchy put in /etc/skel?

The omarchy-settings package installs dotfiles, XDG configuration directories, desktop application entries, and theme assets. Specific mappings include config/** to .config/, applications/*.desktop to .local/share/applications/, and default/bashrc to .bashrc. The complete list is documented in docs/file-layout.md.

Why doesn't /etc/skel update existing user homes?

The Unix useradd mechanism only copies /etc/skel at account creation time. This is by design: modifying existing home directories would destroy user customizations. Omarchy respects this boundary and provides omarchy-reinstall-configs as an explicit, user-initiated reset path.

What happens if I run omarchy-reinstall-configs?

The command executes cp -af /etc/skel/. ~/ which forcibly overwrites all files in your home directory with the current contents of /etc/skel. This destroys any personal modifications to files that exist in the skeleton tree. Run it only when you intend to restore factory defaults.

How does Omarchy handle machine-specific configuration that /etc/skel cannot contain?

The omarchy-provision-user script runs once per user on first login to handle dynamic elements: expanding environment variables, detecting hardware capabilities, and creating conditional symlinks. This separates static templates from runtime-adaptive configuration.

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