Chezmoi Dotfiles Management Implementation Plan

Summary

Implement chezmoi to manage dotfiles across multiple systems including local Windows 10/11, WSL2, and remote Linux systems. The primary development system is vanguard.sysdom.net, a 24/7 DC server for coding/dev.

Problem

Currently managing dotfiles manually across multiple systems leads to:

Inconsistent configurations between systems
Difficulty syncing changes across platforms
No centralized version control for all config files
Manual tracking of system-specific differences

Proposed Solution

Migrate existing dotfiles to chezmoi for cross-platform management with:

Template-based system: Use {{ .chezmoi.os }} and other template variables for OS/detection
System-specific directories: Separate windows/, wsl/, and linux/ directories for major variations
Binary management: Use ai-check.sh script to install tools, not track large binaries
Single git repository: Use existing repo at https://github.com/wsuff/dotfiles.git

Architecture

Primary System

vanguard.sysdom.net - 24/7 DC development server (first system to implement)
Current working directory: /home/william/dev/wsuff/dotfiles
Existing git remote: https://github.com/wsuff/dotfiles.git

Directory Structure

Chezmoi source will be managed at ~/.local/share/chezmoi, which commits to the existing repo:

~/.local/share/chezmoi/ (commits to /home/william/dev/wsuff/dotfiles)
├── .chezmoi.json          # Configuration & template data
├── .chezmoi.yaml          # Alternative config format
├── .chezmoiignore         # Files to exclude
├── .chezmoi.toml.tmpl     # Per-system configuration
├── dot_config/
│   ├── git/
│   │   └── ignore
│   ├── btop/
│   │   └── btop.conf.tmpl
│   └── htop/
│       └── htoprc
├── dot_bashrc.tmpl        # Bash config with OS templates
├── dot_zshrc.tmpl         # Zsh config (optional)
├── dot_profile.tmpl       # Profile with PATH modifications
├── dot_gitconfig.tmpl     # Git config (email/user variables)
├── dot_tmux.conf          # Tmux config (no templates needed)
├── dot_local/
│   └── bin/
│       ├── env
│       └── ai-check.sh
├── dot_local/bin/env.fish # Fish shell PATH setup
├── private_dot_bash_local.tmpl  # Per-system bash overrides
├── private_dot_bash_private.tmpl # Per-system bash private vars
├── windows/               # Windows-specific files (for future)
├── wsl/                   # WSL2-specific files (for future)
└── linux/                 # Linux-only configs (systemd, etc.)

What's Managed

Core shell configs (bash-focused):

.bashrc - Main bash configuration with OS-specific templates
.zshrc - Zsh config (secondary, minimal)
.profile - Login shell config with PATH setup
.local/bin/env - Cross-platform PATH script

Application configs:

.gitconfig - Git configuration with template variables
.tmux.conf - Tmux terminal multiplexer
.config/btop/btop.conf - System monitor with theme template
.config/htop/htoprc - Process viewer
.config/git/ignore - Git ignore patterns

Scripts:

.local/bin/ai-check.sh - AI tools version checker and installer

Template Strategy

1. Template variables (in .chezmoi.json):

{
  "data": {
    "githubUser": "wsuff",
    "email": "william.suffill@gmail.com",
    "gitEditor": "nano",
    "devSystem": "vanguard"
  }
}

2. OS detection templates:

{{ .chezmoi.os }} - "linux", "windows", "darwin"
{{ .chezmoi.hostname }} - "vanguard.sysdom.net", etc.
{{ .chezmoi.kernel.osrelease }} - Detect WSL2 via "microsoft"

3. Template example for bashrc:

{{- /* Core bash configuration */ -}}
# Source global definitions
if [ -f /etc/bashrc ]; then
    . /etc/bashrc
fi

{{- /* vanguard-specific settings */ -}}
{{- if eq .chezmoi.hostname "vanguard.sysdom.net" -}}
# Development environment settings on vanguard
export DEVMODE="dc"
{{- end -}}

{{- /* WSL2-specific settings */ -}}
{{- if .chezmoi.kernel.osrelease | contains "microsoft" -}}
# WSL2 Windows paths
export PATH="$PATH:/mnt/c/Windows/System32"
export DISPLAY=:0
{{- end -}}

{{- /* Source local overrides */ -}}
if [ -f ~/.bash_local ]; then
    . ~/.bash_local
fi

4. Btop theme template:

{{- if eq .chezmoi.os "windows" -}}
color_theme = "C:/Users/{{ .chezmoi.username }}/AppData/Local/btop/themes/matcha-dark-sea.theme"
{{- else -}}
color_theme = "/usr/local/share/btop/themes/matcha-dark-sea.theme"
{{- end -}}

System-Specific Directories

For major differences (templates for small differences, directories for major variations):

windows/ - Windows-native configs (PowerShell profiles, Windows Terminal)
wsl/ - WSL2-specific tweaks (Windows interop settings)
linux/ - Linux-only (systemd user services, cron, etc.)

Implementation Phases

Phase 1: Install Chezmoi & Initialize with Existing Repo

Install chezmoi on vanguard
- curl -fsSL https://chezmoi.io/get | bash

Initialize chezmoi using EXISTING repo as source

chezmoi init --source=~/.local/share/chezmoi https://github.com/wsuff/dotfiles.git
# OR use local path:
chezmoi init --source=~/.local/share/chezmoi /home/william/dev/wsuff/dotfiles

Verify setup
- chezmoi doctor - Check chezmoi installation
- chezmoi cd - Navigate to chezmoi source directory

Phase 2: Create Directory Structure

Create chezmoi source directories
Set up .chezmoi.json with template variables

Create .chezmoiignore for exclusions:

# Exclude compiled/binary files
node_modules/
*.o
*.exe
*.dll
.DS_Store

# Exclude cache/state files
.cache/
.local/state/

Phase 3: Migrate Core Shell Configurations

Files to add:

dot_bashrc.tmpl - Main bash configuration
- Migrate existing .bashrc content
- Add OS-specific sections using templates
- Add vanguard-specific settings
- Add WSL2 detection and Windows paths
dot_zshrc.tmpl - Zsh config (minimal)
- Keep simple: just sources env script
- Template for compatibility
dot_profile.tmpl - Login shell config
- Template for .local/bin PATH setup
- OS-specific PATH additions
- Source env script
dot_local/bin/env - PATH setup script
- Cross-platform (no changes needed)
- Already in current setup

Phase 4: Migrate Application Configurations

Files to add:

dot_tmux.conf - Tmux config
- Cross-platform compatible
- No templates needed
dot_config/git/ignore - Git ignore patterns
- Already minimal, cross-platform
dot_config/btop/btop.conf.tmpl - Btop config
- Template for theme path (Windows vs Linux)
dot_config/htop/htoprc - Htop config
- Cross-platform compatible
- No templates needed

Phase 5: Handle System-Specific Differences

Template variables - Configure .chezmoi.json
OS detection templates - Test OS detection logic
System-specific directories - Set up for future use
- windows/ - Placeholder for Windows configs
- wsl/ - Placeholder for WSL2 configs
- linux/ - Placeholder for Linux-only configs

Phase 6: Add Installation Scripts

dot_local/bin/ai-check.sh - AI tools checker
- Already exists, add to chezmoi
- Make executable: chezmoi chmod +x ~/.local/share/chezmoi/dot_local/bin/ai-check.sh
Optional: install.sh - Bootstrap script for new systems
- Install chezmoi if not present
- Clone repo and initialize
- Run ai-check.sh --install for missing tools
- This can live in the repo root for easy access

Phase 7: Git Integration (Using Existing Remote)

Verify existing remote (already configured)
- Origin: https://github.com/wsuff/dotfiles.git

Commit and push

cd ~/.local/share/chezmoi
git add .
git commit -m "Add chezmoi configuration"
git push origin main

Verify on vanguard
- chezmoi diff - See what would be applied
- chezmoi apply - Apply changes safely
- chezmoi verify - Check state matches

Phase 8: Test on Vanguard

Test chezmoi apply on vanguard
- Ensure all configs work correctly
- Verify bashrc loads properly
- Check PATH includes ~/.local/bin
- Test btop/htop/tmux with new configs
Test templates
- Verify OS detection works
- Check vanguard-specific settings apply
- Ensure no template errors
Document any issues
- Note any configs that don't work
- Fix templates if needed
- Update plan

Phase 9: Future Systems (Home Windows, WSL2, Remote Linux)

Windows setup

# PowerShell (admin)
winget install twpayne.chezmoi

# Initialize with existing repo
chezmoi init https://github.com/wsuff/dotfiles.git
chezmoi apply

WSL2 setup

# Install chezmoi in WSL2
curl -fsSL https://chezmoi.io/get | bash

# Initialize (will detect WSL2 automatically via templates)
chezmoi init https://github.com/wsuff/dotfiles.git
chezmoi apply

Remote Linux setup

# Same as vanguard
curl -fsSL https://chezmoi.io/get | bash
chezmoi init https://github.com/wsuff/dotfiles.git
chezmoi apply

Phase 10: Documentation

Update README.md in the repo with:

# Dotfiles - Chezmoi Managed

This repository contains my personal dotfiles managed by [chezmoi](https://www.chezmoi.io).

## Quick Start

### On a new system:

1. Install chezmoi:
   - Linux/WSL2: `curl -fsSL https://chezmoi.io/get | bash`
   - Windows: `winget install twpayne.chezmoi`

2. Initialize with this repo:
   ```bash
   chezmoi init https://github.com/wsuff/dotfiles.git
   chezmoi apply

Install AI development tools:
```
~/.local/bin/ai-check.sh --install
```

What's Managed

Shell configs (bash, zsh)
Git configuration
Terminal apps (tmux, btop, htop)
Development tools (via ai-check.sh)
System-specific configurations via templates

Template Variables

See .chezmoi.json for customizable variables like email, git editor, etc.

Primary System

vanguard.sysdom.net - 24/7 DC development server


## Security Considerations

- **No sensitive data in git**: Use `.chezmoi.json.template` for secrets, keep `.chezmoi.json` excluded
- **API keys**: Do not track API keys in dotfiles; use environment variables or external secret management
- **Binary management**: Don't track large binaries; use `ai-check.sh` for installation

## Key Design Decisions

1. **Existing repo integration**: Use current repo at `/home/william/dev/wsuff/dotfiles`, no new repo needed
2. **Chezmoi source location**: `~/.local/share/chezmoi` (standard chezmoi location), commits to existing repo
3. **Bash-focused**: Primary shell support, with zsh as secondary option
4. **Template + directories**: Templates for OS/detection, directories for major variations
5. **Primary system**: vanguard.sysdom.net (24/7 DC server) - first to test
6. **No binary tracking**: Rely on `ai-check.sh --install` for tool installation
7. **Maintain `.local/bin` convention**: All custom tools go in `$HOME/.local/bin`

## Checklist

### Phase 1: Chezmoi Setup
- [ ] Install chezmoi on vanguard
- [ ] Initialize chezmoi using existing GitHub repo
- [ ] Run `chezmoi doctor` to verify installation
- [ ] Navigate to chezmoi source directory (`chezmoi cd`)

### Phase 2: Directory Structure
- [ ] Create chezmoi source directory structure
- [ ] Create `.chezmoi.json` with template variables
- [ ] Create `.chezmoiignore` for file exclusions
- [ ] Set up system-specific directories (windows/, wsl/, linux/)

### Phase 3: Shell Configs
- [ ] Add `dot_bashrc.tmpl` with OS-specific templates
- [ ] Add `dot_zshrc.tmpl` (minimal)
- [ ] Add `dot_profile.tmpl` with PATH modifications
- [ ] Add `dot_local/bin/env` (existing script)

### Phase 4: App Configs
- [ ] Add `dot_tmux.conf`
- [ ] Add `dot_config/git/ignore`
- [ ] Add `dot_config/btop/btop.conf.tmpl` with theme template
- [ ] Add `dot_config/htop/htoprc`

### Phase 5: System-Specific Differences
- [ ] Configure template variables in `.chezmoi.json`
- [ ] Test OS detection templates
- [ ] Set up system-specific directories for future use

### Phase 6: Installation Scripts
- [ ] Add `dot_local/bin/ai-check.sh` (existing script)
- [ ] Make ai-check.sh executable
- [ ] Optional: Create `install.sh` bootstrap script

### Phase 7: Git Integration
- [ ] Verify existing git remote (https://github.com/wsuff/dotfiles.git)
- [ ] Commit all changes to chezmoi source
- [ ] Push to origin main
- [ ] Verify git status

### Phase 8: Testing
- [ ] Run `chezmoi diff` to see what would be applied
- [ ] Run `chezmoi apply` to apply changes safely
- [ ] Run `chezmoi verify` to check state matches
- [ ] Test bashrc loads properly
- [ ] Verify PATH includes `~/.local/bin`
- [ ] Test btop with new config
- [ ] Test htop with new config
- [ ] Test tmux with new config
- [ ] Test OS detection in templates
- [ ] Test vanguard-specific settings

### Phase 9: Future Systems
- [ ] Document Windows setup instructions
- [ ] Document WSL2 setup instructions
- [ ] Document remote Linux setup instructions

### Phase 10: Documentation
- [ ] Update `README.md` with quick start guide
- [ ] Document what's managed
- [ ] Document template variables
- [ ] Document primary system (vanguard)
- [ ] Link to chezmoi documentation

## References

- [Chezmoi Documentation](https://www.chezmoi.io)
- [Chezmoi Template Syntax](https://www.chezmoi.io/docs/reference/template/)
- [Managing Dotfiles with Chezmoi](https://www.chezmoi.io/docs/how-to/)
- [Existing dotfiles repo](https://github.com/wsuff/dotfiles)
- [ai-check.sh script](https://github.com/wsuff/ai-model-utils)

wsuff/chezmoi-dotfiles-implementation.md

Select an option

No results found

Select an option

No results found

Chezmoi Dotfiles Management Implementation Plan

Summary

Problem

Proposed Solution

Architecture

Primary System

Directory Structure

What's Managed

Template Strategy

System-Specific Directories

Implementation Phases

Phase 1: Install Chezmoi & Initialize with Existing Repo

Phase 2: Create Directory Structure

Phase 3: Migrate Core Shell Configurations

Phase 4: Migrate Application Configurations

Phase 5: Handle System-Specific Differences

Phase 6: Add Installation Scripts

Phase 7: Git Integration (Using Existing Remote)

Phase 8: Test on Vanguard

Phase 9: Future Systems (Home Windows, WSL2, Remote Linux)

Phase 10: Documentation

What's Managed

Template Variables

Primary System