Allow user to specify the target directory

A new default target can be set using:
* A target option in rcrc(5)
* -T flag

(based on the work in #255) for #246

Author: jonathan 'jonthn' buschmann

Makefile.am

@@ -55,7 +55,10 @@ TESTS = \
 	test/rcup-hooks-failure.t \
 	test/rcup-hooks-run-in-situ.t \
 	test/rcup-hooks-run-in-order.t \
-	test/rcup-spaces.t
+	test/rcup-spaces.t \
+	test/rcup-target.t \
+	test/rcup-target-subst.t \
+	test/rcrc-target.t
 
 dist_check_SCRIPTS = $(TESTS)
 dist_check_DATA = test/helper.sh

NEWS.md.in

@@ -1,6 +1,7 @@
 rcm (@PACKAGE_VERSION@) unstable; urgency=low
 
   * Feature: rcup/rcdn hooks can bail early (Patrick Brisbin)
+  * Feature: specify a target directory instead of $HOME (see -T or TARGET setting .rcrc(5))
   * Documentation improvement (Teo Ljungberg)
 
  -- Mike Burns <[email protected]>  Fri, 30 Dec 2022 11:43:00 -0500

bin/lsrc.in

@@ -257,12 +257,13 @@ handle_command_line() {
   local undotted=
   local never_undotted=
 
-  while getopts :FVqvhI:x:B:S:s:U:u:t:d: opt; do
+  while getopts :FVqvhI:x:B:S:s:U:u:t:d:T: opt; do
     case "$opt" in
       F) show_sigils=1;;
       h) show_help ;;
       I) includes="$(append_variable "$includes" "$OPTARG")" ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
+      T) DEST_DIR="$OPTARG" ;;
       v) verbosity=$(($verbosity + 1));;
       q) verbosity=$(($verbosity - 1));;
       d) dotfiles_dirs="$(append_variable "$dotfiles_dirs" "$OPTARG")" ;;

bin/rcdn.in

@@ -44,14 +44,15 @@ handle_command_line() {
   local never_undotted=
   local hostname=
 
-  while getopts :VqvhIKk:x:S:s:U:u:t:d:B: opt; do
+  while getopts :VqvhIKk:x:S:s:U:u:t:d:B:T: opt; do
     case "$opt" in
       h) show_help ;;
       B) hostname="$OPTARG" ;;
       I) includes="$(append_variable "$includes" "$OPTARG")" ;;
       k) run_hooks=1 ;;
       K) run_hooks=0 ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
+      T) DEST_DIR="$OPTARG" ;;
       S) symlink_dirs="$(append_variable "$symlink_dirs" "$OPTARG")" ;;
       s) never_symlink_dirs="$(append_variable "$never_symlink_dirs" "$OPTARG")" ;;
       U) undotted="$(append_variable "$undotted" "$OPTARG")" ;;

bin/rcup.in

@@ -209,7 +209,7 @@ handle_command_line() {
   REPLACE_ALL=0
   GENERATE=
 
-  while getopts :CVqvfghikKI:x:S:s:U:u:t:d:B: opt; do
+  while getopts :CVqvfghikKI:x:S:s:U:u:t:d:B:T: opt; do
     case "$opt" in
       B) hostname="$OPTARG" ;;
       C) always_copy=1 ;;
@@ -223,6 +223,7 @@ handle_command_line() {
       K) run_hooks=0 ;;
       q) verbosity=$(($verbosity - 1)) ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
+      T) DEST_DIR="$OPTARG" ;;
       S) symlink_dirs="$(append_variable "$symlink_dirs" "$OPTARG")" ;;
       s) never_symlink_dirs="$(append_variable "$never_symlink_dirs" "$OPTARG")";;
       U) undotted="$(append_variable "$undotted" "$OPTARG")" ;;
@@ -302,7 +303,7 @@ if [ "$pre_up_ret" -ne 0 ]; then
   exit "$pre_up_ret"
 fi
 
-dests_and_srcs="$(eval "lsrc $LS_ARGS")"
+dests_and_srcs="$(eval "lsrc -T \"$DEST_DIR\" $LS_ARGS")"
 
 saved_ifs="$IFS"
 IFS='

man/lsrc.1

@@ -19,7 +19,8 @@
 .Op files ...
 .Sh DESCRIPTION
 This program lists all configuration files, both the sources in the
-dotfiles directories and the destinations in your home directory.
+dotfiles directories and the destinations in the destination
+directory (by default your home directory).
 .
 See
 .Xr rcup 1 ,
@@ -90,6 +91,8 @@ protect it from your shell.
 .
 .It Fl t Ar TAG
 list dotfiles according to TAG
+.It Fl T Ar DIR
+consider dotfiles having destinations within target directory DIR
 .
 .It Fl U Ar excl_pat
 the rc files or directories matching this pattern will not be symlinked or

man/rcdn.1

@@ -98,6 +98,8 @@ This can be repeated.
 .It Fl t Ar TAG
 remove dotfiles according to
 .Ar TAG
+.It Fl T Ar DIR
+remove dotfiles relative to target directory DIR
 .It Fl U Ar EXCL_PAT
 any rc file or directory that matches
 .Ar EXCL_PAT

man/rcm.7.mustache

@@ -139,6 +139,22 @@ option. For example:
 .Pp
 .Dl mkrc -U bin
 .
+.Ss COMMON PROBLEM: CHANGING THE TARGET LOCATION DEPENDENT ON THE VALUE OF AN ENVIRONMENT VARIABLE
+By default, the rcm suite will assume that all dotfiles are installed relative to
+.Pa $HOME .
+If instead, the dotfiles are to be installed to, say,
+.Pa $XDG_CONFIG_HOME ,
+there are two options:
+
+The default target can be redefined by using
+.Va TARGET
+location in the rcrc file, or by using the
+.Fl T
+flag.  References to environment variables can be specified in any of these,
+e.g.
+.Pp
+.Dl rcup -T $XDG_CONFIG_HOME
+.
 .Sh QUICK START FOR EMPTY DOTFILES DIRECTORIES
 This section is for those who do not have an existing dotfiles
 directory and whose dotfiles are standard.
@@ -249,6 +265,35 @@ macOS users should see the
 .Sx BUGS
 section for more details.
 .
+.Sh ALTERNATIVE TARGET INSTALL LOCATIONS
+.
+Sometimes it is useful to instruct rcm to install dotfiles to a location
+other than
+.Sx $HOME .
+
+The default target directory is taken to be the first specified by:
+.Bl -enum offset indent -compact
+.It
+command-line flag
+.Fl T ,
+for an invocation of rcup, rcdn, or lsrc.
+.It
+Variable
+.Va TARGET
+in the rcrc file. (see
+.Xr rcrc 5
+and the
+.Sx FILES
+section below)
+.It
+$HOME
+.El
+
+A target location can also be specified on a per dotfiles directory basis.
+This is achieved by placing meta-file
+.Pa target
+in the root, which contains a single line denoting the desired target directory.
+
 .Sh STANDALONE INSTALLATION SCRIPT
 .
 The

man/rcrc.5

@@ -54,6 +54,8 @@ command, but this command is non-standard and can prove unreliable. The
 variable forces a known hostname.
 .It Va TAGS
 the default tags.
+.It Va TARGET
+the new default location to manage dotfiles relative to.
 .
 .It Va SYMLINK_DIRS
 a space-separated list of patterns. Directories matching a pattern are

man/rcup.1

@@ -93,6 +93,8 @@ This option can be repeated.
 .It Fl t Ar TAG
 install dotfiles according to
 .Ar TAG .
+.It Fl T Ar DIR
+install dotfiles relative to target directory DIR
 .It Fl U Ar EXCL_PAT
 any rc file that matches
 .Ar EXCL_PAT