Julia Evans

@b0rk.jvns.ca

74249 Followers 330 Following

programming and exclamation marks blog: jvns.ca zines: wizardzines.com

the "combining diverged branches" from How Git Works, in Korean

This was the best and easiest way to understand why pressing up/down, or delete key, shit out weird characters to my terminal emulator. I was facing this issue intermittently and it broke me.

The documentation talking about resolving these issues on the systems I work on a daily basis (rhel 7 and older) with no sudo access; using old arcane stuff from the Roman empire era was sparse.

I could not for the life of me figure out what the root cause of this issue was.

I did read about the fundamental concept of these years ago on either Debian or Arch wiki page, but approaching the same thing again after multiple years "out-of-the-terminal" felt daunting.

Julia has a knack for making things accessible and I was excited to buy this as soon as it dropped.

Happy with the purchase! The physical copy is totally worth it for me (and I am grateful to get a PDF as a backup option)

Looking forward to more stuff from her!

a cartoon with a map of Canada, where the the order is being shipped from Montreal to Saskatchewan

How DNS Works!, by Julia Evans - A cartoon of a person in a cool puffy outfit navigating a futuristic city street. A passer-by has a speech bubble with an IP address in it, and a floating robot is projecting “Wanted: Example cat.com”, with a picture of a cat wearing sunglasses.

A screenshot of the "zine library" view, with the link to add a new account highlighted below the list of zines

Image of a person sitting next to a bookshelf with their zines

Welcome! Enter your email address and we'll send you a link to download all of the zines that you've ordered in the past.

woman with shell necklace and a redirects belt accessory

zine sale! coming november 28, 50% off PDF zines, 30% off print zines A cartoon of a person in a spacesuit, accompanied by a penguin (also in a spacesuit), flying through a colourful tunnel. The person has an excited expression, a medium skin tone, and big curly hair that fills the bubble helmet of their spacesuit.

different terminal emulators use different escape codes

terminal emulator 1: if you print out ESC[2J I’ll clear the screen!

terminal emulator 2: for me it’s ESC[HESC[J!
your system has a database called “terminfo” with escape codes in it

how if plays out when you press Ctrl+L to clear the screen:

program, with a little heart over it, thinking:
ah, she wants fo clear the screen! I’ll look up how to do that in the terminfo database…

(on my machine, the database is in /usr/share/terminfo)

program: ESC[HESC[J

terminal emulator, thinking: ok, clearing the screen!
how programs know what terminal you’re using: TERM

your terminal emulator sets the TERM environment variable when it starts

fun fact: terminal emulators often say they’re “xterm-256color” even if they’re not
this can break when SSHing into an old system with a new terminal emulator

(in a VERY annoying way)

happy little stick fiture: I am using ghostty

program, with a little heart over it: NOPE never heard of it
some ways to fix TERM

install the terminfo file for your terminal emulator on the system
use a different terminal emulator
just set TERM=xterm-256color, it’ll often sort of work

redirect to a file:

cmd > file.txt terminal emulator into program, program out to file.txt, error out to terminal emulator
append to a file:

cmd >> file.txt terminal emulator into program, program out to file.txt (append mode), error out to terminal emulator
send a file to stdin:

cmd < file.txt file.txt into program, program out and err to terminal emulator
redirect stderr to a file:

cmd 2 > file.txt terminal emulator into program, program out to nowhere, err out to file.txt
redirect stdout AND stderr:

cmd > file.txt 2>&1 terminal emulator into program, out and err to file.txt
pipe stdout:

cmd1 | cmd2 terminal emulator into program 1, 1 out to program 2 via pipe, 2 out to command line, program 2 out 1 and 2 to terminal emulator
pipe stdout AND stderr:

cmd1 2>&1 | cmd2 terminal emulator into program 1, 1 and 2 out to program 2 via pipe, program 2 out 1 and 2 to terminal emulator
three gotchas

cmd file.txt > file.txt will delete the contents of file.txt some people use set -o noclobber (in bash/zsh) to avoid this

but I just have “never read from redirect to the same file” seared into my memory.

sudo echo blah > /root/file.txt doesn’t write to /root/file.txt as root. Instead, do:

echo blah | sudo tee /root/file.txt or sudo sh -c 'echo blah > /root/file.txt'

cmd 2>&1 > file.txt doesn’t write both stdout and stderr to file.txt. Instead, do: cmd > file.txt 2>&1

cat vs <

I almost always prefer to do:

cat file.txt | cmd

instead of

cmd < file.txt

it works fine & it feels better to me

using cat can be slower if if’s a GIANT file though
&> and &|

some shells support &> and &| to redirect/pipe both stdout and stderr

(also some shells use |& instead of &|)

your terminal emulator has two main jobs

turn your actions (typing & clicking) into bytes and send them
receive bytes and display them visually

Illustration of a terminal emulator, with a winking cursor face, and a program, represented by a box with a smiley face. The program has a heart above it, and there are arrows going back and forth between them labelled “bytes”
a little bit of history

it’s called an “emulator” because in the 80s a “terminal” was a separate machine from the computer

Illustration of a bulky old monitor, with a keyboard attached with a spiral cord, and a wire running to a panl of buttons and displays, labelld “mainframe”. There are arrows going back and forth between them labelled “bytes”

We still use the same 80s protocol!
what are these “bytes”?

the bytes are either:

text (like cat blah.txt)
escape codes (for example to tell the terminal what colour to display the text in)
control characters example Ctrl+C is the byte 3)

it’s in charge of copy and paste

your terminal emulator lets you select text and copy/paste it (usually with Ctrl+Shift+C (Linux) or Cmd+C (Mac))

(copy & paste tips on page 18!)
it manages colours and fonts!

some terminal emulators come with a big theme library of different colourschemes!

if yours doesn’t, this site has colourschemes for many terminal emulators: iterm2colorschemes.com
fun fact: how Ctrl-X gets translated to bytes

Ctrl-A => 1
Ctrl-B => 2
...
Ctrl-Z => 26

Ctrl is the only modifier key I trust in the terminal, all of the others can work differently depending on the situation

your TTY driver has configuration

you can see how it’s configured by running:

stty -a

for example it print out the current window size!
Ctrl+S

by default, pressing Ctrl+S wi(( freeze your terminal (and Ctrl+Q wi(( unfreeze) I have never wanted this in my life, you can turn it off with stty -ixon (fish turns it off by default)

###fun fact: changing Ctrl+C technically you can use stty to set a different keyboard shortcut for Ctrl+C, (ike “u”

stty intr u

this is extremely chaotic and I can’t imagine a reason that I would ever do this though
programs have to configure the TTY driver to get friendly features

developer: I want arrow keys to work in my program!

other person: better tell the TTY driver to turn off canonical mode! (more on the next page)
the TTY driver’s settings are called “termios settings”

for the gnarly details:

man termios

but if you’re writing a terminal program libraries like readline or ncurses will handle setting up the TTY driver
panel 6

smiling stick figure with short curly hair: I’ve only needed to use stty once in the last 20 years and I mostly don’t understand its output but I think it’s a fun view into terminal internals!

The Secret Rules of the Terminal, by Julia Evans - The cover illustration depicts three people doing arcane terminal magic in a temple with a smoking censer in the background. Each of the three people has curly brown hair and light brown skin. They are all wearing dresses, billowing cloaks, and utility belts with keyboard symbols on them. The one on the left holds a palette of paints and a brush. The one on the right has a staff with a $ symbol on it and a starfish at the top. The one in the centre has a sword and is reading from a book whose cover says “>_” and “./”, which rests on a lectern with a smiling snake wrapped around it.

the TTY driver is the most obscure part of the system

You almost never need to think about it, but when I’ve wanted to do something weird (like put a terminal in a web browser) understanding the driver is SO USEFUL
when you start your terminal emulator, it asks the OS to create a “pseudoterminal pair” which is a pair of two files

terminal emulator <-> TTY <-> TTY driver <-> TTY <-> program
a “TTY” is the program’s side of the pair

programs use it to:

communicate with the terminal emulator by reading/writing bytes
configure the TTY driver (more on the next page!)

Run tty fo see the current TTY!
the TTY driver is why Ctrl+C does the same thing relatively consistently

program: you press Ctrl+C, I send a signal!
well, unless the program tells me it wants the raw bytes!
some things the TTY driver is in charge of

(you might think “these are unrelated” and you’d be right)

storing the terminal window’s size
sending a SIGHUP signal when you close your terminal
a basic mode for entering text called “canonical mode”
pausing the output and confusing you when you press Ctrl+S
tracking which process is in the “foreground” and sending what you type there

$your terminal emulator has 16 configurable colours normal bright black 0 0 red 1 1 green 2 2 yellow 3 3 blue 4 4 purple 5 5 cyan 6 6 white 7 7 these are called “ANSI colours” you can configure them in your terminal emulator’s settings OR run a script that prints escape codes to magically set up your colours https://wzrd.page/scripts (my favourite way!) programs can use ANSI colours by printing an escape code echo -e "\033[34m blue text" 3 means “normal fg colour” 4 means “blue” the default ANSI colours often have bad contrast ls --color often displays directories in ANSI “blue” which can look like this: [bar of illegibly dark text against a dark background, which says “can you read this?”] ANSI “yellow” on white also often has bad contrast “minimum contrast” Picking ANSI colours which always have good contrast is impossible. the only real solution is to use a terminal emulator which has a “minimum contrast” feature (like iTerm or kitty) which will fix contrast issues usually if a program is writing to a pipe, it’ll disable colours $ grep blah file.txt | less grep, represented by a box with a smiley face: better turn off colours so that I don’t accidentally show someone `^[[34ntext here]$

your shell lets you run many programs (“jobs”) in the same terminal tab

programs can either be:

foreground
background
stopped (which is more like “paused”)

& runs a program in the background

for example I like to convert 100 files in parallel like this:

for i in `seq 1 100`
do
convert $i.png $i.jpg &
done

jobs lists backgrounded & stopped jobs

$ jobs
[1] Running python blah.py &
[2] Stopped vim

use the numbers to bring them to the foreground or background (like fg %2), kill them (kill %2), or disown them
when you close a terminal tab all jobs are killed with a SIGHUP signal

you can stop this with disown or by starting the program with nohup: disown %1 (job number goes here) nohup my_program &
a trick to kill programs if Ctrl+C doesn’t work

press Ctrl+Z to stop the program
run kill %1 to kill it (or kill -9 %1 if you’re feeling extra murderous)

a little flowchart

Three boxes, labelled “running in foreground”, “stopped”, and “running in background”

Ctrl+Z goes from “running in foreground” to “stopped” fg goes from “stopped” to “running in foreground” fg goes from “running in background” to “running in foreground” bg goes from “stopped” to “running in background”

editing text in a REPL doesn’t always work

little stick figure, horrified: when I press my ARROW KEYS it just prints out [[D??? what?
this is because every program has fo implement text editing itself

terminal program author, represented by a nonplussed looking stick figure with medium length straight hair, thinking: but I just want arrow keys to work?? shouldn’t that be automatic?

unix, represented by a box with a smiley face: NOPE you gotta do it
you do gef a few things automatically

backspace (occasionally backspace won’t work and you have to use Ctrl+H instead)
Ctrl+W (delete word)
Ctrl+U (delete line)

(see page 25 for what “automatically” means)
REPLs mostly have the same keyboard shortcuts

there’s a very popular library called “readline”, and everyone either uses it or imitates how it works

for example Ctrl+A (“go to beginning of line”) comes from readline
rlwrap adds readline keyboard shortcuts

for example on my machine the dash shell doesn’t use readline but you can make it better by running:

rlwrap dash
built in programs on Mac don’t use readline

(for example sq1ite3)

this is probably because readline is GPL licensed

They use libedit which is worse. I like to install a sqlite version with readline support and use that instead.

when you click in the terminal, it can either be handled by

your terminal emulator
(represented by a box with a winky cursor face and little arms and legs)
(good if you want to copy text)

or

the program
(represented by a box with a smiley face)
(lots of programs have mouse support!)
programs can tell the terminal emulator to let them handle the mouse

program: if there’s a mouse click, send me escape codes to tell me where it was!

terminal emulator: okay! I’ll disable all my usual mouse functions like “selecting text”!

this is called “mouse reporting”
some programs that have mouse support

tmux: resize a pane! right-click for a menu!
htop: click to sort columns!
micro: text editor with good mouse support
vim: click on the tab bar!
and lots more! (lazygit, mc, zellij, btop…)

how to force the terminal emulator to handle the mouse:

unhappy stick figure with short curly hair, thinking: ugh no I don’t want to focus that pane, I want to COPY SOME TEXT!!!

could be something else too, it depends on your terminal emulator

the scroll wheel

In some programs (like less) the scroll wheel does the same thing as pressing up/down arrow keys really fast

terminal emulator: UP UP UP UP UP UP UP UP UP UP UP UP

in other programs (like lazygit) it uses “mouse reporting” to report where your mouse was when you scrolled
other mouse features your terminal emulator might have

Shift+click (or something) to open a link in a browser
Alt+c1ick (or maybe Option) to move the cursor when editing a command in your shell

37% - 30+ years
39.5% - 10-30 years
13.6% - 5-10 years
10% - under 5 years

1. SHELL

cast of characters
meet the shell
PATH
PATH tips
history
job control
filename tips
stdin/stderr/stdout
redirects

2. TERMINAL EMULATOR

meet the terminal emulator
escape cdoes
colours
the mouse
copy & paste
TERM

3. PROGRAMS

types of programs
less
editing text in REPLs
keyboard shortcuts

4. TTY DRIVER

meet the TTY driver
stty
canonical mode

cmd > file.txt
cmd >> file.txt
cmd < file.txt
cmd 2> file.txt
cmd > file.txt 2>&1
cmd1 | cmd2
cmd1 2>&1 | cmd2

three gotchas:

1. cmd file.txt > file.txt will delete the contents of file.txt

some people use set -o noclobber (in bash/zsh) to avoid this

But I just have "never read from and redirect to the same file" seared into my memory.

2. sudo echo blah > /root/file.txt doesn't write to /root/file.txt as root. Instead, do:

echo blah | sudo tee /root/file.txt

or

sudo sh -c 'echo blah > /root/file.txt'

3. cmd 2>&1 > file.txt doesn't write both stdout and stderr to file.txt. Instead, do:

cmd > file.txt 2>&1

panel 3: cat vs <

I almost always prefer to do:

cat file.txt | cmd

instead of

cmd < file.txt

it usually works fine & it feels better to me

using cat can be slower if it's a GIANT file though

panel 4: &> and &|

some shells support &> and &| to redirect/pipe both stdout and stderr

(also some shells use |& instead of &|)

View with files on the left and diff for that file on the right

person with their hair in a spirally updo with earrings shaped like a shell

a debugging manifesto poster, risograph printed, neon pink and blue

* inspect, don’t squash
* being stuck is temporary
* trust nobody and nothing
* it’s probably your code
* don’t go it alone
* there’s always a reason
* build your toolkit
* it can be an adventure

$Panel 1: multiline It's SO scary when you paste a bunch of commands by accident and then it runs them all. fish, zsh, and newer bash versions protect you from this: you have to press Enter before running the thing you pasted. This is called "bracketed paste" panel 2: problem: copying with the mouse can go wrong - copying 400 lines of text by dragging is nobody's idea of a good time - sometimes extra whitespace that you didn't want gets added at the end of lines panel 3: person: “copying a LOT of text is way easier if you don't use the mouse! Here are 2 tricks for copying without the mouse. " panel 4: copy trick 1: pbcopy macOS comes with two programs that can copy from stdin / paste to stdout, like this: cat main.go | pbcopy They're SO useful and on Linux I like to write my own versions of pbcopy/pbpaste using xsel or xclip panel 5: pbcopy over SSH you can even implement pbcopy over SSH (yes really!) with this bash one-liner. It uses an escape code called "OSC 52". printf "\033]52;c;%s\007" "$(base64 | tr -d '\n')" panel 6: copy trick 2: syncing the vim clipboard I use vim as a terminal text editor, and I find it's WAY easier if I sync my system clipboard with the vim clipboard like this: set clipboard=unnamed tmux can also copy to your system clipboard.$

when you redirect, the shell opens the file BEFORE the program starts

sudo echo blah > file.txt

first I'll open file.txt...

THEN I'll run sudo echo blah

this is why file.txt isn't opened as root!

Panel 1: all terminal programs have 1 input and 2 outputs

they're numbered: stdin is "0", stdout is "1", stderr is "2".

(the numbers are called "file descriptors")

panel 2: you can set them to be any file you want

person: “I don't want to display the output in my terminal emulator, I want to write it to a file”
person: “I'll have the proram read input from a file instead of typing it in"

panel 3: 3 things you can set the inputs/outputs to

1. the TTY (so output is displayed in your terminal emulator)
2. a file
3. a pipe (to write output to the input of another program)

panel 4: your shell is in charge of setting up stdin/stdout/stderr

person: “python3 script.py > out.txt”

shell: “ok, I'll set stdout to out.txt for that program”

more about the syntax on page 15

panel 5: on 2>&1

2>&1 redirects stderr to stdout

you could also do 1>&2 but I've never used this N>&M syntax for anything other redirecting stderr to stdout

panel 6: gotcha: programs often buffer stdout but not stderr

when a program writes text to stdout, it'll often

1. check if stdout is a TTY (using the isatty function)
2. if not, "buffer" the writes until there's 1KB of data to write, for performance reasons

(this is the default in libc)

$panel 1: the terminal driver: an interface that hasn't changed since the 80s person: “I pressed an arrow key and it just printed out ^[[D???” terminal driver: “what's an arrow key?" panel 2: when you're typing text, there are two situations 1. by default: the terminal driver (part of the OS) is responsible "canonical mode" 2. the program is responsible “raw mode” panel 3: "canonical mode" is a terrible way to edit text because the terminal driver hasn't changed much since the 80s, you can only do: 1. backspace 2. Ctrl+W (delete word) 3. Ctrl+U (delete line) panel 4: how canonical mode works 1. you type "helll" + backspace 2. the terminal emulator turns what you typed into bytes 3. the terminal driver passes on "hell" and interprets the backspace 4. the program gets "hello\n" In canonical mode, terminal driver doesn't send anything to the program until you press Enter. In raw mode, the terminal driver just sends “hell\xFFo\n” without changing it panel 5: how to try out canonical mode Run `cat` and type some stuff! Interactive programs almost never use canonical mode because it's so limited. But if you run into it `rlwrap $COMMAND` can help$