Posted onNov 30, 2019

Dotstow: the smart way to manage your dotfiles

Many essential development tools are managed with dotfiles such as git, zsh, emacs, vim, bash, npm, yarn . . . ok, you get the point. However, managing your dotfiles can be a bit of a mess.

The simple way to manage your dotfiles is to sync them with a git repo. This works great until you have to start using your dotfiles across different machines, different operating systems, and different versions of software.

An improved way to solve this is to use the famous GNU stow program. This separates the dotfiles into stow packages, and stow symlinks them into their respective places. Alex Pearce wrote a nice blog post on this.
https://alexpearce.me/2016/02/managing-dotfiles-with-stow

This is great, but it requires a lot of commands and is not simple, to say the least.

Years ago I wrote a program in python to fix this calleddotstow. It simply abstracts all the stow and git commands. You just have to rundotstow sync to pull and push your dotfiles to git. Since it's built on top of stow, you can segregate your dotfiles by their respective program and choose which ones you want to install. For example, if you wanted to install the dotfiles forzsh, you would rundotstow zsh (NOTE: with the new version of dotstow you would rundotstow stow zsh).

https://pypi.org/project/dotstow

Unlike many dotfile syncing tools, this is powered by GNU Stow. This means your dotfiles must be stored inside stow packages (subfolders) instead of the root of your repo. This prevents cluttering your home directory with unwanted files, like yourREADME.md. It also enables you to only install dotfilesyou want on that computer.

This worked great, but even it wasn't enough. What if you have multiple dotfile configurations for a single program. For example, yourmacOS zsh configuration is probably very different from yourlinux zsh configuration.

To solve this, I completely rewritedotstow. This time, I wrote it in TypeScript and added some new features such asenvironments,autocompletion andforce stow

Usage

First, let me explain the basic usage of this new and improved rewrite of dotstow.

Sync

To sync (or initialize a new dotstow) simply run the command below.

dotstowsync

Install (stow) dotfiles

To install (stow) some dotfiles (symlink them into the home directory) simply run the command below.

dotstow stow[LIST OF DOTFILE PACKAGES...]

For example, if you want to install (stow) the dotfiles forzsh andbash, you would run the command below.

dotstow stow zsh bash

Environments

Environments are how dotstow lets you have multiple configurations for a single package. Dotstow tries to guess your environment. You can always force an environment by using the--environment flag, for example--environment=ubuntu.

Dotstow first tries to guess the environment by looking for a package in the folder with the name or your hostname. I name my computers after famous dragons, so if my hostname was drogon it would look in~/.dotfiles/drogon for the package.

If the package is not found, dotstow will proceed to look for a package in a folder with the type of operating system you are using. For example, if you were running ubuntu, dotstow would look in~/.dotfiles/ubuntu,~/.dotfiles/debian,~/.dotfiles/linux and~/.dotfiles/unix for the package. Dotstow can guess multiple operating systems, such asdebian,ubuntu,linux,osx,win32,win64,darwin,sunos,unix and more.

If the package is still not found, dotstow will look in~/.dotfiles/global.

Force stow

Sometime dotstow would throw an error saying thatstowing . . . would cause conflicts. This error actually comes from the underlying stow program. I added a new feature that lets you force stow packages, essentially ignoring this error, by providing a-f or--force flag to the program.