How `omarchy-reinstall-configs` Works with `/etc/skel` Seeding and Resync

omarchy-reinstall-configs resets all Omarchy user configurations to factory defaults by copying the contents of /etc/skel directly over the current user's home directory.

This Bash utility provides a single-command workflow to restore pristine configurations shipped with the basecamp/omarchy distribution. It leverages the standard Unix skeleton directory mechanism while adding Omarchy-specific post-processing for boot themes and editor setups.

How /etc/skel Seeds the User Environment

The /etc/skel directory serves as the template for all new user accounts on Linux systems. When useradd -m creates a home directory, it copies /etc/skel/ contents to the new user's $HOME. Omarchy extends this convention: instead of maintaining scattered configuration sources, the distribution stores its complete default user environment in /etc/skel as an authoritative snapshot.

This includes:

• Shell initialization files (.bashrc, .profile)
• Desktop environment configs (.config/hypr/, .config/waybar/)
• Application defaults and branding assets
• Migration markers and feature toggles

By treating /etc/skel as a read-only reference, omarchy-reinstall-configs achieves a true "factory reset" without tracking individual file changes.

The Five-Step Resync Workflow

The script at bin/omarchy-reinstall-configs executes a predictable sequence to ensure safe, complete restoration.

1. Root Safety Check

if (( EUID == 0 )); then
  echo "ERROR: Do not run as root" >&2
  exit 1
fi

Running as root would copy files into /root rather than the intended user account, so the script aborts immediately (lines 7-10).

2. Status Notification

echo "Resetting Omarchy user configs to shipped defaults..."

A clear progress message confirms the operation has started (line 12).

3. Core Copy Operation

cp -af /etc/skel/. ~/

This single command performs the bulk resync:

• -a (archive): Preserves permissions, timestamps, symlinks, and recursive structure
• -f (force): Overwrites existing files without prompting
• /. syntax: Ensures hidden files (dotfiles) are included in the copy

The trailing slash-dot pattern is critical—it copies the contents of /etc/skel/ rather than the directory itself, flattening the tree correctly into $HOME (lines 14-20).

4. System UI Refresh

omarchy-refresh-limine
omarchy-refresh-plymouth

After user files are restored, these helpers reinstall the Limine bootloader theme and Plymouth splash screen to ensure visual consistency with the reset configuration (lines 21-23).

5. Neovim Configuration Handling

if omarchy-cmd-present omarchy-nvim-refresh; then
  omarchy-nvim-refresh
else
  omarchy-nvim-setup --force
fi

The script adapts to available tooling: preferring the dedicated omarchy-nvim-refresh command when present, falling back to the legacy omarchy-nvim-setup --force otherwise (lines 24-28).

Practical Usage Examples

Basic Resync

# From a regular user shell

$ omarchy-reinstall-configs
Resetting Omarchy user configs to shipped defaults...

Verify Restoration

# Confirm a specific file matches the default

$ diff ~/.bashrc /etc/skel/.bashrc && echo "Restored to default"
Restored to default

Preview Changes (Dry Run)

# Simulate without actually overwriting anything

$ rsync -avn /etc/skel/. ~/

The -n flag enables dry-run mode, showing exactly which files would change.

Key Implementation Files

Path	Purpose
quattro/bin/omarchy-reinstall-configs	Main resync script
quattro/bin/omarchy-refresh-limine	Bootloader theme refresh
quattro/bin/omarchy-refresh-plymouth	Splash screen refresh
quattro/bin/omarchy-nvim-refresh	Preferred Neovim reset
quattro/bin/omarchy-nvim-setup	Legacy Neovim installer

All paths are relative to the Omarchy repository root at basecamp/omarchy.

Why This Approach Outperforms Alternatives

rsync-based delta syncs would require complex exclude lists and state tracking. Package-manager reinstalls lack awareness of runtime-generated configs. The /etc/skel overlay method provides:

• Atomic single-source truth: One directory contains all defaults
• No configuration drift: Every reset pulls from the same snapshot
• Minimal dependencies: Only standard cp required for core operation
• Extensibility: Post-copy hooks (omarchy-refresh-*) handle system-level theming

According to the basecamp/omarchy source code, this design intentionally mirrors how fresh user accounts are created, ensuring that "reset" and "new user" experiences remain identical.

Summary

• omarchy-reinstall-configs performs a complete user configuration reset by overlaying /etc/skel onto $HOME
• The cp -af /etc/skel/. ~/ command preserves metadata while forcing overwrites of all user-modified files
• Post-copy hooks synchronize system-level theming (Limine, Plymouth) and editor configuration (Neovim)
• The script refuses root execution to prevent mis-targeted operations
• /etc/skel serves as Omarchy's single source of truth for default user environments

Frequently Asked Questions

What happens to my personal files and documents?

Only files present in /etc/skel are overwritten. Personal documents, downloads, and custom directories not shipped by Omarchy remain untouched. The copy operates as an overlay, not a wipe.

Can I run omarchy-reinstall-configs without overwriting certain configs?

No—the script does not support selective exclusion. To preserve specific files, back them up before running, or use rsync -avn /etc/skel/. ~/ to preview changes and manually merge differences.

Why does the script refuse to run as root?

Root execution would target /root instead of a regular user's home directory, wasting the operation and potentially corrupting administrative configurations. Always run from the account you intend to reset.

How is this different from deleting ~/.config and rebooting?

Direct deletion leaves orphaned state files and misses updates to non-config files (.bashrc, desktop entries, migration markers). The /etc/skel resync ensures complete alignment with current Omarchy defaults, including files you might not know exist.

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