From 4b01fd8c44983de9fde6f977734625e7be7c518a Mon Sep 17 00:00:00 2001
From: Kris Lamoureux <kris@lamoureux.io>
Date: Mon, 6 Oct 2025 21:47:34 -0400
Subject: [PATCH] Revert to root level package structure for stow

- Document xstow usage for systems lacking GNU Stow
- Add SPDX headers to .stowrc for license compliance
- Add REUSE specification compliance notes to README
---
 .stowrc                                   |  7 ++-
 README.md                                 | 58 +++++++++++++++++++----
 {pkgs/bash => bash}/.bash_aliases         |  0
 {pkgs/bash => bash}/.bashrc               |  0
 {pkgs/git => git}/.gitconfig              |  0
 {pkgs/vim => vim}/.vim/colors/monokai.vim |  0
 {pkgs/vim => vim}/.vimrc                  |  0
 7 files changed, 53 insertions(+), 12 deletions(-)
 rename {pkgs/bash => bash}/.bash_aliases (100%)
 rename {pkgs/bash => bash}/.bashrc (100%)
 rename {pkgs/git => git}/.gitconfig (100%)
 rename {pkgs/vim => vim}/.vim/colors/monokai.vim (100%)
 rename {pkgs/vim => vim}/.vimrc (100%)

diff --git a/.stowrc b/.stowrc
index 8215c9c..1f941f8 100644
--- a/.stowrc
+++ b/.stowrc
@@ -1,3 +1,6 @@
---dir=pkgs
+# SPDX-FileCopyrightText: 2025 Kris Lamoureux <kris@lamoureux.io>
+# SPDX-License-Identifier: 0BSD
+
 --target=$HOME
---verbose
+--no-folding
+--verbose=2
diff --git a/README.md b/README.md
index 03e8fc2..0b71765 100644
--- a/README.md
+++ b/README.md
@@ -5,23 +5,61 @@ SPDX-License-Identifier: 0BSD
 
 ## Dotfiles
 
-Use GNU Stow to slow down your home directory listings with my
+Use GNU Stow (or xstow) to slow down your home directory listings with my
 [accumulated sludge](https://web.archive.org/web/20141205101508/https://plus.google.com/+RobPikeTheHuman/posts/R58WgWwN9jp).
 
 ### Setup
 
-1.  Clone into a subdirectory of `$HOME` and change into it
+1.  Create the `~/.local` directory (if it doesn't already exist)
 
-        git clone https://git.krislamo.org/kris/dotfiles.git ~/.dotfiles && \
-        cd ~/.dotfiles
+        mkdir -p ~/.local
 
-2.  List available configuration packages
+2.  Clone the repository
 
-        basename -a pkgs/*/
+        git clone https://git.krislamo.org/kris/dotfiles.git ~/.local/dotfiles
 
-3.  Dry run `stow` with `-n` against configuration sets and verify output before
-    running
+3.  Navigate to the repository's directory
 
-        stow -n $(basename -a pkgs/*/)
+        cd ~/.local/dotfiles
 
-    - Use `-nvv` for more verbose output.
+4.  Dry run `stow` with `-n` against configuration sets and verify, e.g.,
+
+        stow -n vim
+
+### Using xstow
+
+On systems without GNU Stow, you can build and use `xstow` as an alternative for
+managing symlinks. Build a statically linked binary using
+[xstow-builder](https://git.krislamo.org/kris/xstow-builder), then copy it to
+`~/.local/bin/` on your target system. You need to specify the target directory
+`-t` because `xstow` does not use the `.stowrc` file.
+
+#### Bootstrapping
+
+If you copy `xstow` to `~/.local/bin` before stowing the `bash` package, you'll
+hit a bootstrapping problem. You need `xstow` in your `$PATH` to easily use it,
+but you need the updated `.bashrc` (from the `bash` package) to add
+`~/.local/bin` to your `$PATH` in the first place. To break this cycle, invoke
+`xstow` directly with its full path for the initial setup.
+
+1.  Place the `xstow` binary at `~/.local/bin/xstow`
+2.  Sideline your `.bashrc` file
+
+        cp ~/.bashrc ~/.bashrc.bak
+
+3.  Inside the repository, dry run `xstow` ( `-n` ) using the full path
+
+        ~/.local/bin/xstow -t "$HOME" -v 2 -n bash
+
+    - Remove `-n` only once you are sure it will work as intended
+    - After stowing the `bash` package, start a new shell or source `.bashrc`
+
+### Licensing
+
+This project follows the [REUSE](https://reuse.software) specification.
+
+Efforts have been made to include SPDX license headers and a LICENSES directory
+with the appropriate licenses, since not all configurations in these dotfiles
+are original.
+
+Please ensure that the repository passes the `reuse lint` check.
diff --git a/pkgs/bash/.bash_aliases b/bash/.bash_aliases
similarity index 100%
rename from pkgs/bash/.bash_aliases
rename to bash/.bash_aliases
diff --git a/pkgs/bash/.bashrc b/bash/.bashrc
similarity index 100%
rename from pkgs/bash/.bashrc
rename to bash/.bashrc
diff --git a/pkgs/git/.gitconfig b/git/.gitconfig
similarity index 100%
rename from pkgs/git/.gitconfig
rename to git/.gitconfig
diff --git a/pkgs/vim/.vim/colors/monokai.vim b/vim/.vim/colors/monokai.vim
similarity index 100%
rename from pkgs/vim/.vim/colors/monokai.vim
rename to vim/.vim/colors/monokai.vim
diff --git a/pkgs/vim/.vimrc b/vim/.vimrc
similarity index 100%
rename from pkgs/vim/.vimrc
rename to vim/.vimrc