Guide 4 of 7 · Opening a terminal
What happens when you open a terminal
Between the window appearing and the prompt blinking, zsh reads four files in a fixed order. It takes about 145 milliseconds. Here is every step.
Four files, always in this order
zsh decides which files to read by asking two questions. Is this a login shell, the first one of a session? Is it interactive, with a person typing? A new Terminal window is both, so it reads all four.
In plain words
Think of opening a shop in the morning. Someone unlocks the door and switches on the lights (.zshenv). Someone sets out the stock (.zprofile). Someone arranges the counter the way the shopkeeper likes it (.zshrc). Then the cleaner tidies up out the back while the first customer is already being served (.zlogin).
~/.zshenv every zsh, even scripts
- Skip the system-wide filesmacOS has its own startup files in
/etc. One switch,noglobalrcs, tells zsh to skip them, so startup is the same on every Mac and nothing runs twice. - Name the three drawersSets where settings, caches and data live:
~/.config,~/.cacheand~/.local/share. Every later step uses these names. - Point zsh at the repositorySets
ZDOTDIRto~/.config/zsh. This is the pivot the whole design turns on: from now on zsh looks for its other startup files in the repository, and the ones in the home folder are left for somebody else to own. - Give PATH its basicsAdds the system folders, because skipping the
/etcfiles means nothing else will, and tells zsh to drop duplicate entries. That lives here because this is the only file every shell reads, tmux panes included. A shell started by an app rather than by you also loads the profile here, so it gets the same environment.
.zprofile login shells
- Load the base layer's profileIf a
~/.zprofileexists in the home folder, read it first. On a managed Mac that file belongs to another tool. Loading it first means anything set afterwards wins. - Set the languageMakes sure text is treated as UTF-8, so accents and symbols display properly, and passes that on to every program the shell starts.
- Add only what is missingAdds
/usr/local/binto PATH if it is not there already. It never reorders a PATH that a base layer arranged on purpose. - Find HomebrewPuts
/opt/homebrew/binon PATH, unless a base layer already has. It happens this early because the very next file looks for tmux, and tmux comes from Homebrew. - Pick up what installers addedSome apps announce their command-line tools by listing a folder in
/etc/paths.d. Skipping the/etcfiles skips the step that reads that list, so it is read here. Each folder goes at the end of PATH, and only if it exists.
.zshrc interactive shells
- Jump into tmuxIf this is a fresh Terminal.app or Ghostty window, hand over to tmux straight away, before any expensive work. The shell inside tmux then runs this same list. More on this below.
- Load the base layer's rc fileIf a
~/.zshrcexists in the home folder, read it now. Same idea as the profile: theirs first, ours on top. - Start the plugin managerLoads zinit, which fetches and loads shell plugins, each at the exact commit listed in
pins.zsh. On a brand-new Mac it downloads itself first. When a listed commit has changed since the last shell, what is installed is moved to it here, once. - Register the handy functionsEvery file in
autoload/becomes a command, such askporpath. zsh only reads the file the first time you run it. - Read lib/, one topic per fileFourteen small files in alphabetical order: aliases, completion, history, the prompt and so on. The cast list is below.
- Switch on tab completionBuilds the index of what Tab can complete. The index is saved and only rebuilt when it is more than twenty hours old, which is the difference between a few milliseconds and a few hundred.
- Turn on syntax highlightingColors commands as you type them. It goes last because the highlighter asks to be the final thing loaded.
- Read ~/.zshrc.localAn optional file for this Mac only. Read at the end, so it has the final word.
- Tell the rest of macOS about PATHHands the finished PATH to macOS itself, so apps opened from the Dock can find the same tools the terminal can. Only a shell that a terminal window or a tmux pane started does this. A shell opened from inside something else, such as a Python virtualenv, keeps its PATH to itself.
.zlogin after everything else
- Tidy up in the backgroundCompiles the completion index into a faster form. It runs detached from the shell, so it costs the shell nothing.
- Draw the prompt, then load the restThe prompt appears. A moment later the plugins that were told to wait arrive quietly: suggestions as you type, history search and alias reminders.
.zshenv and .zshrc only.
Sitting on top of another setup
On some Macs a separate tool installs its own ~/.zprofile and ~/.zshrc, and rewrites them now and then. Editing those files would be pointless, because the edits would be wiped. Replacing them would break whatever that tool set up.
So this repository does neither. Its own startup files live in config/zsh, and each one begins by loading the file of the same name from the home folder, if there is one.
- zsh itselfThe shell macOS or Homebrew provides.
- The base layer · ~/.zprofile, ~/.zshrcSomebody else's setup. Loaded first, never edited. On a personal Mac it simply is not there.
- This repository · config/zshLoaded second, so where the two disagree, this one wins.
- This Mac only · ~/.zshrc.localLoaded last. The final word.
↑ later layers win
It asks what is there, never where it is
Nothing in the shell config asks “is this a work Mac?”. It asks questions it can check: does this command exist, is this function already defined. The same files then do the right thing everywhere.
| If the shell finds… | …then this repository |
|---|---|
Node already wrapped by a base layer (nvm, node or npm are functions) | Hands Node over completely and changes nothing about it. |
| Suggestions-as-you-type already running | Does not load a second copy. |
| Another prompt installed (pure) | Switches it off cleanly before starting its own. |
| Another syntax highlighter loaded | Stands it down, so two highlighters never fight over the line. |
| Homebrew already set up | Keeps the order the base layer chose. |
A tool that is not installed (mise, fzf, starship, direnv, docker) | Skips it silently. A missing tool is never an error. |
The cast list in lib/
The .zshrc file itself is short. The real settings are in config/zsh/lib, one file per topic, so it is obvious where a new setting belongs.
| File | What it is in charge of |
|---|---|
1password.zsh | Points SSH at the 1Password agent. See Keys and 1Password. |
alias.zsh | Short names such as vim for Neovim, and a reminder when you type out something that has an alias. |
common.zsh | The core plugins, a handful of Prezto modules, and the default editor and pager. |
completion.zsh | How the Tab menu looks and matches: ignores capitals, forgives typos, groups results. |
direnv.zsh | Per-folder environment variables. |
fzf.zsh | The fuzzy finder and its keys. |
git.zsh | Nine git shortcuts. They are listed in the Toolbox. |
history.zsh | A large history shared between all open shells, without duplicates or throwaway commands like a bare ls. |
homebrew.zsh | Homebrew shortcuts, including brewup for the whole maintenance run. |
mise.zsh | Language runtimes, chosen per project. |
node.zsh | Where npm keeps its cache, unless a base layer owns Node. |
orbstack.zsh | Tab completion for docker and orb. |
prompt.zsh | The Starship prompt. |
tmux.zsh | tmux shortcuts, and where its config file is. |
The tmux front door
The very first thing .zshrc does is decide whether to step inside tmux. It only says yes when every one of these is true. An editor's built-in terminal, an SSH session or a script fails one of them and gets a plain shell.
- A person is typing
- Not already inside tmux
- The window is Terminal.app or Ghostty
- No opt-out is set
- tmux is installed
ZSH_NO_TMUX_AUTOSTART to skip tmux for one shell.
Why it is fast
A shell that takes two seconds to start is two seconds you wait hundreds of times a day. Startup time is treated as a feature here, with a number attached.
Three habits get it there, and a fourth keeps it there.
-
Habit 1
Wait until after the prompt
Suggestions, history search and alias reminders are not needed to draw a prompt. They are loaded a moment after it appears. The alias reminder alone cost 47 ms when it loaded up front.
-
Habit 2
Remember the answer
Tools like Starship, fzf, mise and direnv set themselves up by printing shell code. Asking each one on every start is slow, so
cached_initsaves the answer and only asks again after the tool is upgraded. -
Habit 3
Let Tab fetch it later
Completions for
dockerandorbare saved as files that zsh only opens the first time you press Tab on that command. -
Habit 4
Measure it, every time
A test times real shell startups with
hyperfineand fails if the fastest one is over 200 ms. A slow change cannot slip in unnoticed.
┆ The dashed line is the moment the prompt appears. Only the top row has to finish before it.