Managing your Dotfiles with Dotter (Tutorial)
Tags: linux, dotfiles, dotter, tutorial
Published: 2022-07-06 08:00:03

_Cover Image by [Susan Mielke](https://pixabay.com/users/susannp4-1777190) on [Pixabay](https://pixabay.com/photos/cat-young-animal-kitten-gray-cat-2083492/)_

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](https://chezmoi.io/), [Dotbot](https://github.com/anishathalye/dotbot), or [yadm](https://yadm.io/) (you can see a list [here](https://dotfiles.github.io/utilities/) and a comparison table (from chezmoi, thus biased) [here](https://www.chezmoi.io/comparison-table/). But for this tutorial (and [my dotfiles](https://github.com/SIMULATAN/dotfiles)), I chose [dotter](https://github.com/SuperCuber/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](https://github.com/rhaiscript/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!
1. Create a new repository with [this](https://github.com/SIMULATAN/DotterTemplate) template
2. Clone the repository, preferably in a subfolder in your home directory (for example in `~/.dotfiles`)
3. Rename the `.dotter/local.example.toml` to `.dotter/local.toml`
4. Modify the files to your likings - documentation is available [here](https://github.com/SuperCuber/dotter/wiki/Setup-and-Configuration)
5. "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.
6. If the file you're trying to deploy already exists, use the `--force` flag - this will **overwrite** existing files, so use with caution!
7. 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](https://github.com/SIMULATAN/dotfiles/blob/main/tips/DOTTER_WATCH_SERVICE.md)
8. 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](https://github.com/SuperCuber/dotter/wiki) - it features pretty much everything you'll need! If you need further help, please [reach out to me](#links)

## A few nice-to-knows relating dotter
1. 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)
{% gist https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536 file=cd-into-dotfiles-folder.sh %}
2. 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)
{% gist https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536 file=bool.rhai %}
3. Post-Deploy script that sends a notification once dotter deployed changes (especially useful for `dotter watch`)
{% gist https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536 file=post_deploy_notification.sh %}
4. Post-Deploy script that automatically reloads i3 once changes are detected (IN ANY DOTFILE IN YOUR REPO!) - IMPORTANT: the `bool.rhai` script is required!
{% gist https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536 file=post_deploy_auto_reload.hbs %}

## 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)](https://discord.com/users/505713760124665867), send me an email (simulatan2319@gmail.com), add a comment to the [gist](https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536) or open an issue on the [template repository](https://github.com/SIMULATAN/DotterTemplate) (if related to said template)

Many questions related to dotter can be answered by [the wiki](https://github.com/SuperCuber/dotter/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
{% embed https://github.com/SuperCuber/dotter %}
My template repository
{% embed https://github.com/SIMULATAN/DotterTemplate %}
Nice-to-have dotter scripts
{% embed https://gist.github.com/SIMULATAN/ec8b753a415d408c869775e815e83536 %}
Rhai (scripting language for Dotter's Handlebar Helpers)
{% embed https://github.com/rhaiscript/rhai %}