update to readme

README.md

@@ -1,16 +1,10 @@
-<img src="_images/dotfiles-logo.png" alt="dotfiles logo" width="350">
+<img src="misc/__images/dotfiles-logo.png" alt="dotfiles logo" width="350">
 
-### [Ed Heltzel's](https://github.com/edheltzel) personal configuration (.dotfiles) for MacOS using Fish shell.
+### My personal configuration (.dotfiles) for  macOS using 🐠 Fish shell.
 
-This is my personal configuration (.dotfiles) for macOS that involves web development and devops which are deployed using [GNU Stow](https://www.gnu.org/software/stow/). There are also files for provisioning a new machine and setting up my environment.
+This is my personal configuration (.dotfiles) for macOS that involves web development and devops which are deployed using [GNU Stow][STOW]. There are also files for provisioning a new machine and setting up my environment – they are highly personalized and built over time, so what works for me probably won't work for you. But take inspiration all you want and make it your own. _**So proceed with caution, and use at your own risk**_.
 
-## So what's next?
-
-Zach Holman wrote a great article about [dotfiles](https://zachholman.com/2010/08/dotfiles-are-meant-to-be-forked/) and how they are meant to be forked. I agree with this to a point... I'm more of a fan of the idea that you should take what you like and leave the rest, since dotfiles are highly personalized, and built over time so what works for me probably wont't work for you, but take inspiration all you want and make it your own.
-
-Again, this is My personal setup – _**So proceed with caution, and use at your own risk**_.
-
-## ⚙️ Usage and the Install
+## Get Started
 
 <details>
   <summary><strong>Caveats for non-Apple Silicon (Intel)</strong></summary>
@@ -38,179 +32,187 @@ Again, this is My personal setup – _**So proceed with caution, and use at your
   7. `csrutil status` -> should read `System Integrity Protection status: disabled.`
 </details>
 
+### 👋 For future, Ed:
 
-### SSH Keys
-I use [ssh keys](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) to authenticate with GitHub and other services. You generally want to create new keys for each device you use, but you can also use the same key on multiple devices. **I have started using two different keys for my multi-machine work flow.** One key is for my personal devices and the other is for my work devices. This allows me to easily revoke access to my work devices if I discontinue a relationship with a company or customer, and not have to worry about my personal keys being compromised or having to change them.
+Since we have a bad habit of forgetting things:
 
-If you look at the `.gitconfig` you'll see the use of an include `path = ~/.gitconfig.local` this file is created during the provisioning process and is populated with the correct configuration based on the hostname.
+1. Install Xcode Command Line Tools `sudo softwardupdate -i -a && xcode-select --install`
+    - This will install `git` and `make` if not already installed.
+2. Setup SSH keys for GitHub
+    - [Generate a new ssh keys][GENSSHKEY] or restore existing key if needed.
+2. Clone this repository to `~/.dotfiles`
+3. Run the `bootstrap.sh` script or `make install` command
 
-1. [Generate a new ssh keys](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) and add to your GitHub account. - _Optional_
-  - If you want to restore your key I'd do that before moving on.
+## Whats Inside
 
-2. Clone this repository
+### GNU Stow
 
-```
-git clone [email protected]:edheltzel/dotfiles.git
-```
+Originally I used a series of custom scripts to create symlinks, it worked but I've since switched to using [GNU Stow][STOW]. This is way more manageable and easier to understand.
 
-3. Run the `bootstrap.sh` script
-   1. Alternatively, only run the `setup.sh` scripts in specific subfolder if you don't need everything - You must start with the `./packages/.setup.sh` script first. This will prevent any installation errors.
-4. Install [Fisher](https://github.com/jorgebucaran/fisher) and Plugins -- _Optional_
+### Makefile
 
-```bash
-curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher
-```
+So with the addition of Stow, I added a `makefile` – I treat this like NPM scripts. You need to be in the root of `~/.dotfiles` to execute any of the `make` commands.
 
-#### Commit and Tag Signing
+The following commands are available:
 
-##### SSH Signing
+```shell
+help          Show this help message (default)
+install       Bootstraps a new machine
+run           Symlink all dotfiles w/Stow
+stow          Add individual packages w/Stow
+unstow        Remove individual packages w/Stow
+delete        Delete all dotfiles w/Stow
+update        Sync & clean dead symlinks w/Stow
+```
 
-I use SSH commit signing over GPG. GPG is there if I need it, but I prefer SSH. For a few resources to help get this setup:
+#### Bootstrapping
 
-- [Git Merge Workshop - Simplify Signing with SSH](https://github.com/git-merge-workshops/simplify-signing-with-ssh/tree/main)
-- [Gitlab SSH Commit Signing Doc](https://docs.gitlab.com/ee/user/project/repository/ssh_signed_commits/)
+- `make install` task, it will execute the `bootstrap.sh` script. This script will install the necessary package managers, packages with dependencies, applications, clone the necessary repositories, configure the `~/.gitconfig.local` and symlink dotfiles using Stow.
 
-The `.gitconfig` includes `.gitconfig.local`
+#### Stowing and Unstowing
 
-```shell
-  [meta]
-    isLocalConfig = true
-  [user]
-    signingkey = PATH_TO_YOUR_KEY
-  [gpg "ssh"]
-    allowedSignersFile = PATH_TO_YOUR_ALLOWED_SIGNERS_FILE
-```
-If you choose to use this make sure you look at that `./git/git.sh`, this script is where the provisioning of `.gitconfig.local` happens.
+There are two options for managing packages with Stow:
 
-<details>
-  <summary>GPG Commit Signing - <em>optional</em></summary>
+1. Just use Stow: `stow nvim` or `stow -D nvim` _(unstow)_
+2. Use the Makefile: `make stow pkg=nvim` or `make unstow pkg=nvim`
+    - The `pkg=` variable must be specified.
 
-  GPG signing is set to `TRUE` by default. If you rather not enable GPG then execute: `git config --global commit.gpgsign false` and remove the GPG packages from the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile).
+## Stow Packages
 
-  [renew expired gpg](https://gist.github.com/krisleech/760213ed287ea9da85521c7c9aac1df0)
+- dots (dots/)
+  - misc dotfiles that are stored in the $HOME directory
+- git (git/)
+  - git configuration
+- fish (fish/)
+  - XDG Base Directory – Reference: [XDG Base Directory][XDGRef] for more information. To edit/set the XDG Base Directory variables, you can edit the `~/fish/.config/fish/conf.d/paths.fish` file. Hopefully, this will keep the `$HOME` directory clean and organized.
+- nvim (nvim/)
+  - When I need Vim, I use [LazyVim](https://www.lazyvim.org/) - lightly customized.
+- config (config/)
+  - Configuration files for various applications
+- warp (warp/)
+  - I like Warp but I really like iTerm2
+- vscode (vscode/)
+  - I use the sync feature in vscode to keep my settings and extensions in sync. The `settings.json` and `keybindings.json` are symlinked out of habit.
 
-  [Generate new key and assign to global git config](https://gist.github.com/paolocarrasco/18ca8fe6e63490ae1be23e84a7039374#:~:text=It%20means%20that%20is%20not,secret%20keys%20available%20in%20GPG.)
+## Scripts
 
-  main take away:
+Any of the scripts can be run individually at any time to update/reset as needed.
 
-  - `gpg --list-secret-keys --keyid-format=long`
-  - Copy key
-  - set key for your git user
-    - `git config --global user.signingkey <your key>`
-  - If you need help setting this up GPG:
-    - follow the Github article for [Signing Commits](https://help.github.com/en/articles/signing-commits) to set up you GPG key(s).
-    - I found this [GIST helpful](https://gist.github.com/cezaraugusto/2c91d141ddec026753051ffcace3f1f2)
-    - To get VSCode setup follow this [article](https://dev.to/devmount/signed-git-commits-in-vs-code-36do)
-  - **Please Note** if you used the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile), Cask installed the macOS [GPG Suite](https://gpgtools.org/) via `cask 'gpg-suite-no-mail'` -- _(alternatively)_ update the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile) with `cask 'gpg-suite' to include GPGMail.
+### macOS (macos/)
 
-</details>
+`macos.sh` - Executes a long list of commands pertaining to macOS Preferences – **DO NOT** blindly run this script - it is a WIP with each macOS update things change.
 
+### packages (packages/)
 
-### GNU Stow
+- `packages.sh` - Installs the Brewfile and each package manager's packages based on the `.txt` files.
 
-Originally I used a series of custom scripts to create symlinks, it worked but I've since switched to using [GNU Stow](https://www.gnu.org/software/stow/). I feel like everything is way more manageable and  easier to understand – I previously would have to review each script to make sure I wasn't going to break my system.
+### repositories (repos/)
 
-### Makefile
+- `repos.sh` - Clones the repositories in the `` files at the corresponding locations
 
-So with the addition of Stow, I've added a `makefile` to help with the process of managing my dotfiles, which I find to be a simple and helpful way to execute the Stow commands and other tasks. To use the `make` commands, you need to be in the root of the `~/.dotfiles` directory.
+### private (private/)
 
-The following commands are available:
+- `private.sh` - Left empty on purpose
 
-```shell
-help          Show this help message (default)
-install       Bootstraps a new machine
-run           Symlink all dotfiles w/Stow
-stow          Add individual packages w/Stow
-unstow        Remove individual packages w/Stow
-delete        Delete all dotfiles w/Stow
-update        Sync & clean all symlinks w/Stow
-```
-
-When executing the `make install` command, it will execute the `bootstrap.sh` script. This script will install the necessary packages with dependencies, applications, clone the necessary repositories, configure Git, and symlink dotfiles using Stow.
+### duti (duti/)
 
-When running the `make stow` or `make unstow` commands you need specify the package you want to stow or unstow by setting the `pkg=` variable.
+- `duti.sh` - Sets the default applications for file types
+    - run `./duti/duti.sh` to reset the default applications for file types
 
-**Stow Example:**
-```shell
-# stows the nvim package
-make stow pkg=nvim
-```
-**Unstow Example:**
-```shell
-# unstows the nvim package
-make unstow pkg=nvim
-```
+### misc (misc/)
 
-### XDG Base Directory
+There isn't anything of substance in the `misc/` directory, it's just a place to store files that don't fit anywhere else and I like to keep handy.
 
-Reference: [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for more information. To edit/set the XDG Base Directory variables, you can edit the `~/fish/.config/fish/conf.d/paths.fish` file.
+### Helper Scripts (scripts/)
 
-### macOS Preferences (macos/)
+- `functions.sh` - Contains helper functions for symlinked files and printing progress messages
 
-- setup.sh - Executes a long list of commands pertaining to macOS Preferences
-  - **I can not stress enough to read this and change this for what works for you.**
-  - **DO NOT** blindly run this script - it is a WIP with each macOS update things change.
+## Troubleshooting
+<details>
+  <summary>Fish: Fisher Plugin Manager</summary>
+  In the past, Fisher (fish plugin manager) will do something weird or will introduce a breaking change - just reinstall Fisher.
 
-### Misc Dotfiles (misc/)
+  ```bash
+  curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher
+  ```
+</details>
+<details>
+  <summary>Node Development</summary>
+  Node Version switching for Node development, takes advantage of [fnm](https://github.com/Schniz/fnm) for managing Node versions, which supports both `.nvmrc` and `.node-version` files.
 
-- setup.sh - Symlinks all the associated rc and other dot files to your `~/` _(home directory)_
-- Special Mentions:
-  - `.tigrc` - [tig](https://jonas.github.io/tig/) – configured with pretty colors and layout for git diff and logs
-  - `.eslintrc` - has specific configuration for my JS workflow
-  - `bat/config` - [bat](https://github.com/sharkdp/bat) – a clone of cat with syntax highlighting
-  -
+  - Install happens in the `Brewfile` by running
 
-### Packages (packages/)
+  ```shell
+  brew install fnm
+  ```
 
-- setup.sh - Installs the contents of the package manager files and the Brewfile
+  For Completions run:
 
-### Repositories (repos/)
+  ```shell
+  fnm completions --shell fish
+  ```
 
-- setup.sh - Clones the repositories in the `` files at the corresponding
-  locations
+  Make sure you run:
 
-### Vim (nvim/)
+  ```shell
+  ./fish/./setup.sh
+  ```
 
-I use NeoVim, when I need Vim. The distribution I use is [LazyVim](https://www.lazyvim.org/)
+  This will symlink the `fnm.fish` file in `~/.config/fish/conf.d` _(It might be helpful to `source ~/.config/fish/config.fish`)_
 
-- setup.sh - Clone LazyVim to `~/.config/nvim`
+  **Note:** FNM has the ability to auto switch Node versions if there is a `.node-version` or `.nvmrc` file - this is enabled by default
 
-### Helper Scripts (scripts/)
+  ```shell
+  # automatically run fnm use
+  fnm env --use-on-cd | source
+  ```
 
-- functions.sh - Contains helper functions for symlinked files and printing
-  progress messages
-### Node development
+  > Please note that when you change your default Node version, you will need to run `npm install --global (cat node_packages.txt)` to include `corepack` in the global packages. This will ensure that `pnpm` and `yarn` are available.
+</details>
+<details>
+  <summary>Git: Commit and Tag Signing</summary>
 
-Node Version switching for Node development, takes advantage of [fnm](https://github.com/Schniz/fnm) for managing Node versions, which supports both `.nvmrc` and `.node-version` files.
+  **SSH Signing**
 
-- Install happens in the `Brewfile` by running
+  I use SSH commit signing over GPG. GPG is there if I need it, but I prefer SSH. For a few resources to help get this setup:
 
-```shell
-brew install fnm
-```
+  - [Git Merge Workshop - Simplify Signing with SSH](https://github.com/git-merge-workshops/simplify-signing-with-ssh/tree/main)
+  - [Gitlab SSH Commit Signing Doc](https://docs.gitlab.com/ee/user/project/repository/ssh_signed_commits/)
 
-For Completions run:
+  The `.gitconfig` includes `.gitconfig.local`
 
-```shell
-fnm completions --shell fish
-```
+  ```shell
+    [meta]
+      isLocalConfig = true
+    [user]
+      signingkey = PATH_TO_YOUR_KEY
+    [gpg "ssh"]
+      allowedSignersFile = PATH_TO_YOUR_ALLOWED_SIGNERS_FILE
+  ```
+  If you choose to use this make sure you look at that `./git/git.sh`, this script is where the provisioning of `.gitconfig.local` happens.
+  <details>
+    <summary>GPG Commit Signing - <em>optional</em></summary>
 
-Make sure you run:
+    GPG signing is set to `TRUE` by default. If you rather not enable GPG then execute: `git config --global commit.gpgsign false` and remove the GPG packages from the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile).
 
-```shell
-./fish/./setup.sh
-```
+    [renew expired gpg](https://gist.github.com/krisleech/760213ed287ea9da85521c7c9aac1df0)
 
-This will symlink the `fnm.fish` file in `~/.config/fish/conf.d` _(It might be helpful to `source ~/.config/fish/config.fish`)_
+    [Generate new key and assign to global git config](https://gist.github.com/paolocarrasco/18ca8fe6e63490ae1be23e84a7039374#:~:text=It%20means%20that%20is%20not,secret%20keys%20available%20in%20GPG.)
 
-**Note:** FNM has the ability to auto switch Node versions if there is a `.node-version` or `.nvmrc` file - this is enabled by default
+    main take away:
 
-```shell
-# automatically run fnm use
-fnm env --use-on-cd | source
-```
+    - `gpg --list-secret-keys --keyid-format=long`
+    - Copy key
+    - set key for your git user
+      - `git config --global user.signingkey <your key>`
+    - If you need help setting this up GPG:
+      - follow the Github article for [Signing Commits](https://help.github.com/en/articles/signing-commits) to set up you GPG key(s).
+      - I found this [GIST helpful](https://gist.github.com/cezaraugusto/2c91d141ddec026753051ffcace3f1f2)
+      - To get VSCode setup follow this [article](https://dev.to/devmount/signed-git-commits-in-vs-code-36do)
+    - **Please Note** if you used the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile), Cask installed the macOS [GPG Suite](https://gpgtools.org/) via `cask 'gpg-suite-no-mail'` -- _(alternatively)_ update the [Brewfile](https://github.com/edheltzel/dotfiles/blob/master/packages/Brewfile) with `cask 'gpg-suite' to include GPGMail.
 
-> Please note that when you change your default Node version, you will need to run `npm install --global (cat node_packages.txt)` to include `corepack` in the global packages. This will ensure that `pnpm` and `yarn` are available.
+  </details>
+</details>
 
 #### 🙏 Special Thanks
 
@@ -220,17 +222,20 @@ Gotta thanks to [kalis.me blog post](https://kalis.me/dotfiles-automating-macos-
 
 ## 📝 TODOs
 
+- [ ] create a single line install script to execute bootstrap.sh
+- [ ] use makefile to execute bootstrap.sh and install.sh
+- [ ] Look into [Tuckr](https://github.com/RaphGL/Tuckr)
+- [x] update make unstow to include only the available stow package or all
 - [x] add customizations to lazyvim
 - [x] add vscode settings and symlink to dotfiles
 - [x] add XDG Base Directory support
-- [ ] Look into [Tuckr](https://github.com/RaphGL/Tuckr)
-- [ ] update make unstow to include only the available stow package or all
-- [ ] create a single line install script to execute bootstrap.sh
-- [ ] update install.sh to include duti, packages, repos, and set local git config
-- [ ] use makefile to execute bootstrap.sh and install.sh
-- [ ] update README
-  - [ ] include XDG info
-  - [ ] include Stow info
-  - [ ] include Make info
-  - [ ] include New bootstrap process
-  - [ ] include New install process (makefile)
+- [x] update README
+  - [x] include XDG info
+  - [x] include Stow info
+  - [x] include Make info
+  - [x] include New bootstrap process
+  - [x] include New install process (makefile)
+
+[XDGRef]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+[STOW]: https://www.gnu.org/software/stow/
+[GENSSHKEY]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent