.dotfiles

   _     _   ___ _ _         
 _| |___| |_|  _|_| |___ ___ 
| . | . |  _|  _| | | -_|_ -|
|___|___|_| |_| |_|_|___|___|

Personal dotfiles configuration for macOS. Automates the setup of development environment, system preferences, and development tools.

Inspired by dotfiles.github.io

Quick Start

Prerequisites

Shell: These scripts target Zsh (macOS default). Run ./install.sh and dotfiles from Zsh.

Before running the installation, complete these steps:

1. Sign in to Mac App Store

   • Open App Store and sign in with your Apple ID

2. Update macOS

   • Go to System Settings → Software Update
   • Install the latest macOS version

3. Install Rosetta (Apple Silicon only)

   softwareupdate --install-rosetta
   

4. Set up SSH keys

   mkdir -p ~/.ssh && cd ~/.ssh
   

   • Option A: Copy SSH keys from another machine:

     # Copy id_ed25519 and id_ed25519.pub (or id_rsa/id_ecdsa)
     chmod 600 ~/.ssh/id_ed25519
     chmod 644 ~/.ssh/id_ed25519.pub
     

   • Option B: Generate a new SSH key

     • The installer will prompt you to create one if none are found

   Add the public key to GitHub (and any other forge / server) before continuing — git_clone and friends use SSH remotes.

5. Install Command Line Tools

   xcode-select --install
   

   • Follow the prompts to install Xcode Command Line Tools

Installation

1. Clone the repository

   git clone git@github.com:milon/dotfiles.git ~/.dotfiles
   

   ~/.dotfiles is conventional; any path works — zshrc and the installer resolve the repo root from the checkout itself.

2. Run the installer

   cd ~/.dotfiles
   ./install.sh
   

   Noninteractive (auto-confirm prompts; skips Atuin login and SSH key generation):

   ./install.sh --yes
   # or: DOTFILES_NONINTERACTIVE=1 ./install.sh
   

The installer will guide you through the setup process with interactive prompts. At the end it offers Atuin Hub login/sync.

Optional (after install): Run dotfiles symlinks so config (including files/config/topgrade.toml) is mirrored under ~/.config/. dotfiles update uses ~/.config/topgrade.toml when present; otherwise it reads the copy inside the repo. Replacing an existing file/dir backs it up under ~/.dotfiles-backup/.

Usage

After installation, you'll have a dotfiles command available in your terminal.

View Available Commands

dotfiles help

or simply:

dotfiles

Global flag: dotfiles --yes <command> (or DOTFILES_NONINTERACTIVE=1) auto-answers confirmations.

Command Reference

Run dotfiles help (or dotfiles) for the current list. In short:

• doctor — Read-only health check: Homebrew + Brewfile drift, dotfile symlinks, mise, git config + hooksPath, Sheldon lock, Atuin login, Lerd status, ~/.zshrc.local permissions, yabai/skhd, SSH key + agent, essentials on PATH. Returns non-zero if anything is broken.
• precheck — Create ~/.zshrc.local / ~/.Brewfile.local if missing; verify SSH key and App Store sign-in.
• manual — Print the remaining manual setup checklist.
• update — Topgrade with files/config/topgrade.toml (brew, casks, Mac App Store, mise, editor extensions, Composer, etc.; steps can be disabled in that file).
• clean — brew cleanup, brew autoremove (unused dependency-only formulae), plus npm / Composer / mise cache cleanup where available.
• symlinks — Link tracked files from files/ into ~ and ~/.config/ (backs up conflicts to ~/.dotfiles-backup/).
• atuin — Log in (or register) with Atuin Hub and sync shell history. Skips login when this machine is already signed in.

When you add a dotfiles subcommand, edit support/commands.sh only (script map, description, and help category). bin/dotfiles and support/help.sh both read that registry.

What Gets Installed

Development Tools

• Editors: Neovim (Lazy.nvim)
• Version Manager: mise (node, python, ruby, java, go, rust)
• Languages: Node.js, Python, PHP, Ruby, Java, Rust
• Databases / data: SQLite; Lerd services (MySQL/Postgres/Redis as needed per site). TablePlus as the SQL GUI.
• Other: Git, Composer, Lerd (.test sites and dashboard)

Applications

• Development: Visual Studio Code, OrbStack (Docker), TablePlus. JetBrains Toolbox (PhpStorm) is per-machine in ~/.Brewfile.local.
• Productivity: 1Password, Raycast, Bartender. Notion, Linear, Slack, and ChatGPT are per-machine in ~/.Brewfile.local.
• System: Aldente, MonitorControl
• Media: IINA, YouTube Music
• Terminal: Ghostty

System Configuration

• Shell configuration (Zsh with Sheldon)
• Git configuration with aliases and colors
• macOS system preferences
• Window management (yabai + skhd hotkeys)
• Symlinks for dotfiles

Customization

Adding Your Own Configurations

1. Per-machine overrides: Edit ~/.zshrc.local (created automatically by precheck.sh, mode 600). Sourced last by ~/.zshrc, so anything in it wins. Use it for personal aliases, work secrets / API tokens, host-specific PATH entries, proxies, AWS profiles, etc. Not tracked.
2. Tracked aliases: Aliases shared across all your machines live in files/home/zsh_aliases.
3. Zsh plugins: Edit files/config/sheldon/plugins.toml, then run sheldon lock (or open a new shell — Sheldon locks on source when needed).
4. Dotfiles (symlinked): Add files to files/ and a corresponding entry to support/symlinks_map.sh.
5. Sourced (not symlinked): files/home/starship.toml, files/home/zsh_aliases, files/home/fzf.sh, and files/home/zsh/*.zsh are loaded through Sheldon via $DOTFILES_DIR. Do not add them to symlinks_map.sh — that would fight the current load order.
6. Homebrew packages: Shared packages go in support/Brewfile. Packages for one machine only go in ~/.Brewfile.local (created by precheck.sh, not tracked). dotfiles brew installs the shared file first, then the local one.
7. VS Code Custom CSS/JS (optional, not installed): optional/vscode/{style.css,script.js} are not symlinked. Point the Custom CSS and JS Loader extension at $DOTFILES_DIR/optional/vscode/style.css and $DOTFILES_DIR/optional/vscode/script.js if you want the command-palette styling.

Repository Configuration

• Personal repos: Edit support/repos.sh — both dotfiles clone and dotfiles pull read from this single manifest.

Troubleshooting

Installation Issues

• SSH key errors: Ensure your SSH keys are properly configured and added to GitHub
• Homebrew errors: Make sure you have admin privileges and internet connection
• Permission errors: Some scripts may require sudo for system-level changes

Common Commands

# Re-run a specific setup step
dotfiles brew

# Re-run precheck / see leftover manual tasks
dotfiles precheck
dotfiles manual

# Check what will be installed
cat support/Brewfile

# View installation logs
# Check the output from install.sh for specific errors

Notes

• The installer will prompt you for confirmation at various steps (./install.sh --yes skips prompts)
• Some steps require manual intervention (e.g., signing into apps)
• The manual command (and install’s final step) reminds you of remaining manual tasks

Contributing

This is a personal dotfiles repository, but suggestions and improvements are welcome!

Contact

• Twitter: @to_milon
• Email: contact[@]milon[.]im

License

See LICENSE file for details.