How the Seed→Finalize→Resync Pattern Populates $HOME at Different Stages in Omarchy

The seed→finalize→resync pattern in Omarchy populates $HOME by first copying skeleton files from /etc/skel, then applying runtime-only configurations like XDG directories and skill symlinks, and finally re-applying default configs during upgrades without overwriting user data.

This three-phase approach ensures that new user accounts receive a complete environment while preserving personal changes across Omarchy updates. The pattern separates static file provisioning from dynamic environment setup, allowing the system to evolve its defaults safely.

The Three-Stage Architecture

Omarchy implements a deliberate separation between initial file provisioning, runtime environment configuration, and post-upgrade maintenance. Each stage targets a specific lifecycle moment in the user home directory.

Stage 1: Seeding from /etc/skel

The seed phase establishes the baseline configuration tree in a fresh $HOME directory. During this phase, Omarchy copies the default configuration hierarchy from /etc/skel, including the entire config/ directory structure (mapped to .config/ in the user home) and other skeleton files required for a functional environment.

According to the repository documentation in docs/file-layout.md, this seeding occurs automatically during first-time user provisioning (e.g., after useradd -m). The skeleton directory contains static dotfiles and directory templates that can be safely stored in /etc/skel and copied verbatim.

Stage 2: Finalizing Runtime Configuration

The finalize phase handles setup steps that cannot be captured in static /etc/skel files. The bin/omarchy-finalize-user script performs runtime-only initialization including:

• Creating XDG user directories (xdg-user-dirs)
• Installing MIME type defaults
• Linking skill scripts into the environment
• Executing per-user install scripts located under install/user/

Critically, this stage does not overwrite existing files. It only augments the environment with calculated or dynamic content that depends on the specific runtime state. The finalize step runs automatically after seeding during first login, or can be invoked explicitly via the omarchy-finalize-user command.

Stage 3: Resyncing Defaults During Upgrades

The resync phase reconciles the user's home directory with updated default configurations after Omarchy upgrades. Implemented in bin/omarchy-reinstall-configs, this stage re-applies the skeleton files to an existing $HOME without destroying personal edits.

Resync is intentionally destructive only for the defaults it manages, leaving user-created content untouched. When Omarchy releases new default configurations, this command introduces them into existing homes safely. It runs explicitly when administrators trigger a configuration refresh following a system update.

How the Commands Orchestrate the Pattern

Three primary commands collaborate to implement this lifecycle, each corresponding to a specific operational need:

# 1. Seed and finalize a brand-new user (run automatically on first login)

omarchy-provision-user

The omarchy-provision-user command orchestrates the transition from empty home to fully configured environment. According to the source in bin/omarchy-provision-user, it first applies the seed step by copying /etc/skel contents, then immediately invokes the finalize step to establish runtime configurations.

# 2. Apply runtime-only configurations manually

omarchy-finalize-user

For scenarios requiring re-finalization without re-seeding, omarchy-finalize-user handles the skill symlinks, XDG directory creation, and MIME defaults installation independently.

# 3. Resync defaults after an Omarchy upgrade

omarchy-reinstall-configs

When the system requires updated default configs in existing homes, omarchy-reinstall-configs performs the explicit destructive resync of managed defaults while preserving user modifications.

Summary

• The seed phase copies static skeleton files from /etc/skel into $HOME during account creation, establishing the baseline configuration tree.
• The finalize phase in bin/omarchy-finalize-user creates runtime-only resources like XDG directories and skill symlinks without overwriting existing files.
• The resync phase via bin/omarchy-reinstall-configs introduces new default files during upgrades while protecting user-created content.
• bin/omarchy-provision-user automates the seed-to-finalize transition for new accounts.
• This pattern separates static provisioning from dynamic configuration, enabling safe updates across Omarchy releases.

Frequently Asked Questions

What happens if I run omarchy-reinstall-configs on a heavily customized home directory?

The resync command only overwrites files that belong to the managed default set originally seeded from /etc/skel. Your personal files, custom scripts, and user-created configurations remain untouched. The command is designed to be destructive only for Omarchy's own defaults, merging updates rather than resetting the entire environment.

Why does Omarchy separate seeding from finalization instead of doing everything at once?

Static files can reside in /etc/skel and copy efficiently during user creation, but certain configurations require runtime computation. XDG directories depend on user locale and mount points, skill symlinks must resolve to current installation paths, and per-user install scripts may need to detect hardware or network state. Separating these concerns allows bin/omarchy-finalize-user to execute context-aware setup while keeping /etc/skel contents static and version-controlled.

Where does Omarchy store the default templates used during the seed phase?

The default configuration tree lives in /etc/skel on Omarchy systems, as documented in docs/file-layout.md. This directory contains the config/ hierarchy and other dotfiles that omarchy-provision-user copies into $HOME during the seed phase. When resyncing, bin/omarchy-reinstall-configs references these same /etc/skel templates to determine which files constitute "managed defaults."

Can I skip the finalize step if my home directory already contains config files?

Skipping finalization is not recommended. While the seed phase provides static dotfiles, the finalize phase establishes essential runtime infrastructure including XDG user directories required by modern applications and MIME associations needed for file handling. bin/omarchy-finalize-user explicitly checks for existing files to avoid overwrites, making it safe to run even on partially configured homes.

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