Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Lint

on:
push:
pull_request:

permissions:
contents: read

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7

- name: Install zsh
run: sudo apt-get update && sudo apt-get install -y zsh

- name: ShellCheck
run: shellcheck bin/bootstrap bin/link bin/macos bin/update macos/defaults.sh

- name: zsh syntax
run: for f in zsh/zshrc zsh/zprofile zsh/*.zsh; do zsh -n "$f"; done

- name: Python syntax
run: python3 -m py_compile bin/optional/fetch-gitlab-mr-review-comments
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
*.swo
*~
Brewfile.local
__pycache__/
39 changes: 26 additions & 13 deletions Brewfile
Original file line number Diff line number Diff line change
@@ -1,20 +1,33 @@
tap "oven-sh/bun"

# Git
brew "git"
brew "git-lfs"
brew "git-delta"
brew "gh"
brew "gnupg"
brew "diff-so-fancy"
brew "neovim"
brew "glab"
brew "lazygit"

# Shell
brew "starship"
brew "zsh-autosuggestions"
brew "zsh-syntax-highlighting"
brew "zsh-completions"
brew "fzf"
brew "zoxide"
brew "eza"
brew "bat"
brew "fd"
brew "ripgrep"
brew "jq"
brew "lazygit"
brew "node"
brew "pnpm"
brew "oven-sh/bun/bun"
brew "pyenv"
brew "rbenv"
brew "pipx"
brew "go"

# Development (language runtimes are managed by mise, see mise/config.toml;
# mise itself comes from https://mise.run, installed by bin/bootstrap)
brew "uv"
brew "neovim"
brew "shellcheck"

# Media and web
brew "ffmpeg"
brew "svgo"
brew "mkcert"

cask "ghostty"
153 changes: 101 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@ My personal and opinionated macOS dotfiles, adapted from the general structure a

## What's managed

- `zsh` configuration with `oh-my-zsh`, `powerlevel10k`, `nvm`, `pyenv`, `rbenv`, `pnpm`, `pipx`, and GitHub Copilot shell aliases
- Git config and global gitignore
- Homebrew package bootstrap via `Brewfile`
- `zsh` configuration without a framework: Homebrew plugins (autosuggestions, syntax highlighting, completions), a [Starship](https://starship.rs) prompt, [fzf](https://github.com/junegunn/fzf), [zoxide](https://github.com/ajeetdsouza/zoxide), and `eza`/`bat`/`fd` aliases
- Language runtimes with [mise](https://mise.jdx.dev) (Node, pnpm, Bun, Python, Go, Yarn, Poetry), including automatic switching from `.nvmrc`, `.node-version`, `.python-version` and `.ruby-version`
- Git config with current defaults, [delta](https://github.com/dandavison/delta) for diffs, and SSH commit signing
- [Ghostty](https://ghostty.org) terminal config
- Homebrew packages via `Brewfile`
- Safe macOS defaults

## What's not managed
Expand All @@ -21,19 +23,24 @@ My personal and opinionated macOS dotfiles, adapted from the general structure a
```text
dotfiles/
├── Brewfile
├── bin/
│ └── optional/
├── git/
├── local/
├── bin/ bootstrap, link, update, macos
│ └── optional/ opt-in helper scripts
├── ghostty/ → ~/.config/ghostty/config.ghostty
├── git/ → ~/.config/git/config, ~/.config/git/ignore
├── local/ templates for untracked machine-local files
├── macos/
└── zsh/
├── mise/ → ~/.config/mise/config.toml
├── starship/ → ~/.config/starship.toml
└── zsh/ → ~/.zshrc, ~/.zprofile
```

## Commands

The scripts are not on `PATH`; call them by path.

### Bootstrap a machine

Runs Homebrew setup, installs the tracked packages, creates missing local override files, links managed dotfiles, and optionally applies macOS defaults.
Installs Homebrew and the tracked packages, links managed dotfiles, creates missing local files, installs mise from [mise.run](https://mise.run) along with its runtimes, and optionally applies macOS defaults.

```bash
~/dotfiles/bin/bootstrap
Expand All @@ -42,7 +49,7 @@ Runs Homebrew setup, installs the tracked packages, creates missing local overri

### Relink managed dotfiles

Safely backs up conflicting existing files in `~/.dotfiles-backups/<timestamp>/`.
Safely backs up conflicting existing files in `~/.dotfiles-backups/<timestamp>/`, keeping their path relative to `~`. Running it again changes nothing.

```bash
~/dotfiles/bin/link
Expand All @@ -54,14 +61,91 @@ Safely backs up conflicting existing files in `~/.dotfiles-backups/<timestamp>/`
~/dotfiles/bin/macos
```

### Update the repo and re-apply config
### Update everything

If the repository has an `origin` remote, this pulls with `--ff-only` before refreshing packages and links.
Pulls the repo (`--ff-only`), upgrades Homebrew packages, mise itself (`mise self-update`) and its runtimes, upgrades `gh` extensions, relinks, and lists installed packages that no Brewfile mentions.

```bash
~/dotfiles/bin/update
```

## Managed home files

| Home file | Repo file |
| --- | --- |
| `~/.zshrc` | `zsh/zshrc` |
| `~/.zprofile` | `zsh/zprofile` |
| `~/.config/git/config` | `git/gitconfig` |
| `~/.config/git/ignore` | `git/gitignore` |
| `~/.config/mise/config.toml` | `mise/config.toml` |
| `~/.config/starship.toml` | `starship/starship.toml` |
| `~/.config/ghostty/config.ghostty` | `ghostty/config.ghostty` |

## Local overrides

These files are intentionally outside the repo and are safe for machine-specific or private values:

- `~/.gitconfig`: identity, signing key, and anything `git config --global` writes. Git reads it after `~/.config/git/config`, so its values win.
- `~/.zshrc.local`: sourced at the end of `~/.zshrc`
- `~/.config/git/allowed_signers`: lets git verify your own SSH signatures
- `~/dotfiles/Brewfile.local`: extra packages for this machine (git-ignored)

Bootstrap creates the first two from `local/gitconfig.example` and `local/zshrc.local.example` when missing, and generates `allowed_signers` from `user.email` and `~/.ssh/id_ed25519.pub`.

## Commit signing

Commits and tags are signed with SSH (`gpg.format = ssh`). On a new machine:

1. Set `user.name`, `user.email` and `user.signingkey = ~/.ssh/id_ed25519.pub` in `~/.gitconfig`.
2. Run `~/dotfiles/bin/bootstrap` (or create `~/.config/git/allowed_signers` yourself).
3. Add the public key as a **signing** key on GitHub (`gh ssh-key add ~/.ssh/id_ed25519.pub --type signing`) and on GitLab (key usage "Authentication & Signing").

## Shell shortcuts

### Keys

| Keys | What it does |
| --- | --- |
| `Ctrl-R` | Fuzzy-search your command history (fzf) |
| `Ctrl-T` | Fuzzy-find a file below the current directory and insert its path, with a `bat` preview |
| `Alt-C` | Fuzzy-find a directory below the current one and `cd` into it |
| `**` then `Tab` | Fuzzy completion: `vim **<Tab>` for files, `cd src/**<Tab>` for directories, `kill **<Tab>` for processes, `ssh **<Tab>` for hosts |
| `Tab` | Completion menu with case-insensitive matching; move through it with the arrow keys |
| `↑` / `↓` | Step through earlier commands that start with what you have typed |
| `→` or `End` | Accept the grey autosuggestion; `Option-→` accepts one word of it |
| `Option-←` / `Option-→` | Move one word left or right (`Ctrl-←` / `Ctrl-→` work too) |
| `Ctrl-X Ctrl-E` | Edit the current command in Neovim |

`Alt` is the left `Option` key in Ghostty (`macos-option-as-alt = left`). In iTerm, set the left Option key to "Esc+" under Profiles → Keys.

### Commands

| Command | What it does |
| --- | --- |
| `z <part of a path>` | Jump to the most-used directory that matches (zoxide) |
| `zi <part of a path>` | Pick from the matching directories with fzf |
| `<directory>` | Typing a directory name on its own `cd`s into it |
| `cd -<Tab>` | Pick from recently visited directories |
| `ls`, `ll`, `la`, `lt` | eza: list, long list with git status, long list including hidden files, tree two levels deep |
| `cat <file>` | `bat` with syntax highlighting. Use `\cat` for the original: `bat` rejects flags such as `cat -v` |
| `man <command>` | Man pages are colored by `bat` |
| `vim` | Neovim |
| `dotfiles` | `cd` into this repo |
| `git diff`, `git show`, `git add -p` | Output goes through delta; `n` and `N` jump between files |

## Runtimes with mise

Global versions live in `mise/config.toml`. In a project, mise reads `mise.toml` or the version files of other managers (`.nvmrc` and friends) and switches versions when you `cd` into it, so there is no `nvm use` step.

```bash
mise install # install everything the current directory needs
mise use node@22 # pin a version for the current project (writes mise.toml)
mise ls # show installed and active versions
mise doctor # check the setup
```

Interactive shells use `mise activate`. Login shells started by GUI apps and editors get the mise shims through `~/.zprofile`.

## Optional scripts

Scripts in `bin/optional/` are **not** on `PATH` by default. To opt in, add this to `~/.zshrc.local`:
Expand Down Expand Up @@ -92,47 +176,12 @@ fetch-gitlab-mr-review-comments https://gitlab.example.com/group/project/-/merge

Requires `glab` on `PATH` with access to the GitLab project.

## Managed home files

- `~/.zshrc` -> `~/dotfiles/zsh/zshrc`
- `~/.gitconfig` -> `~/dotfiles/git/gitconfig`
- `~/.gitignore` -> `~/dotfiles/git/gitignore`

## Local overrides

These files are intentionally outside the repo and are safe for machine-specific or private values:

- `~/.gitconfig.local`
- `~/.zshrc.local`
## Brewfile scope

Bootstrap creates them from these templates when missing:
The tracked `Brewfile` contains the core daily tools, grouped by purpose: Git (`git`, `git-lfs`, `git-delta`, `gh`, `glab`, `lazygit`), shell (`starship`, zsh plugins, `fzf`, `zoxide`, `eza`, `bat`, `fd`, `ripgrep`, `jq`), development (`uv`, `neovim`, `shellcheck`), media and web (`ffmpeg`, `svgo`, `mkcert`), and the Ghostty cask. Language runtimes come from mise, not Homebrew. mise itself is installed from [mise.run](https://mise.run) into `~/.local/bin`, because the official binary is smaller and faster than Homebrew's build and can update itself.

- `~/dotfiles/local/gitconfig.local.example`
- `~/dotfiles/local/zshrc.local.example`
Put extra machine-local packages in the untracked `Brewfile.local`; `bin/bootstrap` and `bin/update` load it when it exists.

## Brewfile scope
## CI

The tracked `Brewfile` contains the core daily tools for my machine:

- `git`
- `gh`
- `gnupg`
- `diff-so-fancy`
- `neovim`
- `ripgrep`
- `jq`
- `lazygit`
- `node`
- `pnpm`
- `bun`
- `pyenv`
- `rbenv`
- `pipx`
- `go`
- `ffmpeg`
- `svgo`
- `mkcert`

If you want extra machine-local packages later, add them to a non-tracked `Brewfile.local` and keep the tracked file curated.

`bin/bootstrap` and `bin/update` also load `~/dotfiles/Brewfile.local` when it exists.
`.github/workflows/lint.yml` runs ShellCheck on the scripts and syntax-checks the zsh and Python files on every push.
50 changes: 48 additions & 2 deletions bin/bootstrap
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
set -euo pipefail

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
RUN_MACOS=0

for arg in "$@"; do
Expand All @@ -25,6 +26,15 @@ ensure_homebrew() {

echo "Installing Homebrew..."
NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# A fresh install is not on PATH yet in this process.
local brew_bin
for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew; do
if [[ -x "$brew_bin" ]]; then
eval "$("$brew_bin" shellenv)"
return 0
fi
done
}

copy_if_missing() {
Expand All @@ -40,6 +50,16 @@ copy_if_missing() {
echo "Created: $target"
}

# The official binary is smaller and faster than Homebrew's build and can update itself.
ensure_mise() {
if [[ -x "$HOME/.local/bin/mise" ]]; then
return 0
fi

echo "Installing mise..."
curl -fsSL https://mise.run | MISE_INSTALL_HELP=0 sh
}

install_brewfile_if_present() {
local brewfile="$1"

Expand All @@ -48,17 +68,43 @@ install_brewfile_if_present() {
fi
}

# Git verifies SSH commit signatures against this file. It holds your email, so it stays untracked.
ensure_allowed_signers() {
local signers="$CONFIG_HOME/git/allowed_signers"
local key="$HOME/.ssh/id_ed25519.pub"
local email

if [[ -e "$signers" ]]; then
echo "Unchanged: $signers"
return 0
fi

email="$(git config --global user.email || true)"
if [[ ! -f "$key" || -z "$email" || "$email" == "you@example.com" ]]; then
echo "Skipped: $signers (set user.email in ~/.gitconfig and create $key first)"
return 0
fi

printf '%s namespaces="git" %s\n' "$email" "$(cut -d' ' -f1,2 "$key")" > "$signers"
echo "Created: $signers"
}

ensure_homebrew

if command -v brew >/dev/null 2>&1; then
install_brewfile_if_present "$ROOT/Brewfile"
install_brewfile_if_present "$ROOT/Brewfile.local"
fi

copy_if_missing "$ROOT/local/gitconfig.local.example" "$HOME/.gitconfig.local"
# Linking runs first because it migrates an old ~/.gitconfig symlink out of the way.
"$ROOT/bin/link"

copy_if_missing "$ROOT/local/gitconfig.example" "$HOME/.gitconfig"
copy_if_missing "$ROOT/local/zshrc.local.example" "$HOME/.zshrc.local"
ensure_allowed_signers

"$ROOT/bin/link"
ensure_mise
"$HOME/.local/bin/mise" install

if [[ $RUN_MACOS -eq 1 ]]; then
"$ROOT/bin/macos"
Expand Down
Loading
Loading