DEV Community


Dotstow: the smart way to manage your dotfiles

Clay Risser
Open source software engineer proficient with Kubernetes, React, NodeJS, and TypeScript
・3 min read


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.

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 called dotstow. It simply abstracts all the stow and git commands. You just have to run dotstow 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 for zsh, you would run dotstow zsh (NOTE: with the new version of dotstow you would run dotstow stow zsh).

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 your It also enables you to only install dotfiles you 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, your macOS zsh configuration is probably very different from your linux zsh configuration.

To solve this, I completely rewrite dotstow. This time, I wrote it in TypeScript and added some new features such as environments, autocompletion and force stow


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


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

dotstow sync

Enter fullscreen mode Exit fullscreen mode

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...]

Enter fullscreen mode Exit fullscreen mode

For example, if you want to install (stow) the dotfiles for zsh and bash, you would run the command below.

dotstow stow zsh bash
Enter fullscreen mode Exit fullscreen mode


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 as debian, 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 that stowing . . . 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.


This new rewrite of dotstow also supports shell autocompletion. You simply run dotstow autocomplete.

Code and Installation

You can find the code for this project at the link below.
Please ★ this repo if you found it useful ★ ★ ★

You can find an example of dotfiles using dotstow at the link below.

You can install dotstow by running the following command.

npm install -g dotstow
Enter fullscreen mode Exit fullscreen mode

Discussion (0)