Skip to content

Latest commit

 

History

History
164 lines (130 loc) · 5.22 KB

README.md

File metadata and controls

164 lines (130 loc) · 5.22 KB
Raw

stowsh

A shell script to install and uninstall dotfiles using symlinks. stow written in bash, in other words.

Installation

Put stowsh in your path.

Dependencies

stowsh strives for minimal dependencies, but it currently depends on the GNU coreutils implementation of realpath and GNU findutils.

These are already installed on most Linux systems. On macOS you can install them with brew install findutils coreutils.

I would welcome PRs to remove these dependencies and replace them with POSIX shell commands!

Quickstart

Create a package (a directory of dotfiles, ~/.dotfiles in this example):

$ cd
$ tree -a
.
└── .dotfiles
    ├── .bash_profile
    └── .vimrc

Install the package (create symlinks in the current directory) using stowsh

$ stowsh ~/.dotfiles
$ tree -a
.
├── .bash_profile -> .dotfiles/.bash_profile
├── .dotfiles
│   ├── .bash_profile
│   └── .vimrc
└── .vimrc -> .dotfiles/.vimrc

Uninstall the package (delete symlinks) using stowsh

$ stowsh -D ~/.dotfiles

Details and options

A package is a directory containing related configuration files. stowsh symlinks the package's contents to the corresponding locations in the current directory, creating subdirectories as necessary.

$ stowsh -h
Usage: stowsh [-D] [-n] [-s] [-g] [-v[v]] [-t TARGET] PACKAGES...

TARGET is the destination directory (current directory by default).

  • -D uninstall package(s)
  • -n dry-run (print what would happen, but don't do anything)
  • -v verbose (-vv is even more verbose)
  • -g ignore files that are not tracked by git (uses git ls-files)
  • -s skip (skip errors rather than abort)

When installing a package stowsh will never overwrite existing files. When uninstalling a package stowsh will never delete files that are not symlinks to the expected place in the package.

By default stowsh will abort without making any changes if either of these errors occurs. This is done to avoid being left with a broken half installed configuration. The -s flag can be used to force stowsh to skip these errors and install/uninstall as much as possible.

One important consequence of the fact that stowsh does not delete files that aren't symlinks to the right place is (deep breath!): if you install a package, delete a file from the package, then uninstall the package, your target directory will be left with a broken symlink to the deleted file.

Use as a dotfiles manager

You can put your dotfiles in one package and install that with stowsh directly.

Or you may prefer to have multiple orthogonal packages that get installed by a script that uses stowsh. This allows you to install packages only if certain conditions are met. Here's an example install script that uses stowsh.

If your needs go beyond this, there are many fully-featured dotfiles managers.

Subdirectories

stowsh will only create links to files and links. It does not create links to directories.

If a package contains directories, and the corresponding directories do not exist in the target, stowsh will create real directories (not links).

This choice allows two packages to install files in the same subdirectory, and files that don't belong in your dotfiles repo (e.g. caches) to be added to those subdirectories without also being added to your dotfiles repo or its .gitignore file.

$ tree -a
.
├── .conf
│   └── conf.cache
└── .dotfiles
    ├── pkg1
    │   ├── .conf
    │   │   ├── a.conf
    │   │   ├── b.conf
    │   │   └── c.conf
    │   └── bin
    │       └── script1
    └── pkg2
        └── bin
            └── script2
$ stowsh .dotfiles/pkg1 .dotfiles/pkg2
$ tree -a -I '.dotfiles'  # exclude ./.dotfiles from tree listing
.
├── .conf
│   ├── a.conf -> ../.dotfiles/pkg1/.conf/a.conf
│   ├── b.conf -> ../.dotfiles/pkg1/.conf/b.conf
│   ├── c.conf -> ../.dotfiles/pkg1/.conf/c.conf
│   └── conf.cache
└── bin
    ├── script1 -> ../.dotfiles/pkg1/bin/script1
    └── script2 -> ../.dotfiles/pkg2/bin/script2

Things to note here:

  • ~/bin was created by stowsh. It's a real directory, not a link.
  • both pkg1 and pkg2 install files into ~/bin
  • the directory .conf existed before pkg1 was installed
  • conf.cache is a real file that exists alongside the symlinks installed by stowsh

When uninstalling a package, subdirectories will only be deleted if they are empty. So:

$ stowsh -D .dotfiles/pkg1 .dotfiles/pkg2
$ tree -a -I '.dotfiles'
.
└── .conf
    └── conf.cache

What's wrong with GNU stow?

stowsh is a short, cross-platform bash script without dependencies. stow is implemented as a Perl module. I'm not smart enough to install Perl modules, and I'd rather not have Perl as a dependency.

Author

Mike Lee Williams. Issues and PRs welcome.