Dotfiles

Personal macOS dotfiles managed with modular install scripts.

Quick Start

# Clone for your machine
git clone -b personal git@github.com:marcosmoura/dotfiles.git ./dotfiles

# Run full installation
cd ./dotfiles
./install.sh --all

Architecture

dotfiles/
├── install.sh              # Entry point (--all, --core, --module)
├── packages/               # Declarative package lists
│   ├── Brewfile            # Declarative Homebrew packages (brew bundle)
│   ├── node-globals.txt
│   ├── cspell-dictionaries.txt
│   ├── cargo-binaries.txt
│   ├── pip-packages.txt
│   ├── gems.txt
│   └── luarocks.txt
├── installation/
│   ├── core/               # Always runs (in order)
│   │   ├── preinstall.sh   # Sudo auth, Xcode CLI tools
│   │   ├── symlinks.sh     # Symlinks + stale link cleanup
│   │   ├── macos.sh        # macOS system defaults
│   │   └── postinstall.sh  # Cleanup + summary
│   ├── modules/            # Opt-in, runnable individually
│   │   ├── brew.sh         # Homebrew + brew bundle
│   │   ├── zsh.sh          # Shell setup + sheldon plugins
│   │   ├── node.sh         # Node.js, Bun, pnpm, globals
│   │   ├── lua.sh          # Luarocks packages
│   │   ├── python.sh       # Python, uv, pip packages
│   │   ├── ruby.sh         # Ruby, gems
│   │   └── rust.sh         # Rust toolchain, cargo binaries
│   └── lib/
│       └── utils.sh        # Shared utilities (logging, retry, etc.)
├── home/                   # Symlinked to ~/
│   ├── .zprofile           # Login shell: PATH, env vars
│   ├── .zshrc              # Interactive shell: plugins, prompt
│   └── .config/            # XDG configs (git, nvim, zsh, etc.)
└── static/                 # Assets (keyboard layouts)

Usage

# Full installation (core + all modules)
./install.sh --all

# Core only (symlinks, macOS settings)
./install.sh --core

# Specific modules
./install.sh --module node rust

Note: the installer replaces an existing ~/.config directory with the repo symlink.

Branch Strategy

This repository uses separate branches per machine:

• personal — Full personal development setup
• work — Work machine (limited scope)

Each machine clones its own branch directly:

git clone -b <branch> git@github.com:marcosmoura/dotfiles.git ~/Projects/dotfiles

Note: Git worktrees (.worktrees/) are for development only — not for deployment. To develop across branches simultaneously, use worktrees locally.

Secrets

Secrets are stored outside the repository in ~/.secrets/. The install script creates this directory. Populate it manually after installation.

Git Identity

On first install, install.sh prompts for your Git name and email, creating ~/.config/git/identity (not tracked by git). On subsequent installs, the existing identity is preserved.