The terminal's unwritten rules, written down

This week saw the release of The Secret Rules of the Terminal, a new zine by Julia Evans that digs into the messy, often undocumented conventions that govern how terminal software behaves. It's available for $12 as a PDF or print edition, with print orders shipping in August once the print run is sized to demand.

The zine targets a specific kind of unease: after two decades of daily terminal use, Evans found that while she had a workable intuition for how the terminal behaves, she couldn't always explain why. The terminal ships with a collection of small inconsistencies that most frequent users eventually learn to work around without ever fully understanding:

  • arrow keys sometimes move through your history and sometimes print ^[[D
  • mouse selection works in some programs but not others
  • command history is saved in some contexts and dropped in others
  • up-arrow recall works in some shells and is absent in others

One name, many pieces of software

The core problem is that "the terminal" isn't a single program. It's a stack of software—the terminal emulator, the TTY driver, the shell, core utilities like grep, and every third-party command-line program installed on top—each written by different people with different design assumptions. There's no single authority that defines, say, how text you type gets edited or how colours are restored after they break. The result is a set of de facto rules that are hard to piece together because they're implicitly distributed across the whole stack.

The zine breaks the terminal into its four major components (shell, terminal emulator, programs, and TTY driver), explains how they interoperate, and walks through the conventions worth relying on, along with practical tips for daily terminal usage. The focus is on the useful parts of terminal internals, not the full historical mess. As Evans puts it, a lot of modern terminal behaviour is that way because somebody made a decision in the 1980s and now it's permanent. But some internals are both comprehensible and genuinely practical:

  • understanding what your shell is responsible for makes configuration matter: history access, tab completion, and more live in its hands
  • recognizing escape codes demystifies what happens when cat-ing binary output corrupts your display—the fix can be a simple reset
  • knowing how colour is set lets you fix poor contrast in your terminal and actually read the text on screen

Old assumptions, corrected

Unlike the author's earlier zine How Git Works—where existing knowledge held up under scrutiny—writing this one surfaced a surprising number of the author's own misconceptions about terminal behaviour. Among the genuinely useful findings:

  • a better mental model of the terminal stack makes it possible to isolate which piece of software is responsible when something misbehaves, leading to, among other things, a small improvement contributed to fish
  • a shell script can be written to copy text to your clipboard over SSH
  • reset works by doing roughly the equivalent of stty sane; sleep 1; tput reset, making it unnecessary to remember the harder-to-type constituent commands
  • invisible escape codes can be inspected by running unbuffer program > out; less out
  • the annoying behaviour of built-in REPLs on macOS, such as sqlite3, traces back to their use of libedit instead of readline

The zine's production involved an extended collaboration: Marie Claire LeBlanc Flanagan co-worked on the project from September to June, Vladimir Kašiković designed the cover, Lesley Trites handled copy editing, and Simon Tatham (author of PuTTY) provided technical review. Operations manager Lee transcribed and coordinated, with Jesse Luehrs lending expertise on the terminal's more obscure internals.

Related explorations of terminal behaviour were published as a series of companion posts during development, covering topics from adding directories to PATH, to why pipes get stuck on buffering, to ASCII control characters and the state of ANSI escape code standards.

The Secret Rules of the Terminal is available directly from wizardzines.com, or bundled in the 15-zine all-access pack.