chezmoi dotfile management

Dotfiles are a category of files. They are most commonly configuration files that live in your user directory. Aptly named for the fact that the folder begins with a .. For example, .cargo is there Rust cargo configuration folder.

This type of configuration holds your settings and preferences, and is great to sync between computers. As these tend to be developer settings, git ends up being a natural choice to manage the syncing. One can symlink folders to distribute your dotfiles from the git repository to their expected place on the filesystem.

This begins to become painful though as you sync between different operating systems (OS). Mac expects files in one spot, Windows in another, and the settings themselves might have OS specific paths or settings. This is the value I’ve found in using chezmoi. Visit their website or documentation through their website, chezmoi.io.

chezmoi allows you to sync your settings through git supercharged by Golang templating to normalize your OS differences. It also includes a function to apply your changes if you don’t want to symlink.

Setup

chezmoi is a Golang based command line interface (CLI). Install it with your manager of choice per their instructions.

# on windows
choco install chezmoi
# on Mac
brew install chezmoi
# see the link for other options

Let’s start your repository, and then you can begin adding your existing dotfiles. If you have an existing dotfile repo, you can use the second option as chezmoi expects the repo in a specific location.

Note it is helpful to make certain your dotfiles repo is current if you are importing it.

chezmoi init
# or
chezmoi init <EXISTING_DOTFILE_REPO>

To add a new dotfile, run the add command.

chezmoi add <PATH_TO_FILE_OR_FOLDER>

Adding files to track is a one time operation.

Usage

You can quickly get to your chezmoi directory with their command which opens a sub-shell.

chezmoi cd

I then typically use code . to edit in my [[vscode]] instance. I have found it easiest editing my config directly here. When you make a change in the chezmoi local copy, then you can apply it.

chezmoi apply

If you attempt to apply and it would overwrite changes you have made directly, you will see this response. It makes it feel to liberally apply.

❯ chezmoi apply
Library/Application Support/org.nushell.nu/config.toml has changed since chezmoi last wrote it [diff,overwrite,all-overwrite,skip,quit]?

After making edits to your chezmoi local, git commit them and push. On your other computers, run an update. This effectively does a git pull and chezmoi apply.

chezmoi update

And that is the whole process. You will run through this every time you want to update a setting and sync it.

Templating

In the documentation, templating is explained later on in advanced sections and a specific template document. If you are using multiple OS, this was really the first thing I cared about. How can we deal with this consideration?

It is based on Golang template syntax, so you will find yourself splitting your files up into template pieces and/or a file per OS.

You are given a handful of variables that you can use for if/else logic. To view them, run this command.

chezmoi data

Templates go in ./.chezmoitemplates and files to ignore go in ./.chezmoiignore. These are edited manually.

Note that you can’t template the templates. It uses Go templates which is pretty similar to handlebars or Liquid templates as well.

See my personal dotfile repo if you would like some examples of how these templates look.

summary

I am glad to finally have these settings in sync in a manageable way! I would love to hear how you are using it; reach out! Also a shout out to [[@Chris Biscardi]] for pointing this out to me.