Installing the chezmoi command
Before you can start using the chezmoi command, you need to install it. The tool is written in Go, which means it ships as a single binary with no dependencies. That is one of the things I like about it.
On Debian and Ubuntu systems, the easiest way is through the official APT repository:
sudo apt update
sudo apt install chezmoi
For Arch Linux, you can grab it from the AUR or community repo:
sudo pacman -S chezmoi
There is also a curl-based one-liner for any Linux distro:
sh -c "$(curl -fsLS get.chezmoi.io)"I prefer the package manager approach since it keeps the tool updated. After installation, check the version to confirm everything works:
chezmoi --versionThe project lives on GitHub if you want to browse the source or report an issue. Note that Fedora and RHEL users can install it through COPR, and Homebrew works on Linux too if you already use it.
brew install chezmoiEssential chezmoi command Features for Daily Use
The chezmoi command wraps your home directory in a git repo. Every change you make to a config file is tracked. You can sync settings across multiple machines without cluttering each one. Here are the key features I reach for every day.
What sets this tool apart from manual approaches is how it handles the full lifecycle. You add a file, preview the diff, apply the change, commit it, and push it to a remote. That whole loop takes about 10 seconds once you get the hang of it.
1. Initialize Your Dotfiles Directory
Run chezmoi init to set up a new dotfile repo. This creates a ~/.local/share/chezmoi directory and copies your existing config files into it. You can point it at an existing GitHub repo right away:
chezmoi init https://github.com/yourname/dotfiles.gitThe chezmoi command does not overwrite your current files during init. It only stages the files for review. That keeps you safe from accidents.
2. Add a File to Management
Want to track a new config file? Use chezmoi add:
chezmoi add ~/.bashrc
chezmoi add ~/.config/nvim/init.luaThe source files land in your chezmoi directory with a clean copy of the original. The tool preserves permissions and symlinks, which is something I have not seen other dotfile managers handle well.
3. Preview Changes Before Applying
Run chezmoi diff to see what would change before you commit. This is the step most people skip and then regret. The output looks like a standard git diff:
chezmoi diffIf something looks wrong, you can edit the source file and reapply. No harm done. I use this before every apply to catch formatting issues.
4. Apply Changes to Your Home Directory
chezmoi apply writes the managed files to their actual locations. It creates backups of files it replaces:
chezmoi applyThe chezmoi command is smart about this. If a destination file has changed since you last applied, it shows a conflict and asks what to do. You can also pass --force to skip the warnings.
5. Edit a Managed File
chezmoi edit opens the source version of a file in your editor. The path is relative to your home directory:
chezmoi edit ~/.bashrcThis is faster than navigating the source directory yourself. After editing, run chezmoi diff and chezmoi reapply to preview and push the change live.
6. Manage Templates with Variables
This is where the chezmoi command really shines. You can template config files so each machine gets its own values. File names ending in .tmpl are processed through Go templates:
# ~/.local/share/chezmoi/dot_bashrc.tmpl
export EDITOR="{{ if eq .chezmoi.os "linux" }}nvim{{ else }}vim{{ end }}"
You set variables in ~/.config/chezmoi/chezmoi.toml. The tool picks the right template per machine based on OS, hostname, and architecture.
7. Sync Across Machines with Git
The source directory is a git repo. Commit your changes and push them:
chezmoi git add .
chezmoi git commit -m "added nvim config"
chezmoi git pushOn a new machine, run chezmoi init --apply with the same repo URL. It pulls everything down and applies it in one go. I have my MacBook and my Linux server sharing the same bashrc this way.
8. Manage Secrets with Pass or GPG
The chezmoi command handles encrypted files through age, gpg, or your password manager. You can mark a file for encryption during add:
chezmoi add --encrypt ~/.ssh/id_ed25519The encrypted blob is stored in the repo. Only machines with the right key can decrypt it. This is safer than keeping secrets in a private repo.
9. Remove a File from Management
Need to stop tracking a file? Use chezmoi forget:
chezmoi forget ~/.bashrcThe local file stays untouched. Only the source copy in the chezmoi directory is removed. If you want to delete the file from disk too, use chezmoi remove instead.
10. Reapply the Latest State
chezmoi reapply is the Swiss army knife. It runs through every managed file, checks if the source changed, and updates the destination. Use it after pulling new changes from a remote:
chezmoi reapplyYou can also target a single file with chezmoi reapply ~/.gitconfig. This cuts down the wait time when you only changed one thing.
Why the chezmoi command Beats Manual Symlinks
I used to manage dotfiles with a bare git repo and manual symlinks. It worked but it was fragile. A stray rm -rf in the wrong directory broke my setup more than once. The chezmoi command takes that risk away.
It gives you a diff preview before each apply. It backs up conflicting files. It handles templates, secrets, and permissions better than anything else I have tried. If you manage more than one Linux machine, it is worth the switch.
There is also the question of onboarding a new machine. With symlinks, I had to clone the repo, run a setup script, and pray nothing broke. With chezmoi, one command pulls everything down and applies it. I timed it on a fresh Hetzner VPS recently. From a blank SSH session to a fully configured shell with bashrc, nvim, gitconfig, and tmux settings took under two minutes.
For more on terminal productivity, check out my guides on ripgrep and tmux. Both tools pair well with a chezmoi-managed dotfile setup. Have a look at the official chezmoi documentation for advanced topics like script execution ordering and file permissions.