Allow user to specify the target directory

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

@@ -237,7 +237,7 @@ is_single_excluded() {
 show_help() {
   local exit_code=${1:-0}
 
-  $PRINT "Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
+  $PRINT "Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
   $PRINT "see lsrc(1) and rcm(7) for more details"
 
   exit $exit_code
@@ -257,11 +257,12 @@ 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) DEST_DIR="$OPTARG" ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
       v) verbosity=$(($verbosity + 1));;
       q) verbosity=$(($verbosity - 1));;

bin/rcdn.in

@@ -23,7 +23,7 @@ remove_link() {
 show_help() {
   local exit_code=${1:-0}
 
-  $PRINT "Usage: rcdn [-hqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
+  $PRINT "Usage: rcdn [-hqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
   $PRINT "see rcdn(1) and rcm(7) for more details"
 
   exit $exit_code
@@ -44,13 +44,14 @@ 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) DEST_DIR="$OPTARG" ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
       S) symlink_dirs="$(append_variable "$symlink_dirs" "$OPTARG")" ;;
       s) never_symlink_dirs="$(append_variable "$never_symlink_dirs" "$OPTARG")" ;;

bin/rcup.in

@@ -183,7 +183,7 @@ handle_file() {
 show_help() {
   local exit_code=${1:-0}
 
-  $PRINT "Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
+  $PRINT "Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]"
   $PRINT "see rcup(1) and rcm(7) for more details"
 
   exit $exit_code
@@ -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 ;;
@@ -222,6 +222,7 @@ handle_command_line() {
       k) run_hooks=1 ;;
       K) run_hooks=0 ;;
       q) verbosity=$(($verbosity - 1)) ;;
+      T) DEST_DIR="$OPTARG" ;;
       t) arg_tags="$(append_variable "$arg_tags" "$OPTARG")" ;;
       S) symlink_dirs="$(append_variable "$symlink_dirs" "$OPTARG")" ;;
       s) never_symlink_dirs="$(append_variable "$never_symlink_dirs" "$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

share/rcm.sh.in

@@ -189,4 +189,5 @@ append_variable() {
 
 if [ -r "$RCRC" ]; then
   . "$RCRC"
+  DEST_DIR="${TARGET:-$DEST_DIR}"
 fi

test/lsrc-usage.t

@@ -3,12 +3,12 @@
 -h should output usage information and exit 0
 
   $ lsrc -h
-  Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
+  Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
   see lsrc(1) and rcm(7) for more details
 
 Unsupported options should output usage information and exit EX_USAGE
 
   $ lsrc --version
-  Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
+  Usage: lsrc [-FhqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
   see lsrc(1) and rcm(7) for more details
   [64]

test/rcrc-target.t

@@ -0,0 +1,13 @@
+  $ . "$TESTDIR/helper.sh"
+
+The target for rcup should be specifiable in .rcrc and expand variables
+
+  $ touch .dotfiles/example
+  > mkdir "$HOME/target-rcrc"
+
+  $ echo 'TARGET=$HOME/target-rcrc' > $HOME/.rcrc
+
+  $ rcup -v > /dev/null
+
+  $ assert_linked "$HOME/target-rcrc/.example" "$HOME/.dotfiles/example"
+

test/rcup-target-subst.t

@@ -0,0 +1,11 @@
+  $ . "$TESTDIR/helper.sh"
+
+Should be able to modify the global dotfiles target using a command line argument,
+with environment variables within being expanded
+
+  $ touch .dotfiles/example
+  > mkdir "$HOME/target"
+
+  $ rcup -v -T '$HOME/target' > /dev/null
+
+  $ assert_linked "$HOME/target/.example" "$HOME/.dotfiles/example"

test/rcup-target.t

@@ -0,0 +1,10 @@
+  $ . "$TESTDIR/helper.sh"
+
+Should be able to modify the global dotfiles target using a command line argument
+
+  $ touch .dotfiles/example
+  > mkdir "$HOME/target"
+
+  $ rcup -v -T "$HOME/target" > /dev/null
+
+  $ assert_linked "$HOME/target/.example" "$HOME/.dotfiles/example"

test/rcup-usage.t

@@ -3,12 +3,12 @@
 -h should output usage information and exit 0
 
   $ rcup -h
-  Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
+  Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
   see rcup(1) and rcm(7) for more details
 
 Unsupported options should output usage information and exit EX_USAGE
 
   $ rcup --version
-  Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
+  Usage: rcup [-CfhiKkqVv] [-B HOSTNAME] [-d DOT_DIR] [-I EXCL_PAT] [-S EXCL_PAT] [-s EXCL_PAT] [-T DIR] [-t TAG] [-U EXCL_PAT] [-u EXCL_PAT] [-x EXCL_PAT]
   see rcup(1) and rcm(7) for more details
   [64]