# How the Seed→Finalize→Resync Pattern Populates $HOME at Different Stages in Omarchy > Discover how the seed finalize resync pattern populates $HOME in Omarchy. Learn about skeleton files, runtime configs, and safe upgrades for your user data. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-09 --- **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`](https://github.com/omacom/omarchy/blob/main/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: ```bash # 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. ```bash # 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. ```bash # 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`](https://github.com/omacom/omarchy/blob/main/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.