manage dotfiles with stow
Please ★ this repo if you found it useful ★ ★ ★
Windows support has not been tested.
Built by Silicon Hills LLC
Silicon Hills offers premium Node and React develpoment and support services. Get in touch at nuevesolutions.com.
You can see some dotfiles repos (which are using dotstow) at the link below.
You can read more about dotstow at the blog post below.
- Group dotfiles into units (stow packages)
- Automatically symlink (stow) files
- Backup dotfiles with git
- Keep track of simultaneous dotfile configurations for multiple environments
- Supports shell autocompletion
- Supports bootstraping using a config
npm install -g dotstow
Note that 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.
The idea behind dotstow is twofold:
- You don't need to maintain a shell script that symlinks all of your dotfiles to the correct places in your $HOME directory upon a new dotfile install
- Individual directories in your .dotfiles become packages that can be installed independently
dotstow stow [package]
When setting up your dotfiles on a new computer
dotstow bootstrap --remote <GITHUB_REPO_LINK>, and watch as it's cloned into
~/.dotfilesand would run the scripts configured in bootstrap.yml.
dotstow stow zsh emacs vim ...etc for each of the stow packages you'd like to install (aka symlink to $HOME).
To pull the latest changes from the remote repository, run
When you update a file in a package, you only need to
dotstow syncto update your linked github repo with the changes. This takes care of committing/pushing the changes to the repository.
Note: If you add new files to your stow package, you will need to restow the package. For example, when adding
.dotfiles/globals/zsh/, you will need to
dotstow stow zshto restow the package and then
dotstow syncto update your linked github repo with the changes.
bootstrap.yml config can be placed on any environment directory (including global) and should contain the message and cmd keys for any item. See sample config here
USAGE $ dotstow [COMMAND] COMMANDS autocomplete display autocomplete installation instructions bootstrap bootstrap dotfiles help display help for dotstow pull pull dotfiles stow stow dotfiles sync sync dotfiles
Environments is how dotstow lets you have multiple configurations for a single package. This is extremely useful
if you have multiple operating systems that require slighty different configurations while still keeping
all your dotfiles togather. For example, maybe your
zsh would be configured differently on
osx than on
Dotstow tries to guess your environment. You can always force an environment by using the
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
If the package is not found, dotstow will proceed to look for a package in a folder with the type of the operating
you are using. For example, if you were running
ubuntu, dotstow would look in
~/.dotfiles/unix for the package.
Dotstow can guess multiple operating systems.
aix amigaos android beos bsd centos darwin debian fedora freebsd ios linux mac nintendo openbsd osx redhat rhel slackware starBlade sunos ubuntu unix value win win32 win64 windows
bootstrap.yml is meant to configure things that should have done before actually stowing the packages. Cloning certain directories and keeping them at certain locations is an example of that sort. bootstrap also takes care of cloning the dotfiles directory and you can start stowing packages right after this.
bootstrap dotfiles USAGE $ dotstow bootstrap OPTIONS -d, --dotfiles=dotfiles -e, --environment=environment -r, --remote=remote --debug EXAMPLE $ dotstow bootstrap --remote https://github.com/sreerajkksd/dotfiles.git
Sample bootstrap.yml config
- message: Setting up Vim Plugcmd: curl -fLo ~/.vim/autoload/plug.vim --create-dirs https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim- message: Setting up Tmux TPMcmd: git clone -q --depth 1 https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm- message: Setting up ohm-my-zshcmd: sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"- message: Installing VIM Plugcmd: vim +'PlugInstall --sync' +qa
USAGE $ dotstow stow PACKAGES... OPTIONS -d, --dotfiles=dotfiles -e, --environment=environment -f, --force -s, --sync --debug EXAMPLE $ dotstow stow
USAGE $ dotstow sync OPTIONS -d, --debug EXAMPLE $ dotstow sync
If you want to enable shell autocompletion, simply run the following command
and follow the instructions. Most standard shells are supported, such as
USAGE $ dotstow autocomplete [SHELL] ARGUMENTS SHELL shell type OPTIONS -r, --refresh-cache Refresh cache (ignores displaying instructions) EXAMPLES $ dotstow autocomplete $ dotstow autocomplete bash $ dotstow autocomplete zsh $ dotstow autocomplete --refresh-cache
If you were using the python version of dotstow, you should upgrade to
this version to get the benefits of multiple environments. If you switch
you will have to move your stash plugins into an environment folder (
global is recommended).
You can do that by running the following commands.
mkdir ~/tmp_globalmv ~/.dotfiles/* ~/tmp_globalmv ~/tmp_global mkdir ~/.dotfiles/global
Setting up dev instance
git clone https://github.com/codejamninja/dotstow.gitcd dotstownpm install --also=dev# To start the compiled dotstow code:# Note: Ensure that you have yarn installed. (else install it using `npm install -g yarn`)yarnyarn start# If you want test a command.yarn start <command>
Stowing zsh would cause conflicts
If you get an error similar to the one below, simply force stowing by passing
✖ WARNING! stowing zsh would cause conflicts: * existing target is not owned by stow: .zsh_aliases * existing target is not owned by stow: .zsh_envs * existing target is not owned by stow: .zsh_sources * existing target is not owned by stow: .zshrc All operations aborted.
For example . . .
dotstow stow -f zsh
Please understand this will overrite any existing file.
Submit an issue
Contribute a screenshot
Review the guidelines for contributing
Jam Risser © 2019
Review the changelog
- Jam Risser - Author
Support on Liberapay
A ridiculous amount of coffee ☕ ☕ ☕ was consumed in the process of building this project.
Add some fuel if you'd like to keep me going!