Dotfiles Management

Repository Location

The repository lives at ~/dotfiles on macOS and Arch Linux.

Debugging: Installation output is logged to ~/dotfiles_install.log

Structure

The repo follows a one directory per tool pattern. To see the current structure:

tree ~/dotfiles -L 2 -d   # or: ls -la ~/dotfiles

Each tool directory should contain:

1. install script with install() and configure() functions
2. Config files to be symlinked to appropriate locations

See [references/tool-template.md](references/tool-template.md) for the install script template.

Quick Reference

Platform Support

See [references/platform-detection.md](references/platform-detection.md) for detection code snippets.

Important Constraints

Always Modify Dotfiles, Not Config Targets

Never create or edit files directly in config target directories like ~/.config/ or ~/.local/bin/. These locations contain symlinks to ~/dotfiles/, so changes made there are either not version controlled or will be overwritten by install scripts.

Always make changes in ~/dotfiles/ so they are:

1. Version controlled (git)
2. Propagated to other machines via dot pull
3. Not overwritten by install scripts

Common mistakes to avoid:

• Creating skills in ~/.claude/skills/ or ~/.pi/agent/skills/ instead of ~/dotfiles/skills/
• Editing nvim config in ~/.config/nvim/ instead of ~/dotfiles/nvim/
• Adding scripts to ~/.local/bin/ instead of ~/dotfiles/bin/

After creating or modifying files in ~/dotfiles/, run the appropriate install script to create symlinks (e.g., dot install skills, dot install nvim).

Key Principles

• Always install latest versions: Install scripts should always fetch the latest stable/LTS version of tools, not pin to specific versions. Use @latest tags, --lts flags, or omit version specifiers where possible.
• Idempotent scripts: Install scripts must be safe to run multiple times without side effects.
• Platform-aware: Use platform detection to handle differences between macOS and Arch.
• Script pattern: Each tool script should have install(), configure(), and optionally apply() and update() functions.

Installation Preference Hierarchy

1. Direct GitHub releases - Preferred for tools with prebuilt binaries not yet managed by Nix
2. Nix flake profile - Preferred for shared language runtimes/toolchains and base utilities managed in dotfiles (currently base utilities, Node + TypeScript tools, Go, Rust, Ruby, Neovim, Helix, jj, gh, glab, AWS CLI, Git, 1Password CLI, Whisper, Zig, bat)
3. Package managers - Only when no prebuilt binaries or Nix packages fit (system tools via pacman, GUI apps via brew casks)

Homebrew is installed lazily in Phase 3 of install, only when needed for brew-dependent tools.

Standard Binary Locations

Scripts from bin/ are symlinked individually to ~/.local/bin/.

Idempotency Guidelines

Scripts should produce the same result whether run once or many times:

1. Check before installing: Use command -v <tool> to skip if already installed

``bash if command -v rustc &>/dev/null; then echo "Rust already installed" return fi ``

1. Use -sf for symlinks: The -f flag overwrites existing symlinks safely

``bash ln -sf "$SCRIPT_DIR/.config" "$HOME/.config/tool" ``

1. Handle existing directories: Check and backup if needed

``bash if [[ -e "$target" && ! -L "$target" ]]; then mv "$target" "$target.backup" fi ``

1. Use --noconfirm for package managers: Avoid interactive prompts

``bash sudo pacman -S --noconfirm package brew install package # Already non-interactive ``

dotfiles CLI

The dot command (symlinked to ~/.local/bin/ from bin/dotfiles) provides easy management:

dotfiles status   # Check install/config health
dotfiles pull     # Pull latest and apply changes (skipped on Omarchy)
dotfiles edit     # Open dotfiles in $EDITOR
dotfiles update   # Update tools (brew, Nix profiles, nvim plugins, etc.)

The CLI uses jj (Jujutsu) if available, falling back to git.

Common Tasks

Adding a New Tool

1. Create <tool>/ directory at repo root
2. Create <tool>/install script using the template with:

- install() - Install the tool binary/package - configure() - Symlink configs, set up environment - apply() (optional) - Reload config after dotfiles pull, or handle migrations - update() (optional) - Update tool for dotfiles update - checkinstalled() / checkconfigured() - For dot status health checks

1. Add config files to the directory
2. Test on each platform
3. Optionally integrate with install in the appropriate phase

See [references/tool-template.md](references/tool-template.md) for the install script template. See [references/install-patterns.md](references/install-patterns.md) for version checking and migrations.

Modifying Neovim Config

See [references/nvim-config.md](references/nvim-config.md) for structure details.

Key locations:

• Plugins: nvim/lua/plugins/<name>.lua
• Key bindings: nvim/lua/config/mappings.lua
• Core options: nvim/init.lua

Running Install Scripts

# Main install
~/dotfiles/install

# Tool-specific installs
~/dotfiles/base/install
~/dotfiles/nvim/install
~/dotfiles/zsh/install.zsh
~/dotfiles/skills/install
~/dotfiles/aws/install
~/dotfiles/node/install
~/dotfiles/rust/install
~/dotfiles/go/install
~/dotfiles/jj/install

Shared Utilities

The lib/common.sh file provides shared functions for all scripts:

source "$DOTFILES_DIR/lib/common.sh"

dotfiles_dir    # Get dotfiles path
is_macos        # Check if running on macOS
is_arch         # Check if running on Arch Linux
is_omarchy      # Check if running on Omarchy
vcs_cmd         # Run jj or git command
log_info/log_success/log_warn/log_error  # Logging helpers