Chezmoi Guide: Manage Dotfiles Across Multiple Machines

Maintaining consistent dotfiles across multiple machines is one of those problems that seems minor until you've spent an afternoon wondering why your shell aliases work on your work laptop but not your home machine. Chezmoi solves this by managing your dotfiles in a Git repository and giving you the tooling to keep every machine in sync — with support for templates, encrypted secrets, and one-command bootstrapping on a new system.

Installing Chezmoi

macOS (Homebrew): bash brew install chezmoi

Debian/Ubuntu: bash sudo apt install chezmoi

Universal install script (any platform): bash sh -c "$(curl -fsLS get.chezmoi.io)"

The install script places a binary in ~/.local/bin/chezmoi or wherever your $PATH points. Verify it's working:

chezmoi --version

Getting Started

Initialize chezmoi with:

chezmoi init

This creates a source directory at ~/.local/share/chezmoi/ — this is where chezmoi stores managed versions of your dotfiles. It's a Git repository by default, so you can push it to GitHub or any Git host to sync across machines.

Add a dotfile to chezmoi's management:

chezmoi add ~/.zshrc
chezmoi add ~/.gitconfig
chezmoi add ~/.config/starship.toml

This copies each file into the source directory. To edit a managed file, always edit through chezmoi so it tracks the canonical version:

chezmoi edit ~/.zshrc

After editing, apply your changes to the actual files in your home directory:

chezmoi apply

To see what changes would be applied before committing:

chezmoi diff

This shows a diff between your current home directory files and what chezmoi would apply — useful for reviewing changes before they take effect.

Using Templates for Machine-Specific Configuration

The real power of chezmoi comes from templates. If you have configuration that should differ between machines — like a different Git email for work versus personal projects — you can use chezmoi's templating syntax rather than maintaining separate dotfiles.

Rename a managed file to add the .tmpl extension:

mv ~/.local/share/chezmoi/dot_gitconfig ~/.local/share/chezmoi/dot_gitconfig.tmpl

Then use Go template syntax inside the file:

[user]
  name = Your Name
  {{- if eq .chezmoi.hostname "work-macbook" }}
  email = you@company.com
  {{- else }}
  email = you@personal.com
  {{- end }}

Chezmoi exposes machine data like chezmoi.hostname, chezmoi.os, and chezmoi.arch as template variables. You can also define your own variables in ~/.config/chezmoi/chezmoi.toml:

[data]
  name = "Your Name"
  work = false

And reference them in templates as .name, .work, and so on.

Encrypting Secrets With Age

Dotfiles often contain sensitive data — API tokens, SSH passphrases, or application credentials. Chezmoi integrates with age for encrypting files at rest in your source repository.

Install age (brew install age), then configure chezmoi to use it:

[age]
  identity = "~/.config/chezmoi/key.txt"
  recipient = "age1..."

Generate a key with age-keygen -o ~/.config/chezmoi/key.txt. From there, chezmoi add --encrypt ~/.ssh/config adds the file in encrypted form. The decrypted version is only ever written to your home directory — the repository only contains the encrypted blob.

Syncing Across Machines

The one-liner to bootstrap chezmoi on a new machine from your existing dotfiles repository:

chezmoi init --apply https://github.com/username/dotfiles.git

This clones your dotfiles repository, runs the templating engine for the current machine, and applies everything in one step. A fresh machine goes from zero to your full development environment in under a minute.

After making changes on any machine:

chezmoi cd          # Navigate to source directory
git add -A
git commit -m "Update zshrc"
git push

On another machine:

chezmoi update      # Pull from Git and apply changes

Chezmoi + DeployHQ: Consistent Environments for Reliable Deployments

One of the underappreciated benefits of managing your dotfiles with chezmoi is that your deployment workflow becomes more predictable. When every developer on a team has consistent SSH key management, Git configuration, and tooling across their machines, deployments behave the same way regardless of who triggers them.

DeployHQ sits on the deployment side of this workflow. Once your code is pushed to Git, DeployHQ handles getting it to production — SSH, SFTP, or cloud providers — with configurable build commands, environment variables, and automatic deployments via webhook.

The combination is particularly effective for teams: chezmoi ensures every developer's local environment is set up consistently (SSH keys, Git config, editor settings, shell aliases), and DeployHQ ensures the deployment pipeline is automated and repeatable. There's no "it works on my machine" when both sides of the workflow are managed.

For a new team member, the onboarding flow becomes: 1. chezmoi init --apply https://github.com/your-org/dotfiles.git to set up the local environment 2. Connect to the team's DeployHQ account to get access to existing deployment pipelines 3. Push code to the shared repository and DeployHQ handles the rest

Ready to automate your deployments? Sign up for DeployHQ to connect your Git repository and start shipping reliably. Questions? Reach us at support@deployhq.com or on Twitter at @deployhq.