⚡ TL;DR

Chezmoi follows a declarative approach to configuration management. Even if you already use a configuration-management system, you should check out how it compares!

A Custom Configuration Makes You Feel at Home

Your git aliases, shell setup, keyboard shortcuts and even your favorite fonts are tweaked for your own needs and tastes. It’s part of what makes your computer, your computer. All this configuration evolves over years and is slowly refined over time. It may actually be your longuest-living project.

Do you want to start from scratch when you switch computer? Of course not! And you wouldn’t want to break it with adventurous changes either! Versioning it in git backs up the history and eases the management of this important work. Configuration updates are also more convenient to share between machines this way.

Enter Chezmoi

In the git-based configuration management described above, how to account for the small variations (like between your work environment and personal computer)? Git supports conditional inclusion of configuration files, but how about the other tools? What if you want to encrypt your secrets in your config files, to publish your configuration on GitHub?

Chezmoi follows a declarative approach: it has a separate source repository¹ to describe a target state, that then gets applied to your home directory. This is possible through templates, that are activated selectively for some files. The rest of this post shows how powerful templating can be.

Account for Variations Between Machines

Let’s start with a simple example. In the git configuration, you put your email, that’s then included in all your commits. Thus, you often want to have a different email in .gitconfig for your work and personal profiles. To tackle this issue, I put the following in my .gitconfig chezmoi template:

[user]
    email = {{ .email }}

and it gets rendered to this:

[user]
    email = me@my.home

on my personal computer and this:

[user]
    email = me@my.work

on my work computer. It serves a purpose similar to conditionally setting your gitconfig, but it is applicable to any program.

Even More Variations with Templates

Now, let’s cover a more powerful use of templates.

You can have multiple files generated from one using “global” templates. For instance, if you use i3 and sway as your windows manager, you likely have slightly different configurations, given that sway’s configuration is mostly compatible with that of i3. To keep everything in one file, while taking advantages of sway-specific features, you can (in your chezmoi repository):

1. Put your configuration in .chezmoitemplates/sway_i3. You can keep any sway specific section in a templated if statement, like so:

   {{- if eq .f "sway" }}
   # Sway specific stuff here, like output configuration
   {{- end }}
   

2. In dot_config/i3/config.tmpl (and dot_config/sway/config.tmpl), use something like:

   {{/* Environment */}}
   {{- $env := . -}}
   
   {{/* Flavor */}}
   {{- $f := "i3" -}} # <--- Change this to "sway" in dot_config/sway/config.tmpl
   
   {{- template "sway_i3" dict "f" $f "env" $env -}}
   

   As you may have noticed, chezmoi renames some files in the source state, to encode parameters and for readability. So dot_config/sway/config.tmpl becomes .config/sway/config (.tmpl means the file is executed as a template).
   Also, $env is used to keep the general template context, for instance to check the OS version in our template config file.

.chezmoiignore

Finally, chezmoi supports an ignore file named .chezmoiignore. The concept is similar to the well known .gitignore: patterns listed in this file are ignored by chezmoi. In other words, some files are stored in your chezmoi repository, but do not reflect in your home. This can be used if you put a README.md in your configuration repository, as you don’t want this file in your home directory. Just write:

README.md

in .chezmoiignore and the README.md won’t be copied in your home.

You can do more advanced things with .chezmoiignore as it is a template by default. From the documentation:

{{- if ne .email "firstname.lastname@company.com" }}
# Ignore .company-directory unless configured with a company email
.company-directory # note that the pattern is not dot_company-directory
{{- end }}

Conclusion

Chezmoi has lot more features, like encryption or installation in GitHub Codespaces. It is quite well documented, in particular with a quick start guide.

I’ve switched to it almost two years ago, I don’t regret it at all!

Bonus: Vim Snippet

To update the target state automatically when editing the source file in the chezmoi repo, I use this vim snippet (with the fish shell):

autocmd BufWritePost ~/.local/share/chezmoi/* ! chezmoi apply --source-path %; or for f in (rg -l 'template "%:t"'); chezmoi apply --source-path $f; end

Why create your own Vim config from scratch?

Vim has been my daily driver for about ten years. Almost from the beginning, I used Vim distributions for ease of configuration. Spf13 vim first and then SpaceVim. With a distribution, one gets a lot of bells and whistle without spending too much time configuring things. So why spend hours setting up NeoVim from scratch?

SpaceVim does provide a lot of options and plugins so that everyone can find the functionalities they need and discover some new useful tricks. This ends up creating long key mappings like <space>ff and leads to long startup time. For instance on my machine with an SSD drive, it needs between 1 and 2 seconds to start. This is a common problem with distributions.

The long startup time issue can be mitigated by starting Vim less often or by choosing a lighter Vim distribution. One could even reuse only the core and some parts of a distribution, leaving out the rest. Regarding the long key mappings issue, shorter ones could be redefined. However, this has two major drawbacks:

• your customized configuration lies on the moving foundations of the underlying distributions,
• debugging is made more difficult because of the incorporation of so much code you haven’t written and don’t know well.

To solve all these problems, I found it easier and less time-consuming to have my own configuration. Additional benefits include a better recall of what exists and what functionalities are implemented¹. The good news with NeoVim 0.5 is that you can now use Lua and not an arcane language like VimScript². The result is also quite fast: with my configuration NeoVim starts in 100 to 110 milliseconds.

Starting your own configuration does not mean you can’t draw inspiration from other configurations! The next sections of this post reference guides, snippets and plugins I’ve found useful, so that you can evaluate them for inclusion into your own file.

Enjoy the Ride!

To tailor my experience to my liking, I tried my changes in a new instance of NeoVim after every addition of a plugin or of a set of mappings. Mappings in particular sometime looks good on the screen, but fingers don’t like it that much 😀.

In addition, NeoVim configuration can be notoriously complicated to debug. To quote the documentation:

For this the previous point about regular testing helps, but I would advise for versioning your configuration, for instance with git and chezmoi. With regular commits, you will be able to rely on the git bisect feature when things go wrong.

Guides

Detailed guidance exists online to get started with your configuration. I got started with a mostly one file Lua configuration. This guide contains general explainations on where to put your Lua files, the reasoning behind the changes… If you are not familiar with NeoVim Lua configuration tricks, I strongly recommend reading the above link. See you in a bit 👋.

In addition, these links may prove useful:

• Example init.lua
• A quick guide to set up nvim built in LSP
• NeoVim’s Lua Resources

Snippets from my Configuration

This section assumes basic knowledge of Lua configuration.

Mapping Hints

Which-Key is a brilliant plugin to display a popup with the possible mappings as you press the keys of the shortcut. For instance, I have mapped <space>j to :tabnew, to open a new tab. On the figure above, I’ve just typed <space> (abbreviated SPC) and the keys that could be pressed then are displayed in a popup at the bottom of the screen. What sets which-key.nvim apart is that you don’t have to configuration your mappings using a special function for it to work. It discovers most of your mappings right away and use them to populate the popup.

I’ve tweaked timeoutlen to get the popup more quickly. I’ve also changed labels for some keys to have shorter or more explicit names, like SPC for <space>.

local wk = require("which-key")
wk.setup {
  key_labels = {
    ["<space>"] = "SPC",
    ["<CR>"] = "RET",
    ["<tab>"] = "TAB",
  },
}
vim.opt.timeoutlen = 900

Mapping Choices

My custom mappings are mainly around the <space> key, often with only one key following, like <space>s to write the current file. The <Leader> key is mostly left for plugins, while the <LocalLeader> is sometimes used for some buffer local mappings.

In general, my mappings are heavily adapted to the BÉPO layout, a Dvorak-like keyboard for French.

Clever-F

rhysd/clever-f.vim extends f, t… so that:

1. When you press fc, all characters c in the current line get highlighted
2. Another press on f jumps to the next occurence of c
3. A press on F jumps backward

This makes , and ; redondant and these can be remapped.

Leaders

The universal leader is by default mapped on \. However, it is frequently remapped to ,, which is easier to reach. Since clever-f freed two mappings, I reuse them like so:

g.mapleader = ","
g.maplocalleader = ";"

Buffer Jump

With the awesome hop.nvim, one can get hints to jump to various parts of a buffer (see the figure below if that does not make sense just yet). It is similiar to EasyMotions and supports jumps by line, word, characters sequences and pattern. However, in my opinion this plugin is not replacement for w and the like, because for short movements I find w or f shorter to type and because the need to read the screen for caracters may be quite slow compared to 3w. It is also not a replacement for / because hop.nvim highlights whats visible on the current buffer. Thus it fills the void left for medium range move.

Here is my configuration for this plugin:

map('n', 'T', '<cmd>HopLineStart<CR>')
map('v', 'T', '<cmd>HopLineStart<CR>')
map('n', 'S', '<cmd>HopWord<CR>')
map('v', 'S', '<cmd>HopWord<CR>')
map('n', 'è', '<cmd>HopChar2<CR>')
map('v', 'è', '<cmd>HopChar2<CR>')
map('n', 'È', '<cmd>HopPattern<CR>')
map('v', 'È', '<cmd>HopPattern<CR>')
require('hop').setup {
  keys = 'auietsrncbpovdljyxqghf', -- Hint keys
}

It is heavily optimized for the the BÉPO layout, whose home row contains the auie keys on the left hand and the tsrn keys on the right hand. Hence the choice to put most mappings on T and S, easily reachable with the right hand and to start the hint keys with auie on the left hand.

Plugins

These plugin are often mostly written in Lua, although vim script plugins can be more mature. The Lua-plugin ecosystem is moving really quickly, you may find that other plugins are more suitable in a couple months.

Plugins I use

Telescope

I use telescope.nvim as a fuzzy finder. It can be slow at times compared to skim or fzf. However, it is relatively easy to script in Lua, making it easy to tightly integrate with other functions.

Completion-nvim

I use nvim-lua/completion-nvim in particular for its chains of completion (several completion sources are chained and sources lower in the chain are used when upper sources don’t have any results). However, nvim-compe may be a better choice if you start fresh.

Complete List

This is a list of plugins I use, roughly ordered by frequency of use.

Plugins I load lazily

I lazy load less often used plugins, so that they are not loaded at startup by default.

• romgrk/nvim-treesitter-context is a bit slow and buggy, but useful sometimes to get the context piled up at the top
• mattn/emmet-vim CSS abbreviations to generate HTML and other
• jbyuki/instant.nvim for remote pair programming

Plugins on my Radar for the Future

Plugins I might use in the future to replace existing pieces or add features:

• vimspector a debugger based on the DAP protocol (like LSP, but for debugguers)
• lspsaga.nvim a UI for the native LSP client
• nvim-compe a completion engine with more advanced support for LSP. I quite like the chains in completion-nvim, but maybe nvim-compe could be a better fit at some point
• gina.vim to replace fugitive. It offers faster startup time and asynchronous git operations

Other Interesting Configurations

• tjdevries
• ojroques

Thanks

Thanks to moverest and J. Guereiro for reviewing drafts of this post.