dotfiles

# dotfiles

The whole machine is described declaratively in a single file — [`mise.toml`](mise.toml), a symlink to [`home/.config/mise/config.toml`](home/.config/mise/config.toml). Everything that lands in `$HOME` lives under `home/` at the path it has there; the repo root holds only what belongs to the repo itself.
macOS only.
Requires mise 2026.11.4 or newer; CI uses 2026.11.4 explicitly.
It is applied by [`mise bootstrap`](https://mise.jdx.dev/bootstrap.html): system
packages, git repos, dotfile symlinks, login shell and tools.

## A new mac, from scratch

Five steps. You will be asked for a password twice — that is normal, it is
spelled out below where.

### 1. Xcode Command Line Tools

On a clean macOS `git` and `make` are stubs, so the very first command pops up
the GUI installer. Better to launch it up front and wait:

```sh
xcode-select --install
```

### 2. Get a GitHub token

`[tools]` is almost entirely on `latest`, so mise goes to `api.github.com` for
versions, where anonymous access gets 60 requests per hour — not enough for a
toolset this size. Normally the token comes from `gh`
(`github.credential_command` in `[settings]`), but on a fresh machine `gh` is not
authenticated yet, so for the first run the PAT has to be pulled out of 1Password
by hand (from a phone or the web). Without a token bootstrap does not fail, but it drowns in `429`s and
retries.

### 3. Clone over https

There are no ssh keys on a new machine yet, so not `git@`:

```sh
git clone https://github.com/mokevnin/dotfiles.git ~/dotfiles
cd ~/dotfiles
```

Later, once the keys are in place: `git remote set-url origin git@github.com:mokevnin/dotfiles.git`.

### 4. Run it

```sh
export GITHUB_TOKEN=…   # from step 2
make install
```

`make install` = install Homebrew, install mise with it, and run `mise bootstrap
--yes`. Nothing has to be on the machine beforehand. Run it **from
`~/dotfiles`** — why, is explained below in "What lives where". The `--yes` flag
is also what keeps mise from asking whether you trust the config.

What happens, in order:

| | |
|---|---|
| `brew` target | installs Homebrew if it is missing — **asks for a password** |
| `mise` target | `brew install mise` |
| `pre-packages` hook | the same Homebrew installer, for the case where bootstrap is run without the Makefile. Here brew already exists, so it does nothing |
| `[bootstrap.packages]` | brew formulae and casks, GUI apps included. `pkg` casks (`docker-desktop`, `zoom`, `nordvpn`, `session-manager-plugin`) go through `installer(8)` and **ask for a password** |
| `[bootstrap.directories]` | creates `~/Downloads/Screenshots`, the folder the screenshot preference below points at. macOS does not create it, and a screenshot taken into a missing folder goes nowhere |
| `[bootstrap.repos]` | clones oh-my-zsh — only its plugin files are used |
| `[dotfiles]` | symlinks `~/.config/nvim`, `~/.config/mise/config.toml`, `~/.gitconfig`, `~/.config/starship.toml`, `~/.config/zsh/rc.zsh`, and writes the one li