What Is the Purpose of the `omarchy-settings` Arch Package?

The omarchy-settings Arch package serves as the static defaults bootstrap package that delivers all configuration files, system-wide defaults, and assets required before the main omarchy components can function properly.

According to the omac/o·marchy source code, omarchy-settings (and its development counterpart omarchy-settings-dev) is designed to separate immutable defaults from runtime logic. This architecture ensures that fresh installations and user accounts start with a consistent, working configuration while allowing the core omarchy package to focus on dynamic system management.

How omarchy-settings Seeds New User Accounts

One of the primary responsibilities of omarchy-settings is populating /etc/skel/ with the Omarchy configuration template.

When a new user account is created on an Arch system, files in /etc/skel/ are automatically copied to that user's home directory. The omarchy-settings package pre-populates this directory so that any freshly created user instantly receives the complete Omarchy desktop environment configuration.

This seeding mechanism is documented in docs/file-layout.md at line 35, which describes how user-level defaults propagate through the system.

Installing System-Wide Defaults

Beyond user templates, omarchy-settings installs configuration files across multiple system directories:

Destination	Purpose
/etc/	Core system configuration (e.g., etc/fastfetch/config.jsonc → /etc/fastfetch/config.jsonc)
/usr/share/omarchy/default/	Omarchy-specific default templates
/usr/share/icons/	Icon themes and assets
/etc/snapper/config-templates/omarchy	Btrfs snapshot configuration template

As noted in docs/file-layout.md at line 86, these path mappings ensure that system utilities and desktop components find their configurations in standard locations without requiring manual setup.

Providing Default systemd User Units

The package ships disabled systemd units that administrators can selectively enable. The most significant example is the backup infrastructure:

• omarchy-backup.timer — Ships disabled via the omarchy-settings PKGBUILD

This approach allows the backup subsystem to exist on all installations without automatically consuming resources. Administrators explicitly enable the timer when they want scheduled backups, as described in plans/backup.md at line 68.

Packaging Static Assets

omarchy-settings bundles visual and interface resources under /usr/share/omarchy/:

• Omarchy icon font
• Distribution logos
• Theme resources

The logo assets entry at line 136 of docs/file-layout.md confirms that these resources install to standard XDG-compliant paths where GTK/Qt applications and display managers can locate them.

Enabling ALPM Hook Integration

The omarchy package installs pre-transaction hooks specifically designed to watch for installs or upgrades of omarchy-settings or omarchy-settings-dev. These hooks ensure configuration files remain synchronized when the defaults package updates.

This hook mechanism is documented in docs/update-process.md at line 101. The separation between omarchy-settings (static data) and omarchy (runtime logic with hooks) creates a clean update pipeline where configuration changes trigger appropriate system responses.

Facilitating Configuration Re-Synchronization

When users run the omarchy-reinstall-configs command, the system forcibly copies the defaults that originated from omarchy-settings into the user's $HOME directory. This overwrites any divergent customizations, providing a "factory reset" mechanism for user configurations.

This capability relies on omarchy-settings remaining the canonical source of truth for default configurations.

Installation and Usage Examples

# Install the stable Omarchy stack (includes omarchy-settings)

sudo pacman -S --needed omarchy omarchy-settings

# Install the development/edge stack (includes the dev variant)

sudo pacman -S --needed omarchy-dev omarchy-settings-dev

# After a system upgrade, force-reapply the default configs shipped by omarchy-settings

omarchy-reinstall-configs   # Resynchronises /etc/skel and $HOME defaults

Key Source Files Defining omarchy-settings Architecture

• docs/file-layout.md — Complete mapping of omarchy-settings assets to destination paths
• plans/backup.md — Documentation of backup systemd units shipped via PKGBUILD
• docs/update-process.md — ALPM hooks that react to omarchy-settings installs/upgrades
• agents/skills/install-scripts.md — Explanation of /etc/skel seeding used by omarchy-finalize-user
• test/shell.d/* — Test suites including update-available-test.sh and update-file-conflict-test.sh for verification

Summary

• omarchy-settings is the static defaults bootstrap package that must install before omarchy runtime components
• Seeds /etc/skel/ so new users receive complete Omarchy configurations automatically
• Installs system-wide defaults to /etc/, /usr/share/omarchy/default/, and standard XDG paths
• Ships disabled systemd units like omarchy-backup.timer for optional administrative features
• Bundles icon fonts, logos, and visual assets to /usr/share/omarchy/
• Triggers ALPM hooks in the omarchy package to maintain configuration synchronization
• Provides the canonical source for omarchy-reinstall-configs reset operations

Frequently Asked Questions

What is the difference between omarchy-settings and omarchy-settings-dev?

omarchy-settings-dev is the development/edge counterpart to the stable omarchy-settings package. It contains the same structural components but tracks the development branch of Omarchy, allowing testers and contributors to run bleeding-edge default configurations alongside omarchy-dev.

Can I use Omarchy without installing omarchy-settings?

No. The omarchy package depends on omarchy-settings because it requires the seed files in /etc/skel/, system-wide defaults, and assets to function. Attempting to install omarchy without its settings package would leave the system without the necessary configuration foundation.

What happens when omarchy-settings updates?

The pre-transaction hooks installed by the omarchy package detect the upgrade and execute synchronization logic. This ensures that any changes to default configurations propagate appropriately while preserving explicit user modifications where possible. For forced re-synchronization, run omarchy-reinstall-configs.

Where does omarchy-settings store its files in the repository?

While the built package installs to system paths, the source repository organizes these files under standard directories that map to installation targets via the PKGBUILD. The complete mapping is documented in docs/file-layout.md, showing how repository paths like etc/fastfetch/config.jsonc become /etc/fastfetch/config.jsonc on target systems.

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