Getting Started with Chezmoi: Managing Dotfiles the Smart Way
Managing configuration files across multiple systems can quickly become a mess. From terminal preferences to shell settings, we all have a finely-tuned setup that we rely on day-to-day. But how do you keep those settings consistent across machines? And how do you avoid the chaos of losing them after a reinstall?
That’s where a tool like Chezmoi comes in.
What is Chezmoi?
Chezmoi is a powerful dotfile manager designed to track, version, and securely deploy your configuration files across multiple operating systems. It helps you manage configuration files such as ~/.zshrc, ~/.gitconfig, ~/.config/ and more — all with a simple Git workflow.
Unlike traditional symlink managers like GNU Stow, Chezmoi works by maintaining a source state in a Git repository, which it applies to your home directory. This means you can track your dotfiles like code, safely test changes, and even add logic for different operating systems or hosts.
Getting Started
To get started with Chezmoi, install it using your preferred package manager.
On macOS:
1
brew install chezmoi
Ubuntu:
1
sudo apt install chezmoi
Windows:
1
winget install twpayne.chezmoi
Then initialise your dotfiles repository:
1
chezmoi init --apply aut0nate
This command clones your dotfiles repository (e.g. https://github.com/aut0nate/dotfiles) and immediately applies the configuration to your home directory. You can also start fresh by running:
1
chezmoi init
And then begin adding files:
1
2
chezmoi add ~/.zshrc
chezmoi add ~/.config/nvim/init.vim
The Power of Templates
One of Chezmoi’s most useful features is its powerful templating engine. You can create conditional logic in your config files using Go templating syntax.
For example, let’s say you want a slightly different .zshrc on macOS vs Linux:
1
2
3
4
5
{if eq .os "darwin"}
echo "Running on macOS"
{else if eq .os "linux"}
echo "Running on Linux"
{end}
You can also target OS-specific files by using suffixes in your source directory:
1
2
~/.local/share/chezmoi/dot_zshrc.tmpl
~/.local/share/chezmoi/dot_gitconfig.tmpl
Or host-specific files:
1
2
3
4
5
dot_gitconfig.tmpl
└── applies to all systems
[email protected]
└── only applies when the hostname is 'workmachine'
This allows you to have one unified repository that works intelligently across every system you manage. To learn more about templates in Chezmoi click here.
Why Backing Up Config Files Matters
Your dotfiles represent hours — if not years — of customisation. Losing them can feel like losing a part of your workflow.
By using Chezmoi with Git, you:
- Track every change you make to your configs
- Back up your entire setup to GitHub or another Git provider
- Easily restore your environment after a system wipe or when setting up a new machine
- Reduce time spent reconfiguring new environments
Your dotfiles essentially become portable, versioned, and secure — which is especially useful if you work across macOS, Linux, or WSL environments.
My Dotfiles
If you’re curious, you can check out my dotfiles on GitHub. Feel free to fork, clone, or use it for inspiration.
Final Thoughts
Chezmoi has quickly become one of my essential tools. It removes the friction of managing dotfiles and adds the confidence of knowing my setup is always a chezmoi init away.
Whether you’re just getting started or looking to level up your dotfile game, Chezmoi is a great place to begin.