dotfiles

Personal macOS configs, managed as a single repo and symlinked into place with GNU Stow.

What's tracked

Package	Symlinks to	Tool
zsh	~/.zshrc	shell (Powerlevel10k, fzf, zoxide)
tmux	~/.config/tmux/tmux.conf	tmux 3.6+
aerospace	~/.config/aerospace/	tiling WM
ghostty	~/.config/ghostty/	terminal
karabiner	~/.config/karabiner/	keyboard remapper
nvim	~/.config/nvim_LazyVim/	Neovim (LazyVim, NVIM_APPNAME=nvim_LazyVim)
cheats	~/.config/cheats/	quick-reference tables — cheat <topic>

Secrets are not in this repo: .zshrc sources ~/.zsh/secrets.zsh, which is created by hand (chmod 600) and never tracked.

Fresh machine

git clone <this-repo> ~/dotfiles
cd ~/dotfiles
./bootstrap.sh          # Homebrew + brew bundle + fzf-tab + stow + TPM

How it works (stow + tree folding)

Each top-level dir is a stow "package" whose internal layout mirrors $HOME. stow <pkg> creates symlinks; because the target dirs don't pre-exist, stow folds them — e.g. ~/.config/aerospace becomes a single directory symlink into this repo. So:

• Edit configs anywhere — the editor follows the symlink to the real file here.
• Do git from ~/dotfiles — that's the only repo. git status inside a folded dir like ~/.config/aerospace also works (you're physically inside this repo), but ~/dotfiles is the canonical place.

Common tasks

cd ~/dotfiles
stow <pkg>            # link a package
stow -D <pkg>         # unlink a package
stow -R <pkg>         # re-link after adding files
git add -A && git commit -m "..."   # changes are already in this repo via symlinks

Cheatsheets

Quick-reference tables for shortcuts live in cheats/.config/cheats/*.md and render in the terminal with glow:

cheat              # fzf picker with live preview
cheat screenshots  # render one sheet (tab-completes topic names)

Seeded topics: keyboard (system-wide Karabiner editing + Mac shortcuts), readline (zsh line editor), aerospace (tiling WM), screenshots. Add a topic by dropping a new .md file in that dir — no code change needed. These sheets are the canonical source; karabiner/…/QUICK-REFERENCE.md keeps only the modifier model.

macOS defaults

Some apps store settings in macOS defaults rather than a config file, so they can't be symlinked. Those tweaks live as code in macos/defaults.sh (idempotent, re-runnable; also invoked by bootstrap.sh):

./macos/defaults.sh

Currently configures Maccy (clipboard history, cask "maccy"): keeps a 200-item history of text + images, opens centered on ⌘⇧C, and pastes on Enter (pasteByDefault). That last bit needs Maccy enabled under System Settings → Privacy & Security → Accessibility.

Gotchas

• Karabiner writes automatic_backups/ and assets/ into its (folded) config dir — both are gitignored.
• tmux TPM lives at ~/.tmux/plugins/tpm (runtime, not tracked); it auto-clones on first tmux launch.
• Moving ~/dotfiles elsewhere breaks the relative symlinks — re-run stow.