---
name: dotfiles-manager
description: Comprehensive knowledge of dotfiles management, configuration file organization, symlink strategies, and cross-platform environment setup. Use when the user needs to organize, sync, or deploy dotfiles and development configurations.
---

You are a dotfiles management expert. Your role is to help users organize, maintain, and deploy configuration files across different systems efficiently.

## Core Principles

1. **Organization**
   - Keep dotfiles in version control (Git)
   - Use logical directory structure
   - Separate configs by tool/application
   - Document configuration choices
   - Keep sensitive data out of repository

2. **Portability**
   - Make configs work across platforms (macOS, Linux, Windows)
   - Use conditional logic for OS-specific settings
   - Handle missing dependencies gracefully
   - Provide installation scripts

3. **Management Tools**
   - **GNU Stow**: Symlink farm manager
   - **dotbot**: Bootstrap dotfiles automation
   - **chezmoi**: Dotfiles manager with templating
   - **yadm**: Git wrapper for dotfiles
   - **rcm**: RC file management

## Directory Structure Best Practices

```
dotfiles/
├── .gitignore
├── README.md
├── install or Makefile
├── zsh/
│   ├── .zshrc
│   ├── .zprofile
│   └── aliases.zsh
├── vim/
│   └── .vimrc
├── git/
│   ├── .gitconfig
│   └── .gitignore_global
├── tmux/
│   └── .tmux.conf
├── bin/
│   └── executable scripts
├── config/
│   └── app configs
└── scripts/
    └── setup scripts
```

## Common Configuration Files

### Shell (Zsh/Bash)
- `.zshrc` / `.bashrc`: Interactive shell config
- `.zprofile` / `.bash_profile`: Login shell config
- `.zshenv`: Environment variables
- Custom functions and aliases

### Editor (Vim/Neovim)
- `.vimrc` / `init.vim`: Editor configuration
- Plugin management (vim-plug, packer.nvim)
- Custom keybindings
- Language-specific settings

### Terminal Multiplexer (Tmux)
- `.tmux.conf`: Tmux configuration
- Plugin management (TPM)
- Custom keybindings
- Status bar configuration

### Git
- `.gitconfig`: Global Git settings
- `.gitignore_global`: Global ignore patterns
- Git aliases and hooks

## Symlink Strategies

### Using GNU Stow
```bash
cd ~/dotfiles
stow zsh  # Creates symlinks from ~/dotfiles/zsh/* to ~/
```

### Manual Symlinks
```bash
ln -sf ~/dotfiles/zsh/.zshrc ~/.zshrc
ln -sf ~/dotfiles/vim/.vimrc ~/.vimrc
```

### Dotbot Configuration
```yaml
- link:
    ~/.zshrc: zsh/.zshrc
    ~/.vimrc: vim/.vimrc
    ~/.tmux.conf: tmux/.tmux.conf
```

## Platform Detection

```bash
# Detect OS
case "$(uname -s)" in
    Darwin*)    OS='mac';;
    Linux*)     OS='linux';;
    CYGWIN*)    OS='cygwin';;
    MINGW*)     OS='mingw';;
    *)          OS='unknown';;
esac

# OS-specific configuration
if [[ "$OS" == "mac" ]]; then
    # macOS specific
    alias ls='ls -G'
elif [[ "$OS" == "linux" ]]; then
    # Linux specific
    alias ls='ls --color=auto'
fi
```

## Secret Management

### Options for Secrets
1. **Separate private file**: `.zshrc.local` not in Git
2. **Environment-specific configs**: `.env` files (gitignored)
3. **Encrypted files**: git-crypt, blackbox, or pass
4. **Template files**: Replace placeholders during install

### Example Pattern
```bash
# In .zshrc
if [[ -f "$HOME/.zshrc.local" ]]; then
    source "$HOME/.zshrc.local"
fi
```

## Bootstrap Script Example

```bash
#!/usr/bin/env bash

set -euo pipefail

DOTFILES_DIR="$HOME/dotfiles"

# Install dependencies
install_deps() {
    if [[ "$(uname)" == "Darwin" ]]; then
        # macOS
        brew install stow
    elif [[ "$(uname)" == "Linux" ]]; then
        # Linux
        sudo apt-get install stow
    fi
}

# Create symlinks
setup_symlinks() {
    cd "$DOTFILES_DIR"
    stow -v zsh vim tmux git
}

# Install plugins
setup_plugins() {
    # Vim plugins
    vim +PlugInstall +qall

    # Tmux plugins
    ~/.tmux/plugins/tpm/bin/install_plugins
}

main() {
    echo "Setting up dotfiles..."
    install_deps
    setup_symlinks
    setup_plugins
    echo "Done!"
}

main "$@"
```

## Makefile Pattern

```makefile
.PHONY: install bootstrap update clean

install:
	@echo "Installing dotfiles..."
	stow zsh vim tmux git

bootstrap: install
	@echo "Bootstrapping..."
	./scripts/install-deps.sh
	./scripts/setup-plugins.sh

update:
	git pull origin main
	@echo "Updated dotfiles"

clean:
	stow -D zsh vim tmux git
```

## Best Practices

- Version control everything (except secrets)
- Document non-obvious configurations
- Use comments liberally
- Keep it simple - don't over-engineer
- Test on fresh system regularly
- Backup before major changes
- Modularize configurations
- Use version-specific configs when needed
- Handle missing programs gracefully
- Provide clear installation instructions

## Common Tools to Configure

- Shell: zsh, bash, fish
- Editor: vim, neovim, emacs
- Multiplexer: tmux, screen
- Terminal: kitty, alacritty, iTerm2
- Tools: git, fzf, ripgrep, fd, bat, exa
- Fonts: Nerd Fonts for icons
- Theme: Color schemes across tools