A modular, robust, and idempotent one-stop dotfiles repository for macOS. Automatically provisions and symlinks configurations for Neovim (LazyVim), VS Code, Kitty, Zsh, Git, and Homebrew with safe backups and automated secret prevention.
- Overview & Philosophy
- Prerequisites
- Quick Start Installation
- Installer Options & Flags
- Repository Structure
- Component Breakdown
- Secret Management & Local Overrides
- Day-to-Day Workflows & Syncing
- How-To Guides
- Troubleshooting
- Single Source of Truth: Everything lives in
~/dev/dotfiles. Files in your home directory (~/.config/nvim,~/.zshrc, etc.) are direct symbolic links. Any edit made in your editor is instantly tracked in Git without manual copying or syncing scripts. - Safety First: The installer never clobbers existing files. Any non-symlink file or folder is safely moved to a timestamped backup directory (
~/.dotfiles_backup/<timestamp>/) before creating symlinks. - Zero Secret Leakage: Uses a strict Two-Tier (Local Override) model. Public configurations are version-controlled; private tokens, work relays, and machine credentials stay in local, untracked
*.localfiles guarded by agitleakspre-commit hook. - Idempotency: Running
./install.shmultiple times is completely safe. Already linked files are recognized and skipped.
Before running the installer on a brand new Mac:
- Command Line Tools:
xcode-select --install
- Homebrew (if not already installed):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - Clone the Repository:
git clone https://github.com/jonnylin13/dotfiles.git ~/dev/dotfiles cd ~/dev/dotfiles
Run the central installer:
cd ~/dev/dotfiles
./install.shWhat the installer automatically executes:
- Creates
~/.zshrc.local,~/.zshenv.local,~/.gitconfig.local, and~/.ssh/config.localtemplates if missing. - Backs up any existing configuration files to
~/.dotfiles_backup/<timestamp>/. - Symlinks all configuration files into your home directory.
- Installs all packages specified in
Brewfileviabrew bundle. - Installs all extensions listed in
config/vscode/extensions.txt. - Installs a
gitleakspre-commit hook in.git/hooks/pre-committo prevent accidental credential commits.
Usage: ./install.sh [options]
Options:
--dry-run Preview symlinks, backups, and actions without modifying the filesystem
--skip-brew Skip running Homebrew bundle (useful for quick dotfile-only relinks)
--skip-vscode Skip installing VS Code extensions
--help, -h Show this help message- Preview what will happen:
./install.sh --dry-run
- Re-link configurations without re-running brew or extensions:
./install.sh --skip-brew --skip-vscode
~/dev/dotfiles/
├── install.sh # One-stop installer entry point
├── Brewfile # Core CLI tools (neovim, ripgrep, gitleaks, etc.)
├── .gitignore # Blocks *.local, .env, keys, and OS artifacts
├── README.md # Comprehensive documentation
├── config/
│ ├── nvim/ # Complete Neovim setup (LazyVim) -> ~/.config/nvim
│ │ ├── init.lua
│ │ ├── lazyvim.json
│ │ ├── lazy-lock.json
│ │ ├── stylua.toml
│ │ └── lua/
│ │ ├── config/ # keymaps.lua, options.lua, autocmds.lua, lazy.lua
│ │ └── plugins/ # ai.lua (Gemini CLI, Claude Code), lspconfig.lua, etc.
│ ├── vscode/ # Visual Studio Code configuration
│ │ ├── settings.json # Settings (Vim mode, formatting, themes)
│ │ ├── keybindings.json # Normal/visual mode keybindings & Harpoon
│ │ └── extensions.txt # List of installed extensions
│ ├── kitty/ # Terminal configuration -> ~/.config/kitty
│ │ └── kitty.conf # Font family (ComicShannsMono Nerd Font), size, behavior
│ ├── zsh/ # Shell configurations
│ │ ├── .zshrc # Interactive shell (aliases, PATH, local loader)
│ │ ├── .zshenv # Universal environment (cargo, node hooks)
│ │ ├── .bash_profile # Login shell paths
│ │ └── .sqrx_helper # Shell helpers
│ ├── git/ # Git configuration -> ~/.gitconfig
│ │ └── .gitconfig # User identity, pull preferences, local include
│ └── ssh/ # SSH configuration -> ~/.ssh/config
│ └── config # GitHub config + Include ~/.ssh/config.local
└── scripts/
└── save-state.sh # Exports current VS Code extensions to dotfiles
- Engine: Built on LazyVim with
lazy.nvim. - Symlink Target:
~/.config/nvim$ ightarrow$~/dev/dotfiles/config/nvim - AI Integrations (
lua/plugins/ai.lua):- Gemini CLI (
<leader>ag/): Configured with dynamic environment extraction viazsh -i -c "env -0". All 70+ variables from your interactive shell (likeGOOGLE_CLOUD_PROJECT, customPATH, and proxy credentials) are forwarded seamlessly to the Gemini terminal panel without slowing down Neovim startup. - Claude Code (
<leader>acc): Dedicated keybindings for toggle, focus, resume, and diff acceptance/rejection.
- Gemini CLI (
- Keybindings: Customized in
lua/config/keymaps.luaandlua/plugins/ai.lua. - Plugin Updates: Run
:Lazy updatein Neovim. Commit changes tolazy-lock.jsonto lock plugin versions across machines.
- Symlink Targets:
~/Library/Application Support/Code/User/settings.json$ ightarrow$config/vscode/settings.json~/Library/Application Support/Code/User/keybindings.json$ ightarrow$config/vscode/keybindings.json
- Keybindings: Includes non-recursive Vim leader mappings (
<leader>w d, split controls, file explorer focus) and Harpoon shortcuts. - Sanitization: Raw API keys are omitted. Extensions like Claude Code inherit environment variables from your shell.
- Symlink Target:
~/.config/kitty$ ightarrow$config/kitty - Font: ComicShannsMono Nerd Font (size 12.0).
- Reloading Config: Press
Ctrl+Shift+F5(orCmd+Control+,on macOS) inside Kitty to reload without restarting.
- Symlink Targets:
~/.zshrc$ ightarrow$config/zsh/.zshrc~/.zshenv$ ightarrow$config/zsh/.zshenv~/.bash_profile$ ightarrow$config/zsh/.bash_profile
- Includes: Google Cloud SDK, Bun, OpenJDK 21, and Homebrew paths.
- Aliases:
dots: Quick jump to~/dev/dotfilesand show git status.lsh: Loads SQRX helper aliases if present.
- SSH Target:
~/.ssh/config$ ightarrow$config/ssh/config- Contains universal GitHub SSH keys and agent configuration.
- Includes
~/.ssh/config.localfor private/internal servers.
- Git Target:
~/.gitconfig$ ightarrow$config/git/.gitconfig- Configures default user identity and rebase preferences.
- Includes
~/.gitconfig.localfor private work emails or signing keys.
To prevent accidental credential leaks when sharing or backing up this repository to GitHub, all sensitive values are decoupled using the Two-Tier Model:
| Configuration | Public / Tracked (in Dotfiles) | Private / Untracked (in ~/) |
|---|---|---|
| Shell Environment | config/zsh/.zshrc |
~/.zshrc.local |
| Universal Shell Env | config/zsh/.zshenv |
~/.zshenv.local |
| SSH Target Hosts | config/ssh/config (GitHub) |
~/.ssh/config.local (Work/Private IPs) |
| Git Configuration | config/git/.gitconfig |
~/.gitconfig.local (Work emails, GPG keys) |
Your private ~/.zshrc.local looks like this:
# Machine-specific / private environment variables (DO NOT COMMIT)
export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_AUTH_TOKEN="your_private_token"
export ANTHROPIC_API_KEY="your_private_key"Both .gitignore and the installed gitleaks pre-commit hook ensure these files can never be committed.
Because every active configuration is a symlink:
- Edit Configs Directly: Change a keymap in Neovim or a setting in VS Code; the file is instantly modified inside
~/dev/dotfiles. - Review Changes:
dots # Jumps to ~/dev/dotfiles and runs git status git diff # Inspect edits
- Commit & Push:
git add config/nvim/lua/config/keymaps.lua git commit -m "feat(nvim): add new buffer switching keymap" git push - Pull on Another Machine:
cd