Skip to content
jonnylin13Public

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

19 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🛠️ Dotfiles

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.


📑 Table of Contents


💡 Overview & Philosophy

  1. 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.
  2. 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.
  3. 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 *.local files guarded by a gitleaks pre-commit hook.
  4. Idempotency: Running ./install.sh multiple times is completely safe. Already linked files are recognized and skipped.

📋 Prerequisites

Before running the installer on a brand new Mac:

  1. Command Line Tools:
    xcode-select --install
  2. Homebrew (if not already installed):
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  3. Clone the Repository:
    git clone https://github.com/jonnylin13/dotfiles.git ~/dev/dotfiles
    cd ~/dev/dotfiles

🚀 Quick Start Installation

Run the central installer:

cd ~/dev/dotfiles
./install.sh

What the installer automatically executes:

  • Creates ~/.zshrc.local, ~/.zshenv.local, ~/.gitconfig.local, and ~/.ssh/config.local templates 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 Brewfile via brew bundle.
  • Installs all extensions listed in config/vscode/extensions.txt.
  • Installs a gitleaks pre-commit hook in .git/hooks/pre-commit to prevent accidental credential commits.

⚙️ Installer Options & Flags

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

Example Commands:

  • Preview what will happen:
    ./install.sh --dry-run
  • Re-link configurations without re-running brew or extensions:
    ./install.sh --skip-brew --skip-vscode

📁 Repository Structure

~/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

🔍 Component Breakdown

Neovim (LazyVim)

  • 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 via zsh -i -c "env -0". All 70+ variables from your interactive shell (like GOOGLE_CLOUD_PROJECT, custom PATH, 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.
  • Keybindings: Customized in lua/config/keymaps.lua and lua/plugins/ai.lua.
  • Plugin Updates: Run :Lazy update in Neovim. Commit changes to lazy-lock.json to lock plugin versions across machines.

Visual Studio Code

  • 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.

Terminal (Kitty)

  • Symlink Target: ~/.config/kitty $ ightarrow$ config/kitty
  • Font: ComicShannsMono Nerd Font (size 12.0).
  • Reloading Config: Press Ctrl+Shift+F5 (or Cmd+Control+, on macOS) inside Kitty to reload without restarting.

Shell (Zsh, Bash & Profiles)

  • 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/dotfiles and show git status.
    • lsh: Loads SQRX helper aliases if present.

SSH & Git

  • SSH Target: ~/.ssh/config $ ightarrow$ config/ssh/config
    • Contains universal GitHub SSH keys and agent configuration.
    • Includes ~/.ssh/config.local for private/internal servers.
  • Git Target: ~/.gitconfig $ ightarrow$ config/git/.gitconfig
    • Configures default user identity and rebase preferences.
    • Includes ~/.gitconfig.local for private work emails or signing keys.

🔒 Secret Management & Local Overrides

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)

Setting Up Local Secrets:

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.


🔄 Day-to-Day Workflows & Syncing

Because every active configuration is a symlink:

  1. Edit Configs Directly: Change a keymap in Neovim or a setting in VS Code; the file is instantly modified inside ~/dev/dotfiles.
  2. Review Changes:
    dots       # Jumps to ~/dev/dotfiles and runs git status
    git diff   # Inspect edits
  3. Commit & Push:
    git add config/nvim/lua/config/keymaps.lua
    git commit -m "feat(nvim): add new buffer switching keymap"
    git push
  4. Pull on Another Machine:
    cd