What Is the Purpose of `default/bash/env-bootstrap` in Omarchy?

The default/bash/env-bootstrap script serves as the central environment initializer for Omarchy, resolving the active OMARCHY_PATH and constructing a deterministic, deduplicated PATH variable that ensures consistent tooling availability across Bash, Zsh, and POSIX-compatible shells.

The default/bash/env-bootstrap file in the Omarchy repository (Basecamp's Arch Linux-based desktop environment) functions as the single source of truth for shell environment preparation. When a user's session starts via /etc/profile.d/omarchy.sh, the default Bash rc, or the UWSM environment, this script is sourced to establish critical environment variables. This ensures that all Omarchy commands, user binaries, and development tools resolve correctly regardless of how the shell is invoked.

Core Responsibilities of the Bootstrap Script

Resolving the Active OMARCHY_PATH

The bootstrap script's primary duty is determining which Omarchy installation should take precedence. It evaluates whether the system should use the default installation directory at /usr/share/omarchy or a linked development checkout, ensuring all subsequent Omarchy commands point to the correct location. According to the test suite in test/shell.d/dev-env-path-test.sh【L54-L66】, this logic handles both standard installations and local development environments where developers may have symlinked alternative versions of the framework.

Building a Deterministic PATH

After establishing OMARCHY_PATH, the script constructs a clean and deterministic PATH variable with strict precedence rules. As implemented in the test validations【L56-L73】, the process:

• Prepends the active checkout's bin directory to ensure Omarchy tools take precedence
• Preserves unrelated existing entries that existed before the script ran
• Appends user-level paths such as ~/.local/bin and mise shims after system paths
• Removes duplicate entries while maintaining the intended order

This approach guarantees that system tools, Omarchy-specific utilities, and user-local installations resolve in the correct priority order without polluting the environment with redundant paths.

Cross-Shell Compatibility

Unlike shell-specific configuration files, env-bootstrap is designed to work when sourced by Bash, Zsh, and other POSIX-compatible shells. The script handles differences in how each shell expands and manipulates the PATH variable, as verified by compatibility checks in the test suite【L84-L85】. This universality ensures that users switching between shells or using tools like UWSM (Universal Wayland Session Manager) receive identical environment initialization.

Integration Points Across the System

Rather than duplicating environment logic across multiple files, Omarchy centralizes initialization by having various session entry points source env-bootstrap directly:

• /etc/profile.d/omarchy.sh – Initializes the environment for login shells
• default/bashrc – Provides the bootstrap for interactive Bash sessions
• default/uwsm/env.d/10-omarchy – Ensures graphical sessions launched via UWSM receive the same environment variables

This architecture keeps bootstrapping logic maintained in one location while ensuring consistency whether you access Omarchy through a TTY, terminal emulator, or Wayland session.

Testing and Validation

The logic within env-bootstrap is validated by test/shell.d/dev-env-path-test.sh, which verifies that:

1. Path resolution correctly identifies active checkouts versus default installations
2. Duplicate entries are eliminated without losing critical path ordering
3. User-level directories are appended rather than prepended
4. Cross-shell sourcing produces identical environment states

These tests ensure that modifications to the bootstrap script do not regress the environment setup across supported shell environments.

Practical Usage Examples

Sourcing the Bootstrap Manually

To load the Omarchy environment in a new shell session:

# Load the Omarchy environment

source /usr/share/omarchy/default/bash/env-bootstrap

# Verify that OMARCHY_PATH points to the active checkout

echo "$OMARCHY_PATH"

# Inspect the constructed PATH

echo "$PATH"

Automatic Integration in Bash

The default installation automatically adds this to ~/.bashrc:

# ~/.bashrc - Omarchy environment setup

[[ -r /usr/share/omarchy/default/bash/env-bootstrap ]] && source /usr/share/omarchy/default/bash/env-bootstrap

Verification Under Zsh

To confirm the bootstrap works with Zsh:

# .zshrc

[[ -r /usr/share/omarchy/default/bash/env-bootstrap ]] && source /usr/share/omarchy/default/bash/env-bootstrap

# Verify PATH ordering and deduplication

print -l $path

Summary

• default/bash/env-bootstrap is the single source of truth for Omarchy's shell initialization, sourced by login shells, interactive shells, and graphical sessions.
• The script resolves OMARCHY_PATH to distinguish between default installations (/usr/share/omarchy) and linked development checkouts.
• It constructs a deterministic PATH with strict precedence: Omarchy binaries first, then system tools, then user directories like ~/.local/bin.
• Duplicate path entries are eliminated while preserving intended ordering, as validated by test/shell.d/dev-env-path-test.sh.
• The script is POSIX-compatible and functions correctly when sourced by Bash, Zsh, and other shells.

Frequently Asked Questions

How does env-bootstrap determine which Omarchy checkout to use?

The script evaluates the filesystem to determine whether a linked checkout exists or if it should fall back to the default system installation at /usr/share/omarchy. This logic ensures that development environments using symlinked versions of Omarchy take precedence over the system-wide installation, while standard installations transparently use the default path.

Can I use env-bootstrap with Zsh instead of Bash?

Yes. The script is designed for cross-shell compatibility and handles the nuances of PATH expansion in both Bash and Zsh, as well as other POSIX-compatible shells. The test suite explicitly validates this behavior to ensure consistent initialization regardless of your chosen shell.

Where should I source env-bootstrap in my custom shell configuration?

You should source it early in your shell's initialization file (such as ~/.bashrc or ~/.zshrc), but the recommended approach is to allow Omarchy's default installation to manage this automatically via /etc/profile.d/omarchy.sh or the provided default/bashrc templates. If you must source it manually, ensure it runs before any commands that depend on Omarchy-specific binaries.

How does Omarchy prevent duplicate entries in PATH?

The bootstrap script implements deduplication logic that removes duplicate path entries while maintaining the intended precedence order. This ensures that if a directory appears multiple times (for example, through repeated sourcing or system-wide defaults), only the first occurrence is retained, keeping the environment clean and reducing command lookup overhead.

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