Managing your Dotfiles with Dotter (Tutorial)

Jakob — Wed, 06 Jul 2022 08:00:03 +0000

Cover Image by Susan Mielke on Pixabay

Hello and welcome to my very first blog post! In this tutorial, you'll learn how YOU can manage your Dotfiles with a great tool called Dotter, and sync those Dotfiles to Git(Hub).

What are Dotfiles?

In Linux, everything is a File

True to this quote, when you configure things in Linux, you often times actually write that config to a file, mostly in a format like TOML, YAML, JSON, or similar. Those files often get stored in ~/.config/myprogram, which allows for easy backups and it's a cleaner architecture. However, some programs save their config in the Home Directory of the User, and mostly with the prefix ., because in Linux, Files with the Prefix . are hidden per default, and after all, we don't want to see config files when browsing the file system. Thus, those config files are called the "Dotfiles".

Why should I save / backup those dotfiles?

Remember the last time you got a new PC and had to set up everything again? I personally experienced this 2 weeks ago, and wanted a solution, so I searched, and found the concept of Dotfiles. By backing them up on, say, GitHub, you can

easily share them and ask for help
migrate to a new computer far quicker
take your config files with where you go, they're just a git clone away (and you have to run the executable, but more on that later)
easily restore your configs when your computer stops working

Alright, cool, now, how do I even do that?

I'm glad you asked! There are plenty of dotfiles managers out there, like chezmoi, Dotbot, or yadm (you can see a list here and a comparison table (from chezmoi, thus biased) here. But for this tutorial (and my dotfiles), I chose dotter.

But, why would I use dotter, when there are so many alternatives out there?

For me, dotter has a few good reasons for why to use it.

Handlebars support - If you want to add some logic and "dynamicness" to your dotfiles, you can use Handlebars! There are several built-in helpers, and you can make your own, in the language rhai
Portable Binary - you don't have to install anything, just download the compiled binary from the releases (or build it yourself), run it, and you got your whole dotfiles manager with you wherever you go. You can even push the binary to your repository for even faster onboarding without having to install ANYTHING - not even a scripting language!
It supports symlinks AND copying (if you use templating)
[PERSONAL] Complete Control with Git - unlike chezmoi, you can just use the git commands to check the deployment / syncing status, which makes for a far faster onboarding and it's (in my opinion!) far easier to get used to
[PERSONAL] Nice configurating - I really like the way you configure it, different things are organized in "packages", and you can choose which packages to use locally.

Alright, now let's get our hands dirty! (the actual Tutorial)

I'm glad you're still here, even after this large part, so now, let's finally get started with making our own dotfiles repository!

Create a new repository with this template
Clone the repository, preferably in a subfolder in your home directory (for example in ~/.dotfiles)
Rename the .dotter/local.example.toml to .dotter/local.toml
Modify the files to your likings - documentation is available here
"Deploy" the files to their respective locations by using - you can do this by running ./dotter deploy. NOTE: you HAVE to do this on the same layer as the .dotter folder lays, otherwise it won't detect the configs. "Deploying" is what delivering the files to their final destination is called in the dotter context.
If the file you're trying to deploy already exists, use the --force flag - this will overwrite existing files, so use with caution!
If you want to be able to change and deploy configs on the fly, run dotter watch - this will automatically run deploy every time a change in the filesystem is registered - you can even put this into a systemd service
If you want your changes to be synced, just do git commit and git push in the dotfiles folder like you'd do in a normal git repository - after all, it is literally that!

This is a very short and high-level overview, if you want to know how to do templating, use helpers, and other powerful things, please refer to the documentation - it features pretty much everything you'll need! If you need further help, please reach out to me

A few nice-to-knows relating dotter

A function that allows you to cd into your dotfiles folder from anywhere, or open your Git Repo (source this function, for example by putting it in your zshrc)
Rhai-Script that checks for a boolean (markdown's ifs evaluate as "true" if the condition prints out anything, but sometimes, your condition prints out "true" OR "false", which causes it to always evaluate to true - this script fixes that)
Post-Deploy script that sends a notification once dotter deployed changes (especially useful for dotter watch)
Post-Deploy script that automatically reloads i3 once changes are detected (IN ANY DOTFILE IN YOUR REPO!) - IMPORTANT: the bool.rhai script is required!

Wrapping up

I really hope you learned something new in this tutorial! Thanks a lot for reading through, and please, share feedback in the comments. This is my very first time writing a blog post, and I'd really appreciate some constructive criticism. If you need any help, you can either message me on discord (@simulatan), send me an email (jakob@simulatan.me), add a comment to the gist or open an issue on the template repository (if related to said template)

Many questions related to dotter can be answered by the wiki, which is well-written in my opinion. The author, SuperCuber, is also super helpful and kind, so if you face problems that are related to dotter, just open an issue. Also, PRs are welcome, so feel free to contribute!

Links

Dotter

SuperCuber / dotter

A dotfile manager and templater written in rust 🦀

What is Dotter?

Dotter is a dotfile manager and templater.

Dotfiles are configuration files that usually live in the home directory and start with a dot Often times, it is desirable to have a backup of all the configurations on your system, which is why a lot of users have their dotfiles saved in a git repository, then symlinking them to their target locations using ln -s.

However, there are several issues with that barebones approach:

Hard to keep track of what comes from where once you have more than a handful of dotfiles
Tedious to setup on a new machine - you need to manually create every single link
No real way to handle differences between machines - say you want the battery meter on your bar to not appear on your desktop machine

Dotter aims to solve all those problems by providing a flexible configuration and automatic…

View on GitHub

My template repository

SIMULATAN / DotterTemplate

🚀 a template repository that helps you bootstrap your dotfiles repository with dotter

Nice-to-have dotter scripts

Rhai (scripting language for Dotter's Handlebar Helpers)

rhaiscript / rhai

Rhai - An embedded scripting language for Rust.

Rhai - Embedded Scripting for Rust

Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way to add scripting to any application.

Targets and builds

All CPU and O/S targets supported by Rust, including
- WebAssembly (WASM)
- no-std
Minimum Rust version 1.66.0

Standard features

Simple language similar to JavaScript+Rust with dynamic typing.
Fairly efficient evaluation - 1 million iterations in 0.14 sec on a single-core 2.6 GHz Linux VM running this script.
Tight integration with native Rust functions and types, including getters/setters, methods and indexers.
Freely pass Rust values into a script as variables/constants via an external Scope - all clonable Rust types are supported; no need to implement any special trait. Or tap directly into the variable resolution process.
Built-in support for most common data types including booleans, integers, floating-point numbers (including Decimal)…