How to Setup Chezmoi - Dotfiles Manager

Managing dotfiles across multiple machines can be a pain. Chezmoi is a great tool that helps you manage your dotfiles securely across multiple machines. In this post, I'll walk you through how to set it up, add your dotfiles, push them to GitHub, and pull them on a new machine.

Installation

On macOS, you can install chezmoi using Homebrew:

brew install chezmoi

For other operating systems, check the official installation guide for one-line package install options.

Initial Setup

Once installed, initialize chezmoi:

chezmoi init

This creates a new git repository in ~/.local/share/chezmoi where chezmoi will store the source state of your dotfiles.

Adding Your Dotfiles

You can start adding your dotfiles using the chezmoi add command. For example, to add your .zshrc:

chezmoi add ~/.zshrc

This will copy ~/.zshrc to ~/.local/share/chezmoi/dot_zshrc. You can add as many dotfiles as you want.

Editing Dotfiles

If you want to edit the source version of a dotfile, use:

chezmoi edit ~/.zshrc

This will open ~/.local/share/chezmoi/dot_zshrc in your $EDITOR. Make your changes and save the file.

Reviewing and Applying Changes

To see what changes chezmoi will make to your home directory:

chezmoi diff

If you're happy with the changes, apply them:

chezmoi -v apply

Pushing to GitHub

To keep your dotfiles synced across machines, you need to push them to a GitHub repository. First, navigate to the chezmoi directory:

chezmoi cd

If you don't have a repository yet, create an initial commit and push to a new GitHub repository called dotfiles:

git add .
git commit -m "Initial commit"

Then create a new repository on GitHub called dotfiles and push:

git remote add origin git@github.com:$GITHUB_USERNAME/dotfiles.git
git branch -M main
git push -u origin main

From now on, whenever you make changes, just run chezmoi cd, commit and push your updates.

One-Line Setup on a New Machine

You can install your dotfiles on a brand new machine with a single command:

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

If you use GitHub and your dotfiles repo is called dotfiles, this can be shortened to:

chezmoi init --apply $GITHUB_USERNAME

Note: Private GitHub repos require SSH authentication:

chezmoi init --apply git@github.com:$GITHUB_USERNAME/dotfiles.git

Keeping Everything in Sync

On any machine, you can pull and apply the latest changes from your repo with a single command:

chezmoi update -v

Getting Help

For a full list of available commands, run:

chezmoi help

That's it! Chezmoi makes dotfile management simple and reliable across all your machines. You can check out my dotfiles repo as a reference: github.com/vertocode/dotfiles. Thanks for reading.

April 6, 2026