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

> Learn how omarchy-reinstall-configs resets user configs using /etc/skel. Discover how it seeds and resyncs your home directory to factory defaults.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-20

---

**`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

```bash
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](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-reinstall-configs#L7-L10))**.

### 2. Status Notification

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

```

A clear progress message confirms the operation has started **([line 12](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-reinstall-configs#L12))**.

### 3. Core Copy Operation

```bash
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](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-reinstall-configs#L14-L20))**.

### 4. System UI Refresh

```bash
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](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-reinstall-configs#L21-L23))**.

### 5. Neovim Configuration Handling

```bash
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](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-reinstall-configs#L24-L28))**.

## Practical Usage Examples

### Basic Resync

```bash

# From a regular user shell

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

```

### Verify Restoration

```bash

# Confirm a specific file matches the default

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

```

### Preview Changes (Dry Run)

```bash

# 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](https://github.com/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.