.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

The installer will guide you through the setup process with interactive prompts.

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.

Usage

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

View Available Commands

dotfiles help

or simply:

dotfiles

Command Reference

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

• doctor — Read-only health check: Homebrew + Brewfile drift, dotfile symlinks, mise tools, git config + include.path, ~/.zshrc.local, yabai/skhd running, SSH key, essential commands on PATH (including shellcheck). Returns non-zero if anything is broken.
• 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/.
• 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, update both bin/dotfiles (COMMAND_SCRIPTS) and support/help.sh so help stays accurate.

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: SQLite, DBngin (MySQL, PostgreSQL, Redis)
• Other: Git, Composer, Laravel Valet, Mailpit, Meilisearch

Applications

• Development: Visual Studio Code, OrbStack (Docker), TablePlus. JetBrains Toolbox (PhpStorm) is per-machine in ~/.Brewfile.local.
• Productivity: 1Password, Raycast, Obsidian, Bartender. Notion, Linear, Slack, and ChatGPT are per-machine in ~/.Brewfile.local.
• System: Aldente, MonitorControl, Latest
• 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). 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: Add files to files/ and a corresponding entry to support/symlinks_map.sh.
5. 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.
6. 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

# 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
• Some steps require manual intervention (e.g., signing into apps)
• The manual_steps.sh script will remind 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.