dots

A repository containing instructions and dotfiles for tools I use across multiple development machines.

The intended model is:

• one main branch
• shared tracked config
• OS-specific tracked overlays
• host-specific tracked overlays
• untracked local/private overrides

The repo now includes a layered bootstrap flow for symlinking managed files into a machine:

• bin/bootstrap plan
• bin/bootstrap status
• bin/bootstrap apply

See docs/BOOTSTRAP.md for the manifest layout, backup behavior, and the shared/OS/host overlay model.

For CLI tool installation policy, see docs/MISE.md.

The repo is intended to keep one main branch that supports machine diversity through overlays rather than long-lived machine branches.

The shell config is layered:

• .zshenv is a quiet non-interactive baseline for local bins and the user ssh-agent socket
• .zprofile prepares login shells with the mise shim PATH before interactive startup
• .zshrc is a thin interactive loader
• shell/zshrc.shared contains the common interactive baseline
• shell/zshrc.macos or shell/zshrc.linux contains OS-specific setup, including interactive mise activate
• shell/zshrc.host.<hostname> is for tracked host-specific overrides
• ~/.config/rspurgeon/local.zsh is the untracked local include for secrets and machine-private paths
• local/local.zsh.example and local/git-config.local.example show the intended local-only shape

The bootstrap manifests are also layered:

• bootstrap/manifest.d/00-shared.tsv
• bootstrap/manifest.d/10-macos.tsv
• bootstrap/manifest.d/10-linux.tsv
• bootstrap/manifest.d/20-host-<hostname>.tsv

New Machine Workflow

For a new machine or a major refactor migration, use this order:

1. Clone the repo to $HOME/dev/rspurgeon/dots
2. Install base OS packages and fonts
3. Run bin/setup-shell to ensure zsh, zsh plugins, and the login shell are configured
4. Install oh-my-zsh
5. Run bin/mise-sync install
6. Run bin/setup-nvim
7. Run bin/setup-tmux
8. Create local-only files as needed:

• ~/.config/rspurgeon/local.zsh
• ~/.config/git/config.local

9. Run bin/bootstrap plan
10. Run bin/bootstrap apply
11. On Omarchy Linux desktops, run bin/setup-omarchy-browser-defaults after installing Firefox and Chromium
12. Open a new shell and verify the machine with:

• bin/bootstrap status
• bin/mise-sync status

Overlay Rules

Use this rule of thumb when deciding where config belongs:

• Shared defaults used on most machines belong in shared tracked config.
• OS-specific behavior belongs in shell/zshrc.<os> or bootstrap/manifest.d/10-<os>.tsv.
• Role-specific behavior belongs in shell/zshrc.profile.<profile> or manifest selectors like profile:work and profile:desktop.
• Stable host-specific behavior is reserved for physical-machine details such as monitor layout under .config/hypr/hosts/<hostname>/.
• Secrets, private tokens, personal aliases, and machine-private paths belong in untracked local files.

Examples of local-only files:

• ~/.config/rspurgeon/local.zsh
• ~/.config/git/config.local

Do not use long-lived machine branches for normal setup. Prefer extending the overlay model on main.

I use the zsh shell which is the default on macOS Monterey, the current OS of choice. The brew install commands below could be replaced with a Brewfile solutions, I just haven't take the time yet.

Clone this repo

• git clone git@github.com:rspurgeon/dots.git $HOME/dev/rspurgeon/

Install the xcode command line tools

• xcode-select –install

Install Homebrew

• /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install fonts

• brew tap homebrew/cask-fonts brew search '/font-.*-nerd-font/' | awk '{ print $1 }' | xargs -I{} brew install --cask {} || true
• https://github.com/rspurgeon/nerd-fonts#patched-fonts

Install JetBrains Mono Nerd Font

• Use your platform package manager or install from the Nerd Fonts project
• The active Ghostty, Neovim GUI, and iTerm2 configs use JetBrainsMono Nerd Font Mono

Install various tools

• brew install wget zsh-syntax-highlighting

Install shared CLI tools from the repo-managed mise config

• bin/mise-sync install

Install iTerm2

• Once installed, import the profile in $HOME/dev/rspurgeon/dots/iterm2-default-profile.json and switch to iTerm

Install NeoVim

• brew install neovim

Install NeoVim Packer

• bin/setup-nvim
• Then run nvim +PackerSync

Install nvm

• curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Install pyenv

• brew install openssl readline sqlite3 xz zlib pyenv pyenv-virtualenv
• pyenv install 3.8.13
• pyenv global 3.8.13

Install sdkman

• curl -s "https://get.sdkman.io" | bash
• source "$HOME/.sdkman/bin/sdkman-init.sh"
• sdk install java 11.0.14-zulu

Install oh-my-zsh

• sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Install Starship

• https://starship.rs/guide/#%F0%9F%9A%80-installation

Install zsh-autosuggestions

• bin/setup-shell
• The shell setup script installs the plugin into ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions when needed.

Install zsh-syntax-highlighting

• bin/setup-shell
• The shell setup script installs the plugin into ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting when needed.

Install tmux

• brew install tmux

Install .tmux, which is a nice base tmux configuration

• bin/setup-tmux
• This installs the gpakosz base config at ~/dev/gpakosz/.tmux, links ~/.tmux.conf, installs TPM, and prepares tmux plugins

Install tmuxinator

• brew install tmuxinator

Install tmux plugins

• bin/setup-tmux
• If tmux is already running, the script reloads the base and local config and installs TPM plugins
• Otherwise start tmux and run ~/.tmux/plugins/tpm/bin/install_plugins, or press prefix + I

Install powerline status bar, which I use in vim and tmux

• pip install powerline-status

Enable the environment by creating symbolic links to the dotfiles in this repository

• bin/bootstrap plan
• bin/bootstrap apply
• Managed paths currently include .zshenv, .zprofile, .zshrc, .vimrc, .tmux.conf.local, .config/alacritty, .config/git/config, .config/nvim, .config/powerline, .config/starship.toml, .config/starship-simple.toml, .config/tmux-powerline, .config/tmux-powerline-segments, .config/ghostty, .local/bin/pitch, .local/bin/pitch-mcp, and the iTerm2 dynamic profile on macOS
• mise is handled by bin/mise-sync, which copies mise/global-config.toml into ~/.config/mise/config.toml instead of symlinking it
• Alacritty is the primary cross-machine terminal. Treat .config/alacritty/alacritty.toml as the authoritative source for terminal font size and related defaults; .config/ghostty is retained as a secondary config

Linux Host Notes

Some Linux hosts may also have host-specific tracked entries such as:

• Omarchy Quattro Lua config in .config/hypr (legacy .conf files remain only for pre-Quattro rollback)
• Omarchy shell/bar config in .config/omarchy/shell.json (legacy Waybar files remain only for pre-Quattro rollback)
• Centered Pitch status as the user-owned rspurgeon.pitch-agents Omarchy shell plugin
• Per-monitor workspace indicators as the user-owned rspurgeon.workspaces Omarchy shell plugin
• host-specific helper configs like .config/pitch, .config/codex/guest, or nono/profiles
• host-specific theme assets under .config/omarchy/themes/...

These should normally be introduced through bootstrap/manifest.d/20-host-<hostname>.tsv.

For systemd --user units on Linux:

• Keep the tracked unit file contents in the repo under .config/systemd/user/*.service and *.timer.
• Reload and activate them with systemctl --user daemon-reload and the appropriate enable or start commands.
• Avoid assuming repo-managed *.wants symlinks belong in Git or bootstrap manifests unless you have verified that behavior on the target host.

For Omarchy browser defaults on Linux desktops:

• Use bin/setup-omarchy-browser-defaults to keep Firefox as the normal XDG browser while Omarchy web app launchers continue to use Chromium's --app mode.
• Do not commit ~/.config/mimeapps.list; desktop tools rewrite it as user state.

For the optional direct Avery-to-Ari Ethernet path after Quattro installs NetworkManager:

• Run bin/setup-omarchy-direct-network to install an isolated ari-direct profile for 10.77.0.2/30 with no default route or DNS and EEE disabled.
• The script deliberately does not activate the profile. Keep Wi-Fi/Tailscale available and test Ethernet separately after the upgrade.

For Avery's Wi-Fi handoff from Omarchy 3's iwd to Quattro's NetworkManager:

• After the Quattro packages are installed but before rebooting, run bin/setup-omarchy-wifi-networkmanager. It converts the saved root-only iwd key for NUTNET into an inactive root-only NetworkManager profile without printing the secret or starting NetworkManager. The profile is not tied to the legacy interface name, so it remains eligible if predictable naming changes wlan0 after reboot.
• Do not activate NetworkManager in the legacy live session. Its profile autoconnects on the first Quattro boot, restoring Wi-Fi before Tailscale reconnects.

Install exa for better file listing

• brew install exa

Install fzf for powerful search

• brew install fzf
• Install shell integrations with /opt/homebrew/opt/fzf/install

Install ag, the silver searcher

• brew install the_silver_searcher

Install kubectl

• brew install kubectl