From b73824921864710cc5ecbaa278cbdf1032a06958 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sun, 29 Jan 2023 10:50:51 -0700 Subject: hstow: documentation --- bin/hstow | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 89 insertions(+), 17 deletions(-) (limited to 'bin/hstow') diff --git a/bin/hstow b/bin/hstow index b54b9c94..ff7d4eb4 100755 --- a/bin/hstow +++ b/bin/hstow @@ -17,18 +17,93 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -# The point of this script is to obtain minimally functional dotfiles -# handling in one's home directory on even machines that lack a Perl -# interpreter. As such, many of GNU Stow's more advanced features are -# not reimplemented. Git depends on Perl, for now, but my two methods -# for deploying my dotfiles to remote machines -- my INSINUATE-DOTFILES +# +# 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. +# +# COMMENTARY +# +# The point of this script is to obtain functional dotfiles handling in +# one's home directory on even machines that lack a Perl interpreter. +# As such, many of GNU Stow's more advanced features are not +# reimplemented. Git depends on Perl, for now, but my two methods for +# deploying my dotfiles to remote machines -- my INSINUATE-DOTFILES # Consfigurator property and 'insinuate-dotfiles' shell script -- do not -# depend on having Git on the remote side. See also 'bstraph' script. +# depend on having Git on the remote side. +# +# SEE ALSO +# +# GNU Stow, a Perl program. # -# We completely skip filenames containing control characters, including -# newline and tab, as POSIX find(1) lacks -print0, and it's unlikely -# you'd need to stow any such files. -# Technique from . set -efu IFS="$(printf '\n\t')" @@ -129,15 +204,15 @@ stow1 () { elif ! [ -e .hstow-always-adopt ]; then adoptp=0 else - # Globs matching files that (i) always/often have their symlinks - # replaced with regular files when applications access them; and - # (ii) we don't ever want to edit the copy under $DIR directly, - # but only via the link/copy under $HOME. adoptp="$(printf \ 'rel ~ /%s/' \ "$(awk -f ~/src/dotfiles/lib-src/globs2ere.awk \ .hstow-always-adopt)")" fi + # We completely skip filenames containing control characters, + # including newline and tab, as POSIX find(1) lacks -print0, and + # it's unlikely you'd need to stow any such files. + # See . find . $(globs_to_find_args .hstow-local-ignore ".git/*") \ ! -name . ! -type d ! -name "$cchars" ! -name .gitignore \ ! -name .hstow-local-ignore ! -name .hstow-always-adopt \ @@ -180,9 +255,6 @@ stow1 () { unstow () { cd "$HOME" - # .hstow-unstow-ignore is a list of globs matching dirs into which - # we'll never stow anything. We have this for the sake of speed. - # # awk's close() calls pclose(3), completing all the link deletions. # POSIX.1 "Utility Description Defaults", "Consequences of Errors" # implies that should rmdir(1) encounter a non-empty directory, it -- cgit v1.2.3