Difference Between User Themes and Git-Installed Themes in Omarchy

Git-installed themes ship with the omacom/omarchy repository and copy to your user directory during refresh, while user themes live in ~/.config/omarchy/themes/ and automatically override built-in versions with identical names.

The Omarchy framework manages themes through a dual-layer system that separates version-controlled defaults from personal customizations. Understanding how user themes and git-installed themes in Omarchy interact allows you to customize your environment safely without losing upstream updates or creating Git conflicts. This distinction relies on specific loading precedence rules and directory structures implemented in the source code.

What Are Git-Installed Themes?

Git-installed themes are the default, repository-bundled themes that ship with Omarchy under the top-level themes/ directory. These files serve as the baseline configuration that all users receive upon installation.

Location and Structure

Repository themes follow a structured path within the Omarchy codebase:

• themes/solitude/vscode.json – VS Code theme definition bundled with the repository
• themes/retro-82/btop.theme – Terminal color theme for system monitoring tools

When you execute the omarchy-refresh-config command, the script copies contents from $OMARCHY_PATH/config/ into your local ~/.config/omarchy/ directory. This process propagates the built-in theme files into your user configuration space, making them available for runtime selection. The refresh logic resides in bin/omarchy-refresh-config, which handles the synchronization of these default assets.

Update Cycle

Git-installed themes update only when you pull the latest repository changes via git pull and subsequently run omarchy-refresh-config. Because these files originate from version control, modifying them directly in the repository directory would create merge conflicts during updates—a key reason the user theme system exists.

What Are User Themes?

User themes are custom theme files you create directly in your configuration directory without touching the repository. These files persist independently of Omarchy updates and take precedence over built-in options.

Creating Custom Themes

Place user themes in the dedicated user directory to activate them:

mkdir -p ~/.config/omarchy/themes/my-custom
cat > ~/.config/omarchy/themes/my-custom/theme.json <<'EOF'
{
  "extension": "my.custom-theme",
  "colors": { "background": "#1e1e2e", "foreground": "#cdd6f4" }
}
EOF

Unlike git-installed themes, user themes require no Git operations or refresh commands to become available. Omarchy detects them immediately upon file creation in ~/.config/omarchy/themes/.

Override Behavior

User themes function as overrides. If you create a user theme with the same relative path as a git-installed theme—such as ~/.config/omarchy/themes/solitude/vscode.json to match themes/solitude/vscode.json—Omarchy loads your version exclusively. This cascading load order, referenced in configuration files like default/omarchy/omarchy-menu.jsonc, allows safe customization without forking the repository.

Key Differences Between User and Git-Installed Themes

Understanding the technical distinctions helps you manage customization workflows effectively:

• Location: Git-installed themes originate in the repository's themes/ directory (e.g., themes/retro-82/btop.theme), while user themes reside exclusively in ~/.config/omarchy/themes/.

• Installation Method: Git-installed themes deploy via the omarchy-refresh-config command, which copies $OMARCHY_PATH/config/ contents to your user directory. User themes require no refresh command—you simply create files in the user config directory.

• Update Behavior: Repository themes update when you run git pull on the Omarchy repository, requiring a subsequent refresh to propagate changes. User themes remain static unless you manually edit them, surviving repository updates without modification.

• Loading Priority: User themes always win namespace conflicts. If both a git-installed and user theme share the same filename and relative path, Omarchy loads the user version.

Working with Themes in Practice

Refreshing Git-Installed Themes

To synchronize the latest built-in themes from the repository to your user config:

omarchy-refresh-config

This command replicates the structure from $OMARCHY_PATH/config/ into ~/.config/omarchy/, ensuring your local environment reflects the current repository state.

Overriding a Built-In Theme

Copy an existing git-installed theme as your starting point, then modify it:

cp ~/.config/omarchy/themes/solitude/vscode.json \
   ~/.config/omarchy/themes/solitude/vscode.json.edit

# Edit the copied file – your changes take precedence over the repo version

Since the modified file resides in your user config directory, Omarchy treats it as a user theme with higher priority than the git-installed original, effectively masking the built-in version without deleting it.

Summary

• Git-installed themes reside in the repository's themes/ directory and copy to ~/.config/omarchy/ during omarchy-refresh-config
• User themes live directly in ~/.config/omarchy/themes/ and automatically override git-installed themes with identical names
• Precedence follows a cascading model: repository defaults load first from the config directory, user customizations apply second
• Persistence differs by type—git-installed themes update with git pull and refresh commands, while user themes remain unchanged unless manually edited

Frequently Asked Questions

Where are git-installed themes stored in Omarchy?

Git-installed themes store their source files in the repository's top-level themes/ directory, such as themes/solitude/vscode.json and themes/retro-82/btop.theme. During the refresh process, bin/omarchy-refresh-config copies these files into your user configuration at ~/.config/omarchy/themes/.

How do I override a built-in theme with a custom version?

Create a file with the same relative path in your user config directory. For example, to override themes/solitude/vscode.json, place your modified version at ~/.config/omarchy/themes/solitude/vscode.json. Omarchy automatically prioritizes the user directory version over the git-installed copy during the theme loading sequence.

What happens to user themes when I update Omarchy?

User themes remain untouched during repository updates. Since they reside in ~/.config/omarchy/ rather than the repository directory, git pull operations only modify the source themes. You must run omarchy-refresh-config again to receive updated git-installed themes, but your custom themes persist independently without modification.

Can I delete git-installed themes from my config directory?

Yes. Since omarchy-refresh-config replicates the repository structure into ~/.config/omarchy/, deleting files from your user config directory only removes your local copies. The originals remain safe in the repository's themes/ directory. To remove a theme from your active configuration, delete it from ~/.config/omarchy/themes/; it will not reappear unless you run the refresh command again.

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