Dotstow: the smart way to manage your dotfiles
Tags: dotfiles, stash, linux, typescript
Published: 2019-11-30 07:24:17

---
title: Dotstow: the smart way to manage your dotfiles
published: true
description: Easily manage your dotfiles using dotstow, git and stow
tags: dotfiles, stash, linux, typescript
---

![structure-light-led-movement-158826](https://user-images.githubusercontent.com/6234038/69897460-11f79a00-1312-11ea-8664-69b6f3732631.jpeg)

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 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`).

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 your `README.md`. 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**

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

```sh
dotstow sync

```

### Install (stow) dotfiles

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

```sh
dotstow stow [LIST OF DOTFILE PACKAGES...]

```

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

```sh
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 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.


## Autocompletion

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 ★ ★ ★

https://github.com/codejamninja/dotstow

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

https://github.com/codejamninja/dotfiles

You can install dotstow by running the following command.

```sh
npm install -g dotstow
```

https://medium.com/@codejamninja/dotstow-the-smart-way-to-manage-your-dotfiles-8a0a8b6d984c