Getting Started

This is a beginner-friendly introduction to get you up and running with your own dotfiles repository using doot.

As a power user, moving all my configuration files into a Git repository has been one of the best decisions I've ever made for my workflow. I believe it has 3 main benefits:

• It's a cloud backup of my most important files: I like spending time customizing my system (probably too much time), so losing all that work would be painful. GitHub provides virtually unlimited storage for free, and I can sleep soundly knowing that my configs are safe and sound in the cloud, easily recoverable if needed.

• Massively speeds up the process of setting up a new system: The biggest pain point of switching to a new system or reinstalling my OS is having to reconfigure everything from scratch. With a dotfiles repository, I can simply clone it to my new system and run doot to symlink all my configs. This is especially useful if you have multiple systems (e.g., a laptop and a desktop) that you want to keep in sync.

• Keep a history of all my changes: I can keep track of all the changes that a given file has gone through, and easily revert to a previous version if needed. That's Git's bread and butter, and it works just as well for dotfiles as it does for code.

If this sounds appealing to you, then let's get started!

This is where all your config files will be backed up with version control.

To create a new repository, visit GitHub and click the + button in the top-right corner, or simply click this link. Choose a descriptive name such as "dotfiles". I recommend making the repository private.

Clone the newly created repository locally. From now on, we will refer to this directory as your "dotfiles directory".

git clone https://github.com/<your-name>/dotfiles.git ~/.dotfiles

If you use a GUI Git client (I like GitHub Desktop), you can now add/open this directory in your client.

doot uses sensible defaults for most use cases, but you can customize its behavior to suit your needs.

From your dotfiles directory, create a directory named doot. Inside it, create a file named config.toml.
See Configuration file for available settings and their default values.

You are now ready to start adding files. Just run doot add <some file> and you'll see that the file gets copied to your dotfiles directory and replaced with a symlink.

Notice that the file structure inside a dotfiles directory mimics that of your $HOME. For example, if you add ~/.config/nvim/init.vim, it will be moved to <dotfiles dir>/config/nvim/init.vim.
Check out this example dotfiles directory for a better idea of the general structure.

Now that you have added some files, create a commit using your preferred Git client and push the changes to the remote (which is probably GitHub). I recommend making many small commits, and writing descriptive commit messages. Future you will thank you for this!

Keep in mind that whenever you create, rename or delete a file directly inside your dotfiles directory (this includes pulling changes from the remote), you will need to run doot (no arguments required) to update the symlinks in your home directory.

Once you are comfortable with the basic usage, you may be interested in trying out advanced features such as:

• Host-specific files: Override files based on the hostname of the system you are using. This is useful if you have slightly different configurations for different systems (e.g., a laptop and a desktop).
• Encrypted files: Automatically encrypt sensitive files when pushing them to the remote. This adds an extra layer of security to your dotfiles repository, especially if it is public.
• Hooks: Run custom scripts at various points in the doot workflow (e.g., before/after updating symlinks).
• And more!

The final step of enlightenment is to realize that a dotfiles repository is not just a backup of your configs, but a powerful tool to manage your entire system.
Our goal is simple: to make our system as reproducible as possible (that is, minimize the amount of manual work needed to replicate our system on a new machine). Doing so will allow us to effortlessly recover from disasters or switch between systems.

If that sounds extremely appealing to you, to the point where you want your entire system to be reproducible, then you may want to consider NixOS. Keep in mind, though, that it will take a lot of time and effort.
I, personally, prefer a simpler approach that gives me 90% of the benefits of NixOS with only a fraction of the effort. I'm doing this in 2 ways:

1. Use doot to store the root config files of my system (/etc/hosts, /etc/systemd/system.conf, etc.) in my dotfiles repository. See this example for more details. The sample directory also contains a root-dotfiles directory showing how to do this.

2. Use pkgstate to track my installed packages, user groups, and the state (enabled/disabled) of systemd units (services, timers, sockets...). This is a tool that stores the state of my system inside ~/.config/packages and provides a command that automatically makes any system match that state (by installing/removing packages, enabling/disabling systemd units, etc.). The config files inside ~/.config/packages are, of course, checked into my dotfiles repository.

By doing this, the only files that are not backed up in my dotfiles repository are:

• Autogenerated files (logs, caches...). Those are not important to me and can be recreated at any time.

• User-generated files (downloads, documents...). Most of the work I do is in the cloud (GitHub, Google Drive etc.), so those are usually not a problem. If your PC contains important local files, you may want to consider using a cloud backup solution or a NAS to keep them safe.