Skip to main content

145. Chezmoi for Dotfiles Management

Status: Accepted Date: 2025-07-06

Context​

Given our decision to separate infrastructure and dotfiles (adr://dotfiles-separation), we need a tool to manage the deployment of our personal dotfiles from a Git repository to our home directory.

A simple shell script with git clone and ln -s (symlinking) can work, but it's often brittle. It doesn't easily handle templating (e.g., for machine-specific settings), managing files that shouldn't be symlinked (like SSH keys), or securely managing secrets. We need a more robust and feature-rich tool.

Decision​

We have chosen to use chezmoi as our standard dotfiles management tool.

chezmoi is a powerful, flexible, and secure dotfiles manager. The 27_chezmoi Ansible role is responsible for installing the chezmoi binary and then executing chezmoi apply to initialize the user's environment from their private dotfiles repository, which is expected to be chezmoi-compatible.

Key features of chezmoi that informed this decision include:

  • Declarative Approach: You declare the desired state of your home directory in a Git repo, and chezmoi makes it so.
  • Templating: Supports templating of config files, allowing for machine-specific configurations from a single source.
  • Secrets Management: Has built-in support for securely managing secrets using various backends (e.g., system keyring, 1Password, etc.).
  • Not Just Symlinks: Can manage files as symlinks, regular files, or scripts to be run, providing flexibility.

Consequences​

Positive:

  • Robust and Reliable: chezmoi is a mature, well-regarded tool that handles many of the edge cases of dotfile management gracefully. It is far more robust than a collection of custom shell scripts.
  • Enables Complex Configurations: The templating and secret management features allow us to maintain sophisticated, multi-machine configurations from a single, clean source repository.
  • Idempotent: The chezmoi apply command is idempotent. It can be re-run safely at any time to ensure the home directory is in the state declared in the repository.
  • Standardization: By standardizing on chezmoi, we create a consistent pattern for dotfile management across the team.

Negative:

  • Learning Curve: chezmoi has its own concepts and command-line interface that users need to learn. It's more complex than a simple symlinking script.
  • Opinionated Structure: Requires the dotfiles repository to be structured in the way chezmoi expects (e.g., using dot_ prefixes for files that should have a . prefix in the destination).

Mitigation:

  • A Worthwhile Investment: The learning curve is relatively shallow, and the power and reliability it provides are well worth the initial time investment.
  • Convention Over Configuration: The opinionated structure is a feature. It provides a clear, documented, and consistent way to organize a dotfiles repository, which is a benefit in the long run. Good documentation and team knowledge sharing will mitigate any initial friction.