hstow: documentation

1 files changed, 89 insertions, 17 deletions

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 <http://www.gnu.org/licenses/>.
 
-# 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 <https://dwheeler.com/essays/filenames-in-shell.html>.
 
 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 <https://dwheeler.com/essays/filenames-in-shell.html>.
     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