README
dotstow
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.
Related Projects
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.
https://dev.to/codejamninja/dotstow-the-smart-way-to-manage-your-dotfiles-25ik
Features
- 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
Installation
npm install -g dotstow
Dependencies
Usage
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
using
dotstow stow [package]
For example:
When setting up your dotfiles on a new computer
Run
dotstow bootstrap --remote <GITHUB_REPO_LINK>
, and watch as it's cloned into~/.dotfiles
and would run the scripts configured in bootstrap.yml.Run
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
dotstow pull
.When you update a file in a package, you only need to
dotstow sync
to 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
.zshrc
to.dotfiles/globals/zsh/
, you will need todotstow stow zsh
to restow the package and thendotstow sync
to 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
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 linux
.
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 the operating
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.
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
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 Plug
cmd: curl -fLo ~/.vim/autoload/plug.vim --create-dirs https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
- message: Setting up Tmux TPM
cmd: git clone -q --depth 1 https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
- message: Setting up ohm-my-zsh
cmd: sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
- message: Installing VIM Plug
cmd: vim +'PlugInstall --sync' +qa
Stow
USAGE
$ dotstow stow PACKAGES...
OPTIONS
-d, --dotfiles=dotfiles
-e, --environment=environment
-f, --force
-s, --sync
--debug
EXAMPLE
$ dotstow stow
Sync
USAGE
$ dotstow sync
OPTIONS
-d, --debug
EXAMPLE
$ dotstow sync
Autocompletion
If you want to enable shell autocompletion, simply run the following command
and follow the instructions. Most standard shells are supported, such as
bash
and zsh
.
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
Migration
Python dotstow
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
Setting up dev instance
git clone https://github.com/codejamninja/dotstow.git
cd dotstow
npm install --also=dev
# To start the compiled dotstow code:
# Note: Ensure that you have yarn installed. (else install it using `npm install -g yarn`)
yarn
yarn start
# If you want test a command.
yarn start <command>
FAQ
Stowing zsh would cause conflicts
If you get an error similar to the one below, simply force stowing by passing
the -f
or --force
flag.
✖ 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.
Support
Submit an issue
Screenshots
Contribute a screenshot
Contributing
Review the guidelines for contributing
License
Jam Risser © 2019
Changelog
Review the changelog
Credits
- 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!