Chezmoi: Manage Your Dotfiles Across Multiple Machines

TL;DR — Quick Summary

Chezmoi manages dotfiles across multiple machines securely. Templates for per-machine config, encrypted secrets, and automatic Git sync.

Chezmoi solves the dotfiles problem properly. Instead of fragile symlinks or manual copying, it manages your configs with templates, encrypted secrets, and Git sync — so your terminal setup follows you to every machine.

Installation

# macOS
brew install chezmoi

# Arch Linux
sudo pacman -S chezmoi

# Universal installer
sh -c "$(curl -fsLS get.chezmoi.io)"

# Verify
chezmoi --version

Quick Start

# Initialize (creates ~/.local/share/chezmoi/)
chezmoi init

# Add existing dotfiles
chezmoi add ~/.bashrc
chezmoi add ~/.gitconfig
chezmoi add ~/.config/starship.toml
chezmoi add ~/.ssh/config

# Edit a managed file
chezmoi edit ~/.bashrc

# Preview changes before applying
chezmoi diff

# Apply changes to home directory
chezmoi apply

# Push to Git
chezmoi cd  # enters source directory
git add . && git commit -m "Add dotfiles" && git push

Templates (Per-Machine Config)

Create ~/.local/share/chezmoi/dot_bashrc.tmpl:

# Common config
export EDITOR=helix
alias ll='ls -la'

{{ if eq .chezmoi.os "linux" -}}
# Linux-specific
alias open='xdg-open'
export PATH="$HOME/.local/bin:$PATH"
{{ end -}}

{{ if eq .chezmoi.os "darwin" -}}
# macOS-specific
export PATH="/opt/homebrew/bin:$PATH"
eval "$(/opt/homebrew/bin/brew shellenv)"
{{ end -}}

{{ if eq .chezmoi.hostname "work-laptop" -}}
# Work machine
export HTTP_PROXY=http://proxy.company.com:8080
{{ end -}}

Encrypted Secrets

# Set up age encryption
chezmoi age keygen -o ~/.config/chezmoi/key.txt

# Add to chezmoi config
chezmoi edit-config
# Add: [age] identity = "~/.config/chezmoi/key.txt"

# Add encrypted file
chezmoi add --encrypt ~/.ssh/id_ed25519

New Machine Setup

# One command to set up a new machine:
chezmoi init --apply your-github-username

# This clones your dotfiles repo and applies everything

Comparison

Feature	Chezmoi	Stow	YADM	Bare Git
Method	Copy	Symlink	Git	Git
Templates	Yes	No	Jinja	No
Encryption	age/gpg/1P	No	gpg	No
Multi-OS	Templates	Manual	Alt files	Manual
Git built-in	Yes	No	Yes	Yes
One-line setup	Yes	No	Yes	No

Summary

Chezmoi manages dotfiles by copying with template support — not symlinks
Templates for per-machine, per-OS customization using Go template syntax
Encrypted secrets via age, gpg, 1Password, Bitwarden, and more
One-command setup on new machines: chezmoi init —apply username
Built-in Git integration for syncing across machines

Guide & Instructions

Estimated Time: 15m

Tools Needed:

Chezmoi
Git
Terminal

Install Chezmoi

Install with brew install chezmoi, pacman -S chezmoi, or sh -c $(curl -fsLS get.chezmoi.io).

Initialize

Run chezmoi init to create a source directory at ~/.local/share/chezmoi. This is your dotfiles repo.

Add dotfiles

Run chezmoi add ~/.bashrc to track .bashrc. Chezmoi copies it to the source directory.

Edit and apply

Use chezmoi edit ~/.bashrc to edit the source version, then chezmoi apply to update the actual file.

Push to Git

Run chezmoi cd to enter the source directory, then git add, commit, and push. On a new machine: chezmoi init --apply your-github-username.

Frequently Asked Questions

What is Chezmoi?

Chezmoi is a dotfiles manager that helps you manage configuration files (dotfiles) across multiple machines. It uses templates for per-machine customization, supports encrypted secrets, and syncs via Git.

How is Chezmoi different from GNU Stow?

GNU Stow uses symlinks which can cause issues with some programs. Chezmoi copies files with template support, handles secrets encryption, supports per-machine configs via templates, and has built-in Git integration.

Can Chezmoi handle secrets?

Yes, Chezmoi integrates with age, gpg, 1Password, Bitwarden, LastPass, Vault, and macOS Keychain for encrypting sensitive data in your dotfiles repo.

Does Chezmoi work on multiple OS?

Yes, use templates to have different configs per OS: {{ if eq .chezmoi.os "linux" }} for Linux-specific content, {{ if eq .chezmoi.os "darwin" }} for macOS.