Skip to content

2. Adoption of Chezmoi for Dotfile Management

Date: 2024-11-15

Status

Accepted

Context

Managing dotfiles across multiple machines and operating systems (WSL2, Arch Linux, Ubuntu, macOS) requires a solution that handles:

  1. Cross-platform differences — Different package managers, system paths, and OS-specific configurations
  2. Secret management — API tokens, SSH keys, and credentials must be encrypted in the repository
  3. Idempotency — Safe to run repeatedly without side effects
  4. Version control — Track changes over time with clear history

Alternatives considered:

  • GNU Stow — Simple symlink farm, but no templating or encryption
  • yadm — Feature-rich but heavy reliance on Git hooks, less intuitive
  • Bare Git Repository — Maximum flexibility but requires manual encryption setup and no templating

Decision

We have adopted Chezmoi as the dotfile management system.

Consequences

Positive

  • Template Support — Use Go templates to adapt configs based on OS, hostname, or custom variables
  • Native Encryption — Built-in age encryption support (see ADR-004)
  • Diff/Merge Handling — Visual diffs before applying changes with delta integration
  • Active Community — Well-maintained, comprehensive documentation, broad platform support
  • Declarative Data — .chezmoidata.yaml provides clean separation of config variables
  • Auto-sync — Can commit and push changes automatically via chezmoi apply

Negative

  • Learning Curve — Template syntax and special file naming conventions require familiarization
  • Indirection — Source files live in ~/.local/share/chezmoi, not directly in $HOME

Trade-offs

  • Complexity vs Power — More complex than Stow, but provides essential features for multi-platform management
  • Lock-in — Migration to another system would require rewriting templates, but this is acceptable given the value provided

Implementation Details

  • Source Directory: ~/.local/share/chezmoi
  • Template Data: .chezmoidata.yaml for OS detection and user preferences
  • Ignored Files: .chezmoiignore for platform-specific exclusions and home-directory hygiene (exclude non-dot repo artifacts)
  • Version File: .chezmoiversion pins the minimum required Chezmoi version

References