dotfiles

Dotfiles for macOS (relevant for Catalina 10.15+)

Setup

sudo softwareupdate -i -a

mkdir -p ~/projects/personal && cd ~/projects/personal
git clone https://github.com/mvshmakov/dotfiles.git && cd dotfiles

git submodule update --recursive --init
stow --stow -vt ~ */

./home/scripts/setup.sh

Nix is not installed by default; opt in with INSTALL_NIX=1 ./home/scripts/setup.sh (see the Brewfile TODO about the Nix migration).

To restow/repair the symlinks, use stow --restow -vt ~ */. To simulate the stow process outcome without modifying the file system, use stow --stow --no -vt ~ */. */ is the ZSH glob, which expands only in the folders. Retired configs live in .archive/ — hidden so the */ glob never stows them.

If you want to add the submodule, consider running git submodule add --name {name} https://github.com/{author}/{name}.git {tool}/.config/{tool}/{name} instead of just adding the corresponding submodule definition in the .gitmodules. If you want to delete the submodule, see delete_git_submodule.md.

ITerm2's com.googlecode.iterm2.plist is in the $HOME folder, so you need to set it also in ITerm2 settings to load it.

The last step would be to generate new SSH key pair and add it to the required services.

One should also enable the Reduced motion option in the System Preferences to increase the speed of window/desktop switching.

Useful commands

1. Dump all the installed brew packages: brew list > packages.txt
2. Dump all the installed brew casks: brew list --cask > casks.txt
3. Dump all VSCode extensions to shell commands: code --list-extensions | xargs -L 1 echo code --install-extension
4. stow --restow {directory}

Zoxide-based navigation

• z {pattern}[TAB] will expand the path Z detected

brew

If you want your current system configuration to match your Brewfile (purge all non-fixed deps)

brew bundle --force cleanup

How to upgrade brew:

• brew update update brew itself
• brew upgrade --greedy update all the packages together with :latest and :auto_update

Neovim after stow

• Run :Copilot setup

Atuin

• Daemon mode requires a socket to be available, the brew services start atuin solves this

yabai & skhd

Both auto-start on boot: their launchd plists are versioned in launchctl/ (whitelisted in .gitignore) and stowed into ~/Library/LaunchAgents. home/scripts/services.sh bootstraps them during setup; afterwards launchd loads them on every login.

• Manage the services with the official commands only: yabai --start-service / --stop-service / --restart-service (same for skhd).
• Never run --install-service/--uninstall-service: ~/Library/LaunchAgents is a stow symlink into this repo, so they would overwrite/delete the tracked plists (an unexpected plist diff in git status is the telltale). The tracked plists match the generated ones except for PATH, which is trimmed to a stable machine-agnostic set instead of a snapshot of the installing shell's PATH.
• One-time manual step per machine: grant Accessibility to yabai and skhd, plus Input Monitoring to skhd (System Settings -> Privacy & Security; macOS prompts on first start).
• The yabai scripting addition is not used, so no SIP/sudoers changes are needed.
• The skhd plist/label must stay com.koekeishiya.skhd until an skhd release ships the author's account rename (koekeishiya -> asmvik) - the binary hardcodes that label and plist path. yabai has already migrated to com.asmvik.yabai.

TODO

• Warn about exiting from the git commit message template on non-empty message.
• If possible, simplify the GPG signature sign in git log to make it smaller but still present.
• Use markdownlint for the documentation.
• Run prettier on md/yml/etc. on pre-commit.
• Use shfmt + shellcheck + checkbashisms on scripts from dotfiles + document it.
• Align all shell scripts with Google shell scripting guidelines + apply all the linting.
• Run CI with pre-commit hooks.
• Use git subtree instead of git module to manage dependencies.

Useful links

• awesome-dotfiles
• zsh-users

Literature

• macOS Config
• Colors in terminal
• ANSI Escape Sequences
• "[WTF IS \033[30;47m???", a practical cheat-sheet
• sudo insults - though for macOS it is needed to recompile the sudo binary to enable --with-all-insults
• Which nerd font to select