add debug option and update readme

Readme.md

@@ -1,23 +1,84 @@
-# Personal dotfiles (eg .config)
+# dot
+
+Manage your personal dotfiles with [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html).
+
+## Usage
+
+Keep your dotfiles in your git repo and symlink them into the correct place, allowing you to edit them without forgetting to copy those changes back into your repo.
+
+Further, you can apply your dotfiles to another system by simply checking out your dotfiles repo and running:
+```bash
+./dot apply <package>
+```
+Any existing dotfiles on the system will be left as is. So there is no risk of accidentally clobbering untracked dotfiles.
+> NOTE: because clobbering existing dotfiles is avoided, you will have to manually delete or move existing config files out of the way. This only applies to files with same name and location as those in your dotfiles repo. Any other unrelated files (even in the same directory) can co-exist just fine.
+
+Your applied config can be cleaned up by running:
+```bash
+./dot remove <package>
+```
+This removes the symlinks to your dotfiles that were previously applied effictively wiping your config.
+
+Only symlinks to your config files are created, and only symlinks are removed. Therefore there is no risk of losing any changes you may have made since you applied your config.
+
+## Repo Structure
 
 The files here are structured for compatibility with [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html) to keep things as
 simple as possible and reduce reliance on custom logic.
 
-The config for each program is stored in a single subdirectory (a
-[package](#packages)).
+You can package you dotfiles however you like, either by program or a collection of programs.
 
-I've added the notion of package [targets](#targets) to handle config for
-programs that do not store all config in a single location.
+[Packages](#packages) that require config files in multiple locations are supported, so you don't have to jump through hoops to keep all your config in a single file or directory.
+
+You can optionally apply only part of your config depending on requirements:
+```bash
+./dot apply <package> system
+```
+```bash
+./dot apply <package> user
+```
 
 # Packages
 
-All config files for a specific program are kept together in a package.
+A package is simply a collection of dotfiles (or any config file) that should be applied together.
+
+For added flexability, a package may also contain one or more [targets](#targets).
+
+## Package Structrue
+
+All config files for a specific package are kept together in a top level subdirectory of the repo.
 
-* Each subdirectory of this repo represents a different dotfiles package.
-* The directory structure is compatible with GNU stow.
+The directory structure of each package [target](#targets) is compatible with GNU stow.
 
-There is a custom wrapper bash script (uses GNU Stow) that you can use to easily
-install a config package:
+A package is therefore simply one of thes top level directories and can consist of a config for one or more programs depending on your needs.
+
+## Exampe Repo Structure
+
+When discussing how package [targets](#targets) are handled, the following repo structure will be assumed:
+
+*Example* with dotfiles repo checked out to `./dotfiles` (`DOTFILES_DIR`):
+```plain
+./dotfiles
+├── Readme.md
+├── ssh
+│   ├── system
+│   │   └── etc
+│   │       └── ssh
+│   │           ├── ssh_config
+│   │           └── sshd_config
+│   └── user
+│       └── .ssh
+│           └── config
+└── vim
+    └── .vimrc
+```
+This shows a repo with two packages:
+* vim - no targets (so is assumed to be a `user` target)
+* ssh - two targets: `system` and `user`
+
+## The ./dot Script
+
+There is a custom wrapper bash script (useing GNU Stow) that you can use to easily install a config package:
 
 *Example* Install the config for the `vim` package:
 ```bash
@@ -51,33 +112,22 @@ package target is passed as the package name.
 
 # Targets
 
+At risk of improving upon the perfection that is GNU Stow, the concept of package targets is added to handle programs that do not store all config in a single location, or for when you want to keep some config separate depending on the target.
+
+For example, you may want to stow your personal *and* system ssh(d) config on your home computer, but only your personal ssh config on a remote server.
+
+By keeping the system and user config separate (as is typically the case when installed), then you can optionally instruct GNU Stow to apply only one of the targets.
+
 Each package may have files that target the system or the user file heirarchy.
+
 Therefore, each package may have a subdirectory containing any of:
 
    * system
    * user
 
-*Example* with dotfiles repo checked out to `./dotfiles` (`DOTFILES_DIR`):
-
-```plain
-./dotfiles
-├── Readme.md
-├── ssh
-│   ├── system
-│   │   └── etc
-│   │       └── ssh
-│   │           ├── ssh_config
-│   │           └── sshd_config
-│   └── user
-│       └── .ssh
-│           └── config
-└── vim
-    └── .vimrc
-```
-
 In the case no target subdirectories are present for a given package, then the target is assumed to be the `user` target.
 
-More targets may be added in the future:
+NOTE: More targets may be added in the future:
 
    * user-config (`/home/acme/.config`)
    * user-local (`/home/acme/.local`)
@@ -85,9 +135,9 @@ More targets may be added in the future:
    * system-local (`/usr/local`)
    * system-lib (`/usr/local/lib`)
 
-For now, to ensure maximum compatibility, it's more flexable to require each package to supply the specific heirarchy.
+But for now, `$HOME` and `/` is suffient to cover most use cases whilst keeping the package structure as simple as possible (albeiet with long somewhat redundant paths).
 
-## User Target
+## The User Target
 
 All directories under the user target are relative to `$HOME`.
 
@@ -95,14 +145,18 @@ All directories under the user target are relative to `$HOME`.
 ```bash
 ./dot apply vim
 ```
+Given the [example repo structure](#exampe-repo-structure), the resulting `$HOME` dir will look like:
+```
+/home/acme
+└── .vimrc -> ./path/to/dotfiles/vim/.vimrc
+```
 
-On GNU Stow compatible system this is equivalent to:
-
+On a GNU Stow compatible system this is equivalent to:
 ```bash
 stow -d "$DOTFILES_DIR" -t "/home/$USER" vim
 ```
 
-## System Target
+## The System Target
 
 All directories under the system targt are relative to `/`.
 
@@ -110,6 +164,22 @@ All directories under the system targt are relative to `/`.
 ```bash
 ./dot apply ssh
 ```
+Given the [example repo structure](#exampe-repo-structure), the resulting `$HOME` and `/` dir will look like:
+```
+/home/acme
+└── .ssh
+    ├── config -> ./path/to/dotfiles/ssh/user/.ssh/config
+    ├── id_ecdsa
+    ├── id_ecdsa.pub
+    └── known_hosts
+/etc
+└── ssh
+    ├── ssh_config -> ./path/to/dotfiles/ssh/system/etc/ssh/ssh_config
+    ├── ssh_config.d
+    └── sshd_config -> ./path/to/dotfiles/ssh/system/etc/ssh/sshd_config
+```
+> NOTE: given that one of the ssh [package](#packages) targets is a `system` target, you will likely need to run `./dot` as root. In most cases, this should be fine as the files created will be symlinks, so permissions are not relevant.
+> However, if this is not an option for you, you can apply the `user` and `system` targets separately, requiring only running the `system` target as root.
 
 On GNU Stow compatible system this is equivalent to:
 
@@ -118,3 +188,18 @@ stow -d "$DOTFILES_DIR/ssh" -t "/home/$USER" user
 stow -d "$DOTFILES_DIR/ssh" -t / system # needs root permissions obviously
 ```
 
+
+# Debug
+
+To see what GNU Stow would do without making any changes, set the DEBUG
+environment var.
+
+```bash
+DEBUG=2 ./dot apply vim
+```
+
+The var can be an integer between 1 and 5 to increase verbosity.
+
+Further more, if the `DEBUG` environment variable is set, then the stow commands
+being run will be printed - handy if you would prefer to just run stow directly
+but would like a template to work with.

dot

@@ -6,8 +6,12 @@ action="$1"
 package="$2"
 target="${3:-}"
 
-stow="echo stow" # for debugging
-#stow="stow"
+if [ "${DEBUG:=}" ]
+then
+    stow="stow --simulate --verbose=${DEBUG}"
+else
+    stow="stow"
+fi
 
 DOTFILES_DIR="${DOTFILES_DIR:=}"
 [ "$DOTFILES_DIR" ] || DOTFILES_DIR=$(pwd)
@@ -34,7 +38,10 @@ _stow(){
     stow_target_dir="$2"
     stow_action="$3"
     stow_package="$4"
-    $stow -d "${stow_dir}" -t "${stow_target_dir}" "${stow_action}" "${stow_package}"
+    (
+        [ "$DEBUG" ] && set -x
+        $stow -d "${stow_dir}" -t "${stow_target_dir}" "${stow_action}" "${stow_package}"
+    )
 }
 
 action=$(action_to_arg "$action")