holman richmond does dotfiles

Your dotfiles are how you personalize your system. These are mine.

If you're interested in the philosophy behind why projects like these are awesome, you might want to read a post on the subject.

topical

Everything's built around topic areas. If you're adding a new area to your forked dotfiles — say, "Java" — you can simply add a java directory and put files in there. Anything with an extension of .zsh will get automatically included into your shell. Anything with a prefix of symlink will get symlinked without the prefix into $HOME when you run script/bootstrap, whether the source is a file or a directory. This differs from Holman's layout so the file extension stays unchanged, which helps with syntax highlighting. A + in the filename maps to a / in the destination path under $HOME.

what's inside

A lot of stuff. Seriously, a lot of stuff. Check them out in the file browser above and see what components may mesh up with you. Fork it, remove what you don't use, and build on what you do use.

components

There's a few special files in the hierarchy.

• bin/: Anything in bin/ will get added to your $PATH and be made available everywhere.
• topic/*.zsh: Any files ending in .zsh get loaded into your environment.
• topic/path.zsh: Any file named path.zsh is loaded first and is expected to setup $PATH or similar.
• topic/completion.zsh: Any file named completion.zsh is loaded last and is expected to setup autocomplete.
• topic/install.sh: Any file named install.sh is executed when you run script/install. To avoid being loaded automatically, its extension is .sh, not .zsh.
• topic/symlink*: Any file or directory starting with symlink gets symlinked into your $HOME. This is so you can keep all of those versioned in your dotfiles but still keep those autoloaded files in your home directory.
  • To further nest symlinks into subdirectories under $HOME, use + signs to signify additional directory delimiters. So for example, the file topic/symlink.folder_name+file_name would get symlinked to $HOME/.folder_name/file_name when you run script/bootstrap.

symlink example

This repo uses the source filename to determine the destination path.

• zsh/symlink.zshrc becomes ~/.zshrc
• vscode/symlink.vscode+argv.json becomes ~/.vscode/argv.json
• vscode/symlinkLibrary+Application Support+Code+User+settings.json becomes ~/Library/Application Support/Code/User/settings.json
• skills/symlink.agents+skills becomes ~/.agents/skills

Run script/bootstrap to create the managed symlinks, and run script/test-symlink to verify that they still point to the expected files.

install

Run this:

git clone https://github.com/r-richmond/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
script/bootstrap

This will symlink the appropriate files in .dotfiles to your home directory. Everything is configured and tweaked within ~/.dotfiles.

To validate that the expected symlinks are present and pointing at the right files, run script/test-symlink. Subsequently, if you add new symlink* files you can run script/heal-symlink to automatically restore missing or broken symlinks.

The main file you'll want to change right off the bat is zsh/symlink.zshrc, which sets up a few paths that'll be different on your particular machine.

bugs

I want this to work for everyone; that means when you clone it down it should work for you even though you may not have something installed, for example. That said, I do use this as my dotfiles, so there's a good chance I may break something if I forget to make a check for a dependency.

If you do hit an issue, feel free to open an issue and I'll do my best to fix it. If you want to contribute a fix, even better!

thanks

I forked Holman's' excellent dotfiles Most of the code in these dotfiles stem or are inspired from Holman's original project.

things left to do

• change keyboard ctrl-option-cmd-space - system preferences > keyboard > shortcuts > input sources
• configure alfred powerpack
  • setup powerpack & link to sync folder & setup theme

macOS keyboard and mouse shortcuts

macos/defaults-macos-keyboard.sh stores:

• Caps Lock to Escape for all connected keyboards and previously saved keyboard IDs. IDs are discovered automatically; other modifier swaps are preserved. These per-host preferences survive restarts, unlike transient hidutil remaps. Rerun the script after connecting a new, previously unknown keyboard.
• Command-Option-backtick to show or hide Notification Center (symbolic hotkey 163).
• Control + mouse button 4 for Mission Control (38), Control + mouse button 5 for Application Windows (39), and Control + mouse button 3 for Show Desktop (42), including their Shift variants (40, 41, 43). These match the saved settings, including Control; button parameters are bitmasks 8, 16, 4.

Run bash macos/defaults-macos-keyboard.sh to apply these settings, then log out and back in so macOS reloads them. The macOS installer also runs this script. The script stores preferences; it does not force a logout or restart apps. It requires jq and a macOS version whose hidutil list supports --ndjson.

Run bash tests/macos/keyboard_test.bash on macOS to check keyboard discovery, modifier-map preservation, and saved keyboard and mouse shortcut values. Tests require jq and redirect preference writes to temporary plists without changing live settings.

FAQ

1. I want to get started quick. How do I install this on a new machine?

Clone the repo into ~/.dotfiles and run the bootstrap script. That will set up the managed symlinks and kick off the installer flow for the topic directories.

git clone https://github.com/r-richmond/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
script/bootstrap

2. I added a new .zsh file. What do I need to do to have it take effect?

Files ending in .zsh are loaded by your shell startup flow, so after adding one you just need to start a new shell or reload your zsh config. If the file changes PATH setup or completion behavior, opening a fresh terminal is the safest option.

source ~/.zshrc

3. I added a new file that should be symlinked. How do I ensure it is named correctly and where it will go?

Name the file or directory with a symlink prefix and treat + as a directory separator under $HOME. For example, vscode/symlink.vscode+argv.json maps to ~/.vscode/argv.json, and script/test-symlink will verify that the destination is what you expect.

script/test-symlink

4. After I verify the file is set up properly and the symlink is in the right place, which script do I use to symlink it?

script/heal-symlink