dotfiles

Personal configuration files managed with GNU Stow.

Installation

macOS (Full Setup)

git clone git@github.com:yungweng/dotfiles.git ~/repos/dotfiles
cd ~/repos/dotfiles

make macos   # Runs: preflight → brew → setup → stow → hooks → shell switch

make macos handles everything automatically:

1. Preflight — installs Xcode CLI Tools and Homebrew if missing
2. Brew — interactive package install (or essentials-only on fresh macOS with bash 3)
3. Setup — git identity, GPG key, GitHub CLI auth, npm globals, SSH Keychain
4. Install — stows all packages (backs up conflicting files automatically)
5. Hooks — enables gitleaks pre-commit hook
6. Shell — offers to switch default shell to fish

macOS (Step by Step)

cd ~/repos/dotfiles
make preflight  # Check/install prerequisites
make brew       # Install Homebrew packages (interactive)
make setup      # Interactive setup (name, email, GPG, usernames)
make install    # Stow all packages
make hooks      # Enable gitleaks pre-commit hook

Linux (No Root Required)

For headless servers or environments without brew:

git clone https://github.com/yungweng/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./setup-linux.sh   # Installs tools, runs setup, stows configs

This installs fish, starship, fzf, and ripgrep to ~/.local/bin, runs interactive setup, and symlinks configs. Works on x86_64 and aarch64.

Individual Packages

stow fish      # Stow a single package
stow -D fish   # Remove symlinks for a package
stow -R fish   # Re-stow (fix stale symlinks)

Note: Use stow --adopt <package> if the target files already exist. This moves existing files into the repo and creates symlinks. Run git diff afterward to review changes.

Makefile Targets

Target	Description
make help	Show all available targets
make preflight	Check/install prerequisites (Xcode CLI Tools, Homebrew, Git)
make setup	Interactive setup (name, email, GPG, usernames, gh auth, SSH Keychain)
make install	Stow all packages into ~ (with conflict backup)
make uninstall	Unstow all packages
make restow	Re-stow all packages (fix stale symlinks)
make brew	Install Homebrew packages interactively (skips installed; falls back to essentials on bash < 4)
make brew-essentials	Install only essential dev packages (~30: terminal, shell, editor, git, languages)
make brew-all	Install ALL Homebrew packages non-interactively (120+)
make brew-dump	Update Brewfile from currently installed packages
make hooks	Enable gitleaks pre-commit hook
make macos	Full macOS setup (preflight + brew + setup + stow + hooks)
make linux	Linux bootstrap (no root required)
make lint	Run shellcheck and fish syntax checks locally
make clean	Find broken symlinks pointing to this repo
make list	List all stow packages

Contents

Package	Description
bash/	Bash shell config (.bashrc, .inputrc)
fish/	Fish shell configuration, functions, and scripts
ghostty/	Ghostty terminal config
starship/	Starship prompt config
git/	Git configuration with aliases
gitmux/	Git status in tmux status bar
claude/	Claude Code CLI — config, custom agents, slash commands, skills, and hooks
codex/	Codex CLI — config, prompts, and skills
tmux/	tmux terminal multiplexer config (cheat sheet)
vim/	Vim editor config
npm/	npm global prefix setting
topgrade/	Topgrade system updater config
btop/	btop system monitor config
htop/	htop process viewer config
gh/	GitHub CLI preferences
direnv/	direnv environment manager config
zed/	Zed editor keymap and settings

Non-stow	Description
setup.sh	Interactive setup — name, email, GPG, gh auth, npm globals, SSH Keychain
setup-linux.sh	Linux bootstrap — installs tools, runs setup, stows configs (no root required)
brew-interactive.sh	Interactive Homebrew installer — skips already-installed packages
Makefile	Task runner — install, uninstall, brew, hooks, and more (make help)
Brewfile	Homebrew package manifest — full (120+ packages)
Brewfile.essentials	Homebrew essentials — terminal, shell, editor, git, languages (~30 packages)
hooks/	Git pre-commit hook (shellcheck, fish syntax, gitleaks)
macos/	macOS-specific scripts (defaults, Touch ID for sudo)
.github/workflows/	CI — shellcheck, fish syntax linting, stow install tests on macOS + Linux

Usage

Add a new config to an existing package

Just add the file to the package with the correct path structure:

# Example: add a new fish function
# File goes in: <dotfiles>/fish/.config/fish/functions/myfunction.fish
# Stow creates: ~/.config/fish/functions/myfunction.fish

Re-stow after adding files

stow -R fish  # Restow (re-creates symlinks)

Remove symlinks

stow -D fish  # Delete symlinks for fish package

Add a new package

1. Create the package directory with the target path structure:

   mkdir -p <dotfiles>/newapp/.config/newapp

2. Add your config file:

   cp ~/.config/newapp/config <dotfiles>/newapp/.config/newapp/

3. Remove the original and stow:

   rm ~/.config/newapp/config
   stow newapp

Directory Structure

Stow mirrors the directory structure relative to ~. The .stowrc file sets the target to home (~).

<dotfiles>/
├── bash/
│   ├── .bashrc                         → ~/.bashrc
│   └── .inputrc                        → ~/.inputrc
├── fish/
│   ├── .config/fish/                   → ~/.config/fish/
│   │   ├── config.fish
│   │   ├── conf.d/rustup.fish
│   │   ├── secrets.fish.example        (template — copy to secrets.fish)
│   │   └── functions/                  (brew, cloud, coy-review, key bindings)
│   └── bin/claude-cleanup              → ~/bin/claude-cleanup
├── ghostty/
│   └── .config/ghostty/                → ~/.config/ghostty/
├── starship/
│   └── .config/starship.toml           → ~/.config/starship.toml
├── git/
│   └── .gitconfig                      → ~/.gitconfig
├── gitmux/
│   └── .gitmux.conf                    → ~/.gitmux.conf
├── claude/
│   └── .claude/                        → ~/.claude/
│       ├── CLAUDE.md.template           (template — generated by setup.sh)
│       ├── settings.json
│       ├── agents/                     (deep-dive-investigator, research-thinker)
│       ├── commands/                   (slash commands: most-used, seminar, workflow, ...)
│       ├── hooks/                      (skill evaluation hooks)
│       └── skills/                     (12 skills: browser, audio, gh-cli, react, ...)
├── codex/
│   └── .codex/                         → ~/.codex/
│       ├── AGENTS.md.template           (template — generated by setup.sh)
│       ├── config.toml
│       ├── prompts/                    (review, investigation, openspec prompts)
│       └── skills/                     (react, web-design-guidelines)
├── tmux/
│   ├── .tmux.conf                      → ~/.tmux.conf
│   └── TMUX-CHEATSHEET.md             (reference, not stowed)
├── vim/
│   └── .vimrc                          → ~/.vimrc
├── npm/
│   └── .npmrc                          → ~/.npmrc
├── topgrade/
│   └── .config/topgrade.toml           → ~/.config/topgrade.toml
├── btop/
│   └── .config/btop/btop.conf          → ~/.config/btop/btop.conf
├── htop/
│   └── .config/htop/htoprc             → ~/.config/htop/htoprc
├── gh/
│   └── .config/gh/config.yml           → ~/.config/gh/config.yml
├── direnv/
│   └── .config/direnv/direnv.toml      → ~/.config/direnv/direnv.toml
├── zed/
│   └── .config/zed/                    → ~/.config/zed/ (keymap.json, settings-shared.json)
├── .github/
│   └── workflows/
│       ├── lint.yml                    (CI: shellcheck + fish syntax)
│       └── test-install.yml            (CI: stow install test on macOS + Linux)
├── hooks/
│   └── pre-commit                      (shellcheck + fish syntax + gitleaks)
├── macos/
│   ├── defaults.sh                     (Trackpad, Finder, Dock, Safari, TextEdit preferences)
│   └── setup-touchid-sudo.sh           (Touch ID for sudo)
├── Makefile                            (task runner: make help)
├── Brewfile                            (Homebrew package manifest)
├── brew-interactive.sh                 (interactive Homebrew installer)
├── .stowrc                             (sets --target=~)
├── .gitignore
├── setup.sh                            (interactive personalization)
├── setup-linux.sh                      (Linux bootstrap, no root)
└── README.md

Secrets

API tokens and credentials are stored in ~/.config/fish/secrets.fish (not tracked by git). setup.sh creates this file automatically from the template. To set up manually:

cp <dotfiles>/fish/.config/fish/secrets.fish.example ~/.config/fish/secrets.fish
# Edit secrets.fish and fill in your tokens

Required variables:

Variable	Purpose	Generate at
CR_PAT	GitHub Container Registry PAT	GitHub Tokens
SONAR_TOKEN	SonarQube/SonarCloud API token	SonarCloud Security
NPM_TOKEN	npm publish token (used by ~/.npmrc)	npm Tokens

This file is sourced automatically by config.fish.

Git Hooks

The pre-commit hook runs three checks on staged files:

1. shellcheck — lints staged .sh files
2. fish --no-execute — syntax-checks staged .fish files
3. gitleaks — scans for accidentally committed secrets

# Activate (already done by make hooks / make macos)
git config core.hooksPath hooks

# Required tools
brew install shellcheck gitleaks  # macOS

CI (.github/workflows/lint.yml) runs the same checks on push and PR.

macOS Setup

# Set system preferences (Trackpad, Finder, Dock, Safari, TextEdit)
bash macos/defaults.sh

# Enable Touch ID for sudo (persists across system updates)
sudo bash macos/setup-touchid-sudo.sh

Git Aliases

Alias	Description
prune-local	Remove local branches whose remote tracking branch is gone

Fish Aliases

Alias	Expands to
docker-compose	docker compose (v2 compatibility)
lsla	ls -la

Fish Abbreviations

Abbr	Expands to
cy	claude --dangerously-skip-permissions
claudeyolo	claude --dangerously-skip-permissions
coy	codex --dangerously-bypass-approvals-and-sandbox
codexyolo	codex --dangerously-bypass-approvals-and-sandbox

Fish Utility Functions

Function	Description
mkcd <dir>	Create directory and cd into it
backup <file>	Create timestamped backup (file.bak-20250206-183000)
sizeof <path>	Show size of file or directory
copy [text]	Copy args or stdin to clipboard (cross-platform)
cloud	cd to iCloud Drive
coy-review	Run parallel Codex code reviews (-n count, -b branch, -t thinking)
claude-cleanup	Kill detached Claude background processes, show freed memory

Ghostty Shortcuts

Shortcut	Action
Cmd+Shift+P	Command palette
Cmd+D	Split pane right
Cmd+Shift+D	Split pane down
Cmd+Option+P	Quick terminal (global — works from any app)
Cmd+Shift+S	Toggle secure input
Cmd+Plus / Cmd+- / Cmd+0	Font size: increase / decrease / reset