Guide 6 of 7 · Toolbox
The toolbox
The other guides explain how it works. This one is the cheat sheet: what you get, and which keys to press.
The shopping list
The Brewfile is a plain list of everything Homebrew should install. Add a line, run brew bundle --global, and the tool is on this Mac. Commit the line, and it is on the next Mac too.
-
brew
Command-line tools
zsh, git, Neovim, tmux, fzf, ripgrep, fd, Starship, mise, direnv, the GitHub CLI,
jqandyq, and the tools the tests need. -
cask
Apps
1Password, Ghostty, Alfred, Rectangle, Karabiner-Elements, OrbStack, Visual Studio Code and the rest of the everyday apps.
-
cask
Fonts
Three Nerd Fonts, which add the small icons the prompt and the editor's status line use.
| Command | What it does |
|---|---|
brewup | The whole maintenance run in one word: update, upgrade, clean up, health check. |
make brew-drift | Compares this Mac with the Brewfile and lists what each has that the other lacks. |
make audit | Asks Homebrew and GitHub whether anything on the list has been renamed, deprecated or abandoned. |
Two terminal apps, one look
Either Apple's Terminal.app or Ghostty can be the window. They are set up to match, and both step into tmux when a window opens.
-
Terminal.app
A Gotham profile
script/macosinstalls the Gotham color profile and makes it the default for new windows. -
Ghostty
The same sixteen colors
config/ghostty/configspells out the Gotham palette and the same Nerd Font. The colors sit in the same numbered slots, because the tmux status bar picks its colors by slot number. -
Ghostty
Two switches turned off
Its shell integration is off, because it works by borrowing
ZDOTDIR, which this setup depends on. And closing a window does not ask first, because tmux keeps the session alive.
The prompt
The prompt is drawn by Starship. It stays quiet until there is something to say.
dotfiles on main *
➜
The arrow is green after a command that worked and red after one that failed. Inside a git repository the prompt adds the branch, a * when files have changed, and arrows when you are ahead of or behind the remote. A helper also speaks up when you type a long command that already has a shortcut.
Git
Nine shell shortcuts cover the commands typed most often. They are defined in config/zsh/lib/git.zsh, and adding one is a single line there.
| Type | Runs | Type | Runs |
|---|---|---|---|
g | git | gfr | git pull --rebase |
gia | git add | gp | git push |
gco | git checkout | gpf | git push --force-with-lease |
gbc | git checkout -b | gr | git rebase |
gfc | git clone |
Git itself has a few more, from config/git/config:
| Command | What it does |
|---|---|
git st | Status. |
git undo | Takes back the last commit but keeps its changes. |
git lg | The history as a colored graph of every branch. |
git l | The history as one line per commit, date first. |
git cleanup | Deletes merged local branches whose remote branch is gone. |
gh co | Checks out a pull request by number. |
How git behaves here
- Every commit is signed. See Keys and 1Password.
- Pulls and merges only fast-forward, so history never gains a surprise merge commit.
- Rebasing with unsaved changes stashes them and puts them back afterwards.
- Fetching removes branches that were deleted on the remote.
- New repositories start on
main, and diffs are shown throughdiff-so-fancy. - A new commit message opens with a template that reminds you to say why.
tmux
tmux splits one terminal window into panes and tabs, and keeps them running when the window closes. Every tmux key starts with the prefix, which is Ctrl A here. Press it, let go, then press the next key.
| After the prefix | What happens |
|---|---|
| | - | Split the pane side by side, or one above the other. The new pane opens in the same folder. |
| h j k l | Move to the pane on the left, below, above or right. |
| H J K L | Resize the pane in that direction. Hold to repeat. |
| c | A new tab, in the same folder. |
| R | Reload the tmux settings. |
- The mouse works. Click a pane to select it, drag a border to resize, drag over text to copy it to the Mac clipboard.
- Tabs name themselves after the folder they are in, so three tabs read “dotfiles”, “api”, “notes” and not “zsh”, “zsh”, “zsh”.
- Sessions survive a restart. Two plugins save the layout regularly and restore it when tmux starts again.
- The status bar shows the mode. It lights up when the prefix is pressed, in copy mode, and in red when typing goes to every pane at once.
Finding things
fzf is a fuzzy finder: type a few letters from anywhere in a name and it narrows the list as you go.
| Keys | What it finds |
|---|---|
| Ctrl T | A file under the current folder, including hidden files and ones git ignores. |
| Ctrl R | A command from your history. |
| Alt C | A folder to jump into. |
| ↑ ↓ | Type part of a command first, and the arrows step through the history entries that contain it. |
| Tab | Completion with a menu. It ignores capitals and forgives a typo. |
The editor
Neovim is set up as a quick editor for commit messages and config files, not as a second IDE. It has five plugins, pinned to exact versions by a lockfile. vim and vi both open it. The leader key is Space.
| Keys | What happens |
|---|---|
| Space Space | Find a file. |
| Space h | Recently opened files. |
| Space b | Open buffers. |
| Space / | Search the whole project. |
| Space d | Problems in this file. |
| Esc | Clear the search highlight. |
ys ds cs | Add, delete or change the quotes or brackets around something. |
ga | Line things up in columns. |
Commit messages get special treatment: a ruler at 72 characters, spell checking, and the cursor on the subject line.
Languages and projects
-
mise
The right version per project
Reads a project's
mise.toml,.nvmrc,.node-versionor.python-versionand switches Node or Python to match. It never downloads anything without being asked. -
direnv
Variables per folder
Loads the environment variables in a folder's
.envrcwhen you enter it, and removes them when you leave. -
OrbStack
Containers
Provides
docker. Its Tab completions are generated from whichever version is installed.
Small conveniences
| Command | What it does |
|---|---|
path | Prints PATH one folder per line, in color. |
kp | Pick running programs from a fuzzy list and stop them. |
curlt | Fetches a URL and shows where the time went. |
checkip | Prints this Mac's public IP address. |
randommac | Gives the Wi-Fi card a random hardware address. |
rm_node_modules | Deletes every node_modules folder below the current one. |
One job needs no helper: ssh-keygen -R <host> makes SSH forget a server's old fingerprint after the server has been rebuilt.
Outside the terminal
- Caps Lock is useful. Karabiner makes it Escape when tapped and Control when held with another key.
- macOS is set up the same everywhere.
script/macosapplies one table of settings: dark mode, the Dock on the right and hidden, Finder in list view with the path bar, no.DS_Storefiles on network or USB drives, silent alerts and no startup chime. - You can check without changing.
script/macos --checklists any setting that has drifted and writes nothing.
Switches
| Variable | Effect when set |
|---|---|
ZSH_NO_TMUX_AUTOSTART | This shell does not step into tmux. |
ZSH_NO_ZCOMPILE | Skips the background compile of the completion index. |
DOTFILES_URL, DOTFILES_REF | Where script/bootstrap installs from. |