hstow -- POSIX sh minimal reimplementation of GNU Stow for dotfiles

[Sean Whitton]

I am pleased to announce hstow, a POSIX sh minimal reimplementation of
GNU Stow to manage symbolic links from HOME into VCS repos of dotfiles.

I've spent a lot of time poring over POSIX.1, and the result is acceptably
fast, and should be very highly portable.  I would appreciate hearing from
users running BSDs/macOS w.r.t. the latter claim.

https://git.spwhitton.name/dotfiles/tree/bin/hstow

-- 8< --
#
# USAGE
#
#     hstow stow|unstow|restow|adopt DIRECTORY
#
# For example, if ~/dotfiles/ is a VCS repository with master copies of
# your .profile, .inputrc, .config/git/config, etc., you can use
#
#     % hstow stow ~/dotfiles
#
# to create links ~/.profile           -> ~/dotfiles/.profile,
#                 ~/.inputrc           -> ~/dotfiles/.inputrc,
#                 ~/.config/git/config -> ~/dotfiles/.config/git/config
# etc..
#
# ADOPTION
#
# Some programs will replace a symlink to a stowed file with a regular
# copy of the file, and a subset of these will do this even if they
# haven't edited the file.  This will cause 'hstow stow' to fail.
#
# To deal with this, use the 'adopt' subcommand.  This will move the
# modified file into your repository, and restore the symlink.
# Then you can use VCS tools ('git diff', 'hg diff', etc..) to decide
# whether to keep any changes.
#
# INSTALLATION
#
# This script is POSIX sh-compatible: it should run almost anywhere.
#
# Copy hstow, posix-defuns.sh and globs2ere.awk from my dotfiles.git
# into your own, and update the paths to the latter files embedded in
# the first.  You might then incorporate restowing into any bootstrap
# scripts you have.  I use joeyh's myrepos, and cf. my 'bstraph' script.
#
# CONFIGURATION
#
# There are three optional configuration files in the root of DIRECTORY.
# Each is a list of globs, one per line, with blank lines ignored.
# There is no comment syntax.  These globs are for matching, not
# expansion: '/' and '.' are not treated specially.
#
# .hstow-local-ignore
#
#     Files under DIRECTORY which should not be symlinked.
#     E.g. 'archive/*'.
#
# .hstow-unstow-ignore
#
#     Paths under HOME which should not be scanned for symlinks to
#     remove.  By default, 'hstow unstow' looks at every symlink under
#     HOME to see whether it's one we created: this has the advantage
#     that if a 'git pull' or 'hg up' removes a file, it's still
#     possible to remove the dangling symlink.  But this can be slow.
#
#     If you have directories under HOME into which you'll never stow
#     anything but which contain a lot of symlinks and/or subdirectory
#     structure, list globs matching those here.  E.g. 'annex/*'.
#
# .hstow-always-adopt
#
#     Paths under HOME which 'hstow stow' should treat in the manner
#     that 'hstow adopt' does.  E.g. '.config/mimeapps.list'.
#     List globs matching files for which you don't ever want to edit
#     the copy under DIRECTORY directly, but only via the link/copy
#     under HOME.
#
# TIPS
#
# hstow works well with multiple repositories, perhaps dotfiles/ and
# work-dotfiles/.  In secondary repositories you can create and commit
# relative symlinks to the primary repository's .hstow-unstow-ignore.
#

-- 
Sean Whitton