The benefits of using a single configuration file

Using a single init.lua or vimrc configuration file for (Neo)Vim file is better than a multi folder/file layout approach. Let me tell why that is the case.

The benefits of using a single configuration file

I recently changed my 20 years old vimrc file to init.lua, so I could start using Neovim, again. I used Neovim in the past (around 2015), primarily to support the Neovim support in vim-go .

While migrating to Neovim, I had to read many dotfile repos and blog posts; I've realized that all of them use a multi-folder approach with several layers of abstractions. It wasn't easy to follow. I know there is a specific pattern and that it's all tied to Lua file sourcing, but I wasn't a fan of it.

I realized then why I was not too fond of it. For the past two decades, I always had a single vimrc file. The beauty of using a single file is that I can copy/paste it, and it will work everywhere, and I don't have to jump into other folders or files to understand what's happening.

Treating configuration files like test files

However, the most significant advantage is that I treat editor configuration files, such as vimrc or init.lua like Test files (e.g., files like foo_test.go  or test/spec/model.rb).

The most crucial thing in a test file is that it's usually written once but rarely touched. There are unit tests that someone probably wrote six months ago and never touched. It's probably run on every CI run, but again, it's rarely touched. But when the time comes to modify the test, the problem arises precisely at that moment.

Experienced software engineers write tests in DAMP, which means "Descriptive and Meaningful Phrases" rather than in DRY (Don’t Repeat Yourself).

Test files should be repetitive and highly descriptive. They shouldn't hide any surprising logic. It should be straightforward to add new tests with minimal reading. Second, tests written in DAMP are easier to debug. The goal is to fix the test failure as soon as possible because the code was written six months ago. A highly repetitive and descriptive test code is a valuable asset because you don't have to dive deep into multiple layers of abstracted code.

Google's Test Blog has an excellent post about why tests should not be DRY but DAMP.

Benefits of using a single init.lua/vimrc file

Now back to our init.lua/vimrc file. The same pattern applies to a configuration file. Configuration files, once written, are not touched that often. They should be highly descriptive and readable. They shouldn't hide any implementation details or how a plugin is configured in a particular way.

Assuming you want to add a new plugin and configure it. If you haven't touched your dotfiles for months, the moment you try adding a new plugin, you'll have to adjust and familiarize yourself with the layout. Using a multi-folder with hundreds of scattered tiny files will make adding a new plugin harder. Second, you'll have difficulty debugging if any issues arise because you don't have multiple abstractions that hide the error from you.

Using a single file has many benefits, some of that I enjoy:

  • As I wrote earlier, DAMP over DRY triumphs because I can understand what's going on with my configuration file due to its highly verbose nature.
  • All my settings are in a single place, and I can immediately grep a keyword and make changes without jumping between files.
  • I started with 15 lines of code and grew to 750 lines. I can easily blame any line and see the exact moment and history of the changes for a particular change.
  • You can copy/paste any settings easily and apply them to another init.lua/vimrc without creating folders/files or renaming variables. It's more user-friendly and approachable for other Neovim/Vim users.
  • I can easily bookmark my configuration file and share it with others. Here is my init.lua file: Go ahead and open it. You can copy/paste this file and tweak it to your liking.

I was able to maintain my vimrc for 21 years because that's all I did. I followed the rule of having a single file for my configuration. It traveled with me over cities/countries and continents. I never had to start from scratch, and in times when I had never made changes for years, I could easily modify it when the time came.

To recap, treat your init.lua/vimrc files like test files. Write them in a very highly verbose and descriptive way, and most important, put all your logic in a single file. Your quality of life will improve, and the more you use it, the more you'll appreciate how easy it is to extend and maintain your configuration file over time.