chezmoi — Manage Dotfiles Across Multiple Machines

Introduction

chezmoi manages your dotfiles across multiple machines by maintaining a source directory that serves as the single source of truth. It handles machine-specific differences through templates and securely integrates with password managers for secrets.

What chezmoi Does

• Maintains dotfiles in a versioned source state directory separate from your home directory
• Applies configuration files with Go text/template for machine-specific differences
• Integrates with 1Password, Bitwarden, LastPass, pass, Vault, and system keyrings for secrets
• Supports file encryption via age or GPG for sensitive dotfiles
• Works on Linux, macOS, Windows, and FreeBSD with a single binary

Architecture Overview

chezmoi stores a source state in ~/.local/share/chezmoi (typically a git repo). Each file in the source has a name that encodes attributes (executable, private, template). When you run chezmoi apply, it computes the target state by evaluating templates and comparing against the destination. Only files that differ are written, making applies idempotent and safe.

Self-Hosting & Configuration

• Install via Homebrew, Scoop, apt, pacman, nix, or download the binary directly
• Initialize with chezmoi init which creates the source directory and optionally clones a dotfiles repo
• Configure in ~/.config/chezmoi/chezmoi.toml for merge tool, diff command, and secrets manager integration
• Use .chezmoiignore to exclude files per OS or hostname
• Run chezmoi update on each machine to pull and apply the latest changes from your repo

Key Features

• Template system handles OS, hostname, and architecture differences in a single repo
• Secrets never appear in plaintext in the source repository
• Declarative desired-state model means partial applies and rollbacks are trivial
• Built-in chezmoi diff previews changes before applying
• Supports running scripts on apply for tasks like installing packages or reloading services

Comparison with Similar Tools

• GNU Stow — symlink-based; chezmoi copies files, enabling templates and encryption
• yadm — thin git wrapper; chezmoi adds templates, secrets, and cross-OS support
• dotbot — YAML-driven symlinker; chezmoi handles file content transformation
• rcm — tag-based organization; chezmoi uses attribute-encoded filenames for more granular control
• Nix Home Manager — full declarative system; chezmoi is lighter and does not require Nix

FAQ

Q: How do I handle different configs for work and personal machines? A: Use template conditionals on .chezmoi.hostname or custom data variables defined in chezmoi.toml.

Q: Can I use chezmoi with an existing dotfiles repo? A: Yes. Run chezmoi import or manually place files in the source directory and add them with chezmoi add.

Q: Does chezmoi overwrite local changes? A: By default it warns about conflicts. Use chezmoi merge to three-way merge or configure auto-merge behavior.

Q: How do I share some dotfiles publicly but keep secrets private? A: Encrypt sensitive files with age or GPG, or pull secrets at apply-time from a password manager.

Sources

• https://github.com/twpayne/chezmoi
• https://www.chezmoi.io/user-guide/command-overview/