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

  1. 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.
  2. Name the three drawersSets where settings, caches and data live: ~/.config, ~/.cache and ~/.local/share. Every later step uses these names.
  3. Point zsh at the repositorySets ZDOTDIR to ~/.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.
  4. Give PATH its basicsAdds the system folders, because skipping the /etc files 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

  1. Load the base layer's profileIf a ~/.zprofile exists 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.
  2. 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.
  3. Add only what is missingAdds /usr/local/bin to PATH if it is not there already. It never reorders a PATH that a base layer arranged on purpose.
  4. Find HomebrewPuts /opt/homebrew/bin on PATH, unless a base layer already has. It happens this early because the very next file looks for tmux, and tmux comes from Homebrew.
  5. Pick up what installers addedSome apps announce their command-line tools by listing a folder in /etc/paths.d. Skipping the /etc files 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

  1. 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.
  2. Load the base layer's rc fileIf a ~/.zshrc exists in the home folder, read it now. Same idea as the profile: theirs first, ours on top.
  3. 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.
  4. Register the handy functionsEvery file in autoload/ becomes a command, such as kp or path. zsh only reads the file the first time you run it.
  5. Read lib/, one topic per fileFourteen small files in alphabetical order: aliases, completion, history, the prompt and so on. The cast list is below.
  6. 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.
  7. Turn on syntax highlightingColors commands as you type them. It goes last because the highlighter asks to be the final thing loaded.
  8. Read ~/.zshrc.localAn optional file for this Mac only. Read at the end, so it has the final word.
  9. 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

  1. Tidy up in the backgroundCompiles the completion index into a faster form. It runs detached from the shell, so it costs the shell nothing.
  2. 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.
Press Play, or select any step. Inside tmux the shell is not a login shell, so it reads .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.

  1. zsh itselfThe shell macOS or Homebrew provides.
  2. The base layer · ~/.zprofile, ~/.zshrcSomebody else's setup. Loaded first, never edited. On a personal Mac it simply is not there.
  3. This repository · config/zshLoaded second, so where the two disagree, this one wins.
  4. This Mac only · ~/.zshrc.localLoaded last. The final word.

↑ later layers win

Each layer is loaded after the one beneath it, and later settings replace earlier ones.

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 runningDoes not load a second copy.
Another prompt installed (pure)Switches it off cleanly before starting its own.
Another syntax highlighter loadedStands it down, so two highlighters never fight over the line.
Homebrew already set upKeeps 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.

FileWhat it is in charge of
1password.zshPoints SSH at the 1Password agent. See Keys and 1Password.
alias.zshShort names such as vim for Neovim, and a reminder when you type out something that has an alias.
common.zshThe core plugins, a handful of Prezto modules, and the default editor and pager.
completion.zshHow the Tab menu looks and matches: ignores capitals, forgives typos, groups results.
direnv.zshPer-folder environment variables.
fzf.zshThe fuzzy finder and its keys.
git.zshNine git shortcuts. They are listed in the Toolbox.
history.zshA large history shared between all open shells, without duplicates or throwaway commands like a bare ls.
homebrew.zshHomebrew shortcuts, including brewup for the whole maintenance run.
mise.zshLanguage runtimes, chosen per project.
node.zshWhere npm keeps its cache, unless a base layer owns Node.
orbstack.zshTab completion for docker and orb.
prompt.zshThe Starship prompt.
tmux.zshtmux 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
No session yetStart one, named after your username.
A session nobody is looking atAttach to it, and carry on where you left off.
A session open in another windowLeave it alone. This window gets a plain shell, so a session is never stolen.
Set 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.

  • 2022, the old plugin manager2,230 ms
  • 2022, everything loaded up front730 ms
  • The test's limit200 ms
  • Today146 ms
Time to start an interactive login shell. The 2022 figures are from the README's historical log on an older Mac, so compare the shape, not the decimals.

Three habits get it there, and a fourth keeps it there.

Needed now
the four startup files
Can wait
deferred plugins
Background
background chores

┆ The dashed line is the moment the prompt appears. Only the top row has to finish before it.

A sketch of where the work goes, not a measurement.