manage dotfiles with stow
Please ★ this repo if you found it useful ★ ★ ★
Windows support has not been tested.
You can see my dotfiles (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
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 you .dotfiles become packages that can be installed independently
dotstow stow [package]
When setting up your dotfiles on a new computer
dotstow sync, give it your dotfiles github repo link, and watch as it's cloned into
dotstow stow zsh emacs vim ...etc for each of the stow packages you'd like to install (aka symlink to $HOME).
- When you update a file in a package, you only need to
dotstow syncto update your linked github repo with the changes. 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.
USAGE $ dotstow [COMMAND] COMMANDS autocomplete display autocomplete installation instructions help display help for dotstow 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
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_global mv ~/.dotfiles/* ~/tmp_global mv ~/tmp_global mkdir ~/.dotfiles/global
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!