This repository contains my dotfiles, managed with chezmoi. The goal of this repository is to provide a consistent and reproducible terminal environment across macOS and Linux systems by capturing shell settings, editor preferences, and much more.

• Shell (Zsh): Platform‑specific configurations built on Oh My Zsh. The templates, located in .chezmoitemplates, define and source plugins, helper functions, and other settings.
• Shell Prompt: Custom Starship configurations, which define icons for many languages and OSes.
• Editor / IDE: Neovim configurations, with plugins managed by vim-plug.
• Version Control: A Git configuration template, with Delta integration.
• Fonts: Meslo Nerd Font files under .fonts to render terminal icons.
• Chezmoi Data & Templates: Data files and external resource definitions in .chezmoidata and .chezmoiexternal.toml.tmpl.
• Package Definitions: Package lists for different operating systems, used by the package installer script to install CLI tools.

• OS & package manager detection: The installer scripts check the OS and choose the appropriate package manager. Unsupported systems are skipped or fail gracefully.
• GUI awareness: A precompute script examines the environment and caches whether a GUI session is present. Other scripts use this flag to enable or disable desktop‑specific settings.
• Automatic template selection: When applying the Zsh configurations, the system automatically selects the appropriate template for Linux or macOS.

• Packages: The package installer script reads packages.yaml and installs both general and OS‑specific CLI tools via pacman, apt, or Homebrew. Refer to External Resource Management for additional software not handled by a package manager.
• Neovim & Starship: On Debian-based distros, dedicated scripts (Neovim & Starship) download the latest releases of Neovim and Starship from GitHub — package manager versions often lag behind. They compare these with the currently installed versions and install them if they're newer. On macOS and Arch, these tools are managed by a package manager.
• Nerd fonts: A font installer script checks whether Meslo Nerd Font files are missing or outdated by comparing file hashes, then copies updated fonts into ~/.local/share/fonts and refreshes the font cache. macOS users get their fonts via a Homebrew cask.
• Default shell: A default shell script sets Zsh as the default shell for the current user. This script only runs once, unless executed manually.

• Neovim plugin maintenance: A plugin‑update script runs whenever your Neovim configurations change or after a set amount of time has passed. It installs vim‑plug if it's missing and runs PlugInstall, PlugUpdate, and TSUpdate in headless mode to install and update plugins and tree-sitters.
• Safe shell updates: Before overwriting your Zsh configurations, a drift‑detection script extracts the managed portion of ~/.zshrc, compares it with the current template, shows a diff, and prompts you to apply, skip, or cancel the changes.
  • Managed portion: The drift-detection script ignores all changes below the chezmoi:unmodified comment at the bottom of the .zshrc file. This section ensures configurations can be added without them being tracked or overwritten during updates.

• Automated downloads: The .chezmoiexternal.toml.tmpl file tells chezmoi to fetch and cache third‑party tools during chezmoi apply. It downloads vim‑plug, Oh My Zsh, zsh plugins, and much more.
• Scheduled refreshes: Each external resource defines a refresh period of 168 hours (one week), ensuring that these tools stay up to date without manual intervention.

These dotfiles are made for macOS and Linux only. Before applying them, ensure you meet the following prerequisites:

• chezmoi for dotfiles management
• Homebrew (on macOS)
• Git (version 2.0+)
• Bash (version 3.2+)
• Internet connection for downloading external resources
• Administrative privileges (for package installation on Linux)

1. Install chezmoi (if not already installed):

   # macOS
   brew install chezmoi
   
   # Linux
   sh -c "$(curl -fsLS get.chezmoi.io)"

2. Initialize with this repository:

   chezmoi init https://github.com/StrangeRanger/dotfiles.git

3. Preview changes (optional):

   chezmoi diff

4. Apply the dotfiles:

   chezmoi apply

   [!NOTE] The first run will install packages, fonts and configure your environment. This may take a minute or two and will require administrative privileges on Linux systems.

To update your dotfiles:

chezmoi update

During the update/apply process, you may see a prompt like:

Detected changes in '~/.zshrc' above '#### chezmoi:unmodified'.
--- current (head) vs rendered (head) diff ---
<colorized diff>
Proceed with changes? [y]es / [S]kip / [c]ancel apply:

Options:

• y: Apply the changes
• s: Skip modifying ~/.zshrc (Default)
• c: Abort the entire apply

Skip flag:

• When skipping ~/.zshrc modifications, a skip flag file is created so the modifying template leaves it as-is.
• The flag is placed at $XDG_RUNTIME_DIR/chezmoi/skip-dot-zshrc or ~/.cache/chezmoi/skip-dot-zshrc. It is removed automatically on the next run.

Some steps are intentionally skipped when no TTY is available (e.g., in CI or automated provisioning) to avoid hanging on prompts:

• .zshrc head drift
• Package installation
• Starship installation
• Neovim installation

These safeguards ensure unattended runs complete safely without partial or unintended configuration changes.

Please use GitHub Issues for bug reports and feature requests.

This project is licensed under the MIT License.