What Is Chezmoi? The Beginner's Guide to Managing Dotfiles Across Machines

CodexFuse Team · 2026-11-04T13:01:45.918Z · 12 min read min read

What Is Chezmoi? The Beginner's Guide to Managing Dotfiles Across Machines

If you have ever wondered what is chezmoi and why developers mention it whenever dotfiles come up, here is the short version: chezmoi is a single Go binary that manages the hidden configuration files in your home directory — your shell config, your Git identity, your editor settings — in a Git repository, and then renders them correctly on every machine you own. The newest release, 2.74.0, shipped on November 1, 2026. Git stays the version-controlled source of truth for everything, and our Git beginner guide covers that half of the workflow; chezmoi handles the half Git cannot do alone, turning one committed source into the right files for each machine.

This guide explains chezmoi from zero: the three-state model that makes every command click, the one-command way to take over a machine you already use, Go templates for per-machine differences, secrets that stay encrypted, the single-command bootstrap for a fresh machine, and how chezmoi compares to Stow, yadm, and dotbot. Every behavior below was checked against the official docs or captured from a real chezmoi 2.74.0 session run on 2026-11-04.

What Is Chezmoi, Exactly?

The direct answer: chezmoi is a dotfile manager that keeps the desired state of your personal configuration files in a Git repository — the source state, stored in ~/.local/share/chezmoi — and renders that desired state into your home directory on each machine, using Go templates for machine differences, encryption or password-manager lookups for secrets, and scripts for everything else. It is distributed as a single statically-linked binary with no dependencies, not even git or Python, and it needs no root access, so it runs on Linux, macOS, and Windows alike.

The mental shift is small but important. Most dotfile managers either symlink files from a repo into your home directory or expect you to maintain a bare Git repo in $HOME. Chezmoi does neither: it calculates what each dotfile should contain on this machine and then makes the minimum changes required to get there. That is why it does not symlink like Stow — it renders real files into your home directory, which means your configs keep working even where symlinks cause trouble, and each machine can get slightly different content from the same committed source.

How Does Chezmoi's Three-State Model Work?

The direct answer: every chezmoi command is one of three comparisons between three states — the source state, the target state, and the destination state. Learn the three states once and every command reads like plain English.

The target state is the useful extra layer. On one machine, a dot_gitconfig.tmpl template can render your work email and company signing key; on another, the same committed template renders your personal identity. chezmoi diff compares the calculated target with the current destination and shows you what would change. chezmoi apply makes the destination match the target, touching only what differs. Two flags from the quick-start guide are worth memorizing early: -v prints exactly what a command will change, and -n is a dry run that changes nothing — the combination is how you preview before you commit to anything.

How Do You Start Using Chezmoi on Your Current Machine?

The direct answer: install the binary, run chezmoi init, adopt files one at a time with chezmoi add, preview with chezmoi diff, apply, then commit and push like any Git project. Five steps, no restructuring of your life required.

1. Install chezmoi from your package manager or with the installer one-liner. It needs no root access.
2. Initialize with chezmoi init — this creates a fresh Git repository in ~/.local/share/chezmoi where chezmoi stores its source state.
3. Adopt a file with chezmoi add ~/.bashrc. This copies the file into the source state as dot_bashrc (the dot_ prefix is how chezmoi encodes the leading dot).
4. Preview and apply with chezmoi diff, then chezmoi apply -v to write the changes, verbosely.
5. Commit and push: chezmoi cd opens a shell in the source directory, where git add, git commit, and git push work exactly as usual. Push to a repo called dotfiles on your Git host of choice.

Here is that loop captured for real on 2026-11-04, with chezmoi v2.74.0 bootstrapping a demo repo that contains one template (dot_gitconfig.tmpl) and one plain file (dot_bashrc):

$ chezmoi version v2.74.0, commit fcc38cf6fdb3a79ae4afae9ef6ad241890db6cde, built at 2026-11-01T13:53:24Z, built by goreleaser

$ chezmoi init --apply /path/to/dotfiles-repo
Cloning into '/home/user/.local/share/chezmoi'...
done.

$ cat ~/.gitconfig
[user]
    name = "Ada Tester"
    email = "[email protected]"
    # rendered on htch-runtime / linux

$ chezmoi managed
.bashrc
.gitconfig

$ chezmoi source-path ~/.gitconfig
/home/user/.local/share/chezmoi/dot_gitconfig.tmpl

Two things in that transcript deserve a second look. The # rendered on htch-runtime / linux line came from a template containing {{ .chezmoi.hostname }} / {{ .chezmoi.os }} — the same committed source renders a different comment on every machine. And chezmoi managed lists exactly the files chezmoi owns, while chezmoi source-path traces any destination file back to its source, which is how you find what to edit when something looks wrong.

The safety loop closes the same way. Edit ~/.bashrc by hand, and chezmoi notices immediately:

$ chezmoi status
MM .bashrc

$ chezmoi diff
diff --git a/.bashrc b/.bashrc
--- a/.bashrc
+++ b/.bashrc
@@ -1,3 +1,2 @@
 alias ll='ls -la'
 export EDITOR=vim
-alias gs='git status'

The MM flag means the file differs from both the source and the last-applied state — your cue to either fold the change back in with chezmoi re-add or overwrite it with chezmoi apply. Nothing is ever a mystery: diff shows it, status flags it.

What Do Templates Change About Dotfiles?

The direct answer: templates let one committed file produce different content per machine, which is the entire reason chezmoi exists. Any source file ending in .tmpl is rendered as a Go template at apply time, with a rich .chezmoi variable exposing the machine's hostname, OS, OS release, architecture, username, and home directory.

In practice this kills the oldest dotfiles headache: maintaining three near-identical configs for work, home, and server. One dot_gitconfig.tmpl can branch on .chezmoi.hostname or .chezmoi.os and emit the right identity everywhere, from a single commit. The naming system around templates is precise and worth learning as a table, because the source directory's filenames are the whole manifest — there is no separate config file to maintain:

The run_onchange_ prefix is the quiet superpower: a package-install script only re-runs when the package list itself changes, so applying your dotfiles stays idempotent instead of reinstalling the world every time.

How Does Chezmoi Handle Secrets?

The direct answer: never commit plaintext secrets — chezmoi gives you two safe routes, and you should pick one before your first commit. The first is full-file encryption with age, GPG, git-crypt, or transcrypt, so encrypted blobs live in the repo and only your machines can read them. The second is password-manager integration: templates can pull values from 1Password, Bitwarden, KeePassXC, Vault, AWS Secrets Manager, and more at apply time, so the unencrypted value never exists in Git at all.

The encryption route pairs naturally with age, the modern file-encryption CLI — our age encryption guide walks through keypairs, recipients, and passphrase mode from zero, and chezmoi's age integration means an encrypted file in your source state decrypts transparently when applied. The password-manager route is the better fit when secrets already live in a vault your team shares: the template renders the live value on each machine, and a public dotfiles repo stays public without leaking anything. Either way, the rule is one sentence: secrets are encrypted or fetched, never committed as text.

What Happens on Your Second Machine?

The direct answer: one command clones the repo, renders the templates, and writes everything to $HOME — the famous single-command bootstrap that makes a fresh machine feel like home in minutes.

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

If your repo is called dotfiles on GitHub, that shortens to chezmoi init --apply $YOUR_GITHUB_USERNAME, and private repos use the SSH form chezmoi init --apply [email protected]:$YOUR_GITHUB_USERNAME/dotfiles.git. Cautious users split it in two — chezmoi init, then chezmoi diff to preview, then chezmoi apply -v — and there is even a full installer one-liner that puts chezmoi itself plus your dotfiles onto an empty machine in one shot. From then on, every machine stays in sync with a single command: chezmoi update -v pulls the latest source and applies it.

If your "second machine" is a fresh Linux server rather than a laptop, the same bootstrap applies the moment you can SSH in — our VPS hosting guide covers what that machine is and how to reach it, and chezmoi is exactly the kind of tool that makes a new VPS feel configured in one command instead of one afternoon.

Chezmoi vs Stow vs Yadm vs Dotbot: Which One Fits?

The direct answer: pick by how much per-machine variation and secrecy you need. Chezmoi wins when one repo must serve different machines and secrets must stay out of Git; the others win on simplicity when every machine is identical.

The one-line version from a developer who switched: Stow is pure symlinks with no templating, yadm wraps Git with templating via plugins, dotbot needs a YAML manifest — chezmoi bundles templating, encryption, and scripts into one binary. If your machines are truly identical and you will never have a secret in a config file, Stow's simplicity is honest. The moment a work laptop and a home desktop need different Git identities, or an API key has to live in a config, chezmoi's template-and-secrets layering pays for itself.

Sources

Every technical claim on this page was verified against these sources on 2026-11-04:

1. chezmoi.io, official homepage — version 2.74.0 (released 2026-11-01), pronunciation /ʃeɪ mwa/, single statically-linked binary with no dependencies and no root required, the init --apply bootstrap one-liner, chezmoi update, encryption via age/GPG/git-crypt/transcrypt, template and password-manager support. Fetched 2026-11-04.
2. chezmoi.io, Quick start guide — source state in ~/.local/share/chezmoi, the add/edit/diff/apply loop, -v/-n flags, the $YOUR_GITHUB_USERNAME shorthand, SSH form for private repos. Fetched 2026-11-04.
3. blog.hofstede.it, "Chezmoi and Git: Dotfiles Without Pretending Every Machine Is the Same" — the three-state model (source, target, destination), chezmoi diff comparing target with destination, age/rage/GPG encryption, password-manager template values, git.autoCommit/git.autoPush off by default. Updated ~84 days before this article. Fetched 2026-11-04.
4. dev.to (recca0120), "chezmoi: One Dotfiles Repo Across macOS, Linux, and Windows" — chezmoi vs Stow vs yadm vs dotbot, the init --apply URL form, filename-prefix behavior, run_onchange_ content-hash scripts. Published ~205 days before this article. Fetched 2026-11-04.
5. amireslampanah.com, "chezmoi: dotfile management across many machines" — Go binary, dot_/private_/executable_ conventions, .chezmoi template variables (hostname, os, osRelease, arch, username, homedir), secrets rendered at apply time. Published April 2024. Fetched 2026-11-04.
6. probableodyssey.blog, "Dotfile management with Chezmoi and Vim" — the staging-area workflow (add, re-add, chezmoi cd, commit/push, chezmoi update). Published ~459 days before this article. Fetched 2026-11-04.
7. x-cmd.com, "Dotfiles Across Machines a Mess? chezmoi: Templates, Encryption, One Command" — password-manager support list (1Password, Bitwarden, LastPass, KeePassXC, gopass, pass), single-binary design. Fetched 2026-11-04.
8. Author's live terminal session, 2026-11-04 — chezmoi v2.74.0 init --apply transcript, template rendering of {{ .chezmoi.hostname }} / {{ .chezmoi.os }}, managed, source-path, status, and diff outputs quoted verbatim above.

Frequently Asked Questions

Is chezmoi better than just keeping dotfiles in a Git repo?

It is not a replacement — it sits on top of Git. A bare Git repo in your home directory breaks the moment two machines need different contents in the same file, and it has no answer for secrets. Chezmoi keeps Git as the source of truth and adds the two things Git cannot do: render per-machine content from templates and keep secrets encrypted or in a password manager.

Does chezmoi symlink my dotfiles like Stow does?

No — say this once and the whole tool makes sense. Stow symlinks files from a repo into your home directory; chezmoi renders template output as real files in your home directory. That is why one chezmoi source can produce different files on different machines, and why chezmoi diff can show you exactly what would change before anything is written.

Can I keep my dotfiles repo public on GitHub?

Yes, as long as every secret is encrypted with age or GPG or pulled from a password manager at apply time. Public dotfiles repos are common in the chezmoi community precisely because the secrets layer makes them safe. The one rule: plaintext secrets never get committed — check chezmoi diff before your first push.

What happens when I edit a dotfile by hand instead of through chezmoi?

Chezmoi notices on the next run: chezmoi status flags the file (the MM marker in the session above), and chezmoi diff shows the exact difference. Fold a change you want to keep back into the source with chezmoi re-add; run chezmoi apply to overwrite a change you do not want. You never have to use chezmoi edit — editing the source files directly in ~/.local/share/chezmoi works fine too.

Does chezmoi work on Windows and macOS, or only Linux?

All of them. It is a single statically-linked Go binary with no dependencies, so the same binary concept runs on Linux, macOS, and Windows — the per-machine template system is specifically designed for people whose machines span operating systems. No root access is required on any of them.