Your Dotfiles, Every Machine, One Command

Setting up a new machine usually means hours of tweaking configurations, reinstalling tools, and manually copying dotfiles from another computer. What if a single command could reproduce your entire environment, complete with secrets pulled from your password manager and templates that adapt to each host? That is exactly what chezmoi promises, and after years of quiet evolution, it has become one of the most starred projects in its category.

Chezmoi solves the multi-machine dotfiles problem that raw Git cannot handle on its own. Templates adapt per host, secrets stay in your password manager, and one command deploys everything. The trade-off is a real learning curve, but it pays off the next time you provision a fresh machine.

Why this matters

If you have ever spent an afternoon reconfiguring a new laptop, copying dotfiles from another machine, and still missing something important, you know the pain. Chezmoi is not the only dotfiles manager out there, but it is the one that takes the multi-machine problem seriously. Here you will find out how it works, where it beats raw Git, and where the complexity tax kicks in.

The problem with raw Git

Most Linux users eventually discover that their dotfiles belong in a Git repository. It works, up to a point. The moment you own more than one machine, cracks appear. A desktop with an Nvidia GPU needs different settings than a laptop running AMD. A triple-monitor workstation has nothing in common with a single-screen laptop. Branch-per-machine quickly turns into a maintenance nightmare: merges pile up, changes made on one branch never reach the others, and soon you are managing repositories instead of configurations.

How chezmoi works

Chezmoi treats your home directory as the target and keeps a separate source directory (a Git repo) that holds the desired state of every managed file. When you run chezmoi apply, the engine renders every template, fetches secrets from your password manager, and writes the final files into place.

Adding and editing files

The basic workflow is straightforward:

• chezmoi add ~/.bashrc copies the file into the source directory and starts tracking it
• chezmoi edit ~/.bashrc opens the source version in your editor, whether it is a plain file or a template
• chezmoi cd drops you into the source directory so you can use Git directly
• chezmoi diff shows what would change before you apply it

Every change is version-controlled through Git, so you get the full history of your configurations with no extra effort.

Templates that adapt per host

This is where chezmoi outshines a plain Git setup. By appending .tmpl to a filename, you turn it into a Go template that can reference system properties such as hostname, OS, and architecture. A single .bashrc.tmpl can produce different outputs on every machine:

{{- if eq .chezmoi.hostname "workstation" }}
export DISPLAY=:0
{{- else if eq .chezmoi.hostname "laptop" }}
export DISPLAY=:0
{{- end }}

Consider an OBS configuration file as a template. On a machine with an Nvidia GPU, the template enables NVENC hardware encoding; on everything else, it falls back to software encoding. No branches, no manual edits per host, no forgotten differences.

Secret management without leaks

Dotfiles often contain sensitive data: API keys, SSH private keys, access tokens. Committing those to a Git repository, even a private one, is a security risk. Chezmoi solves this by integrating directly with password managers.

Consider pulling an SSH private key from Bitwarden using bitwarden_attachment_by_reference. The template references the secret at render time; the secret itself never touches the Git repository. The result is a dotfiles setup that is both portable and secure by default.

Tips and tricks

A few practical patterns that make daily use smoother:

• chezmoi merge resolves conflicts when both the source state and the target file have changed, giving you a three-way merge similar to Git
• chezmoi data prints all available template variables, invaluable when you are writing templates and need to know what properties are accessible
• chezmoi doctor runs diagnostics on your setup, checking that all integrations (Git, password managers) are working correctly
• External tool integration: chezmoi can run scripts before and after applying changes, so you can bootstrap package managers, install fonts, or set permissions as part of the same workflow
• chezmoi init-apply: one-command deployment. On a fresh machine, running chezmoi init-apply https://github.com/yourname/dotfiles clones your repo and applies everything in a single step

Who is chezmoi for?

The honest answer: power users who manage multiple Linux (or macOS, or Windows, or FreeBSD) machines and are comfortable with Git and the command line. If you have never felt the pain of reconfiguring a new laptop from scratch, chezmoi will feel like overkill. But if the phrase “let me just set up my environment” fills you with dread, it might be exactly what you need.

The technical details

From here on, this gets technical. If you are interested in the idea more than the implementation, you can skip to the conclusion.

Template variables and system detection

Chezmoi exposes a wide range of template variables through the .chezmoi object. The most commonly used include:

• .chezmoi.hostname - the machine’s hostname
• .chezmoi.os / .chezmoi.arch - operating system and CPU architecture
• .chezmoi.kernel.osrelease - kernel release string, useful for Linux-specific logic
• .chezmoi.username - the current user

These variables allow a single template to branch on any system property. Combined with the external tool integration (scripts that run pre-apply or post-apply), you can build dotfiles that not only adapt content per machine but also trigger machine-specific bootstrapping.

Source directory structure

The source directory uses a deterministic naming convention that encodes metadata:

• dot_bashrc becomes .bashrc (the dot_ prefix maps to a dot)
• private_*.tmpl marks a file as both private and templated
• Directories like exact_* enforce that only the files chezmoi manages exist in the target directory

This naming scheme is one of the main sources of confusion for newcomers, since the source tree looks nothing like the home directory it produces. The chezmoi cd and chezmoi edit commands abstract most of it away, but understanding the mapping is essential when debugging templates.

The sponsor segment

Worth mentioning alongside chezmoi is InternXT, a European open-source cloud storage provider. InternXT offers end-to-end zero-knowledge encryption, GDPR compliance, ISO 27001 certification, and support for Rclone and WebDAV. It also features file versioning and post-quantum cryptography. It is worth noting that this is an advertisement, not an editorial endorsement.

The bottom line

Key points:

• Chezmoi handles multi-machine dotfiles with per-host templates and first-class password manager integration, something raw Git simply cannot do
• The learning curve is real: Go templates and the source directory naming convention take time to internalize
• One command (chezmoi init-apply) deploys a fully configured environment on a fresh machine, secrets included

Managing dotfiles across machines is a solved problem, but only if you are willing to invest in the tooling. Chezmoi is the most complete answer so far; the question is whether you need that level of completeness.

• chezmoi official site
• chezmoi on GitHub
• chezmoi documentation