Robin Sloan’s
post about “home-cooked” code
has been making the rounds, and for good reason. It’s about
highly personalized programs; when you build something purely for
yourself or a small audience, it’s more like home cooking
than industrial production. I really love the analogy, and
it’s inspired me to write about one of my own
“home-cooked” tools:
wat
.
The Problem
I spend a lot of my day in a terminal, and command line interfaces have notoriously poor discoverability. It’s easy to remember the handful of commands+flags you use on a regular basis; it’s much harder to remember the ones you only use a couple times a year. So, like many people, I used to spend a lot of time digging through man pages when 1) I know what I want to accomplish 2) I can’t remember the exact CLI syntax to make it happen.
Unfortunately, man pages usually aren’t designed for this. The average man page is more like a lengthy novel than Cliff’s Notes; it’s thorough+exhaustive documentation when I just want a quick reference.
There are a few excellent projects that provide succinct
documentation for *nix commands:
tldr
and
cht.sh
are my
favourites. But they don’t provide good facilities for
adding personalized documentation of my own; that’s where
wat
comes in.
What Wat Does
wat
started out as a simple wrapper around
tldr
and cht.sh
. The two provide similar
content, but they do so in different ways; tldr
is
installed locally, cht.sh
is usually accessed through
a dead-simple web interface: curl cht.sh/command
. The
first iteration of wat
was just a simple
fish function that would call
tldr
if it’s installed, and otherwise fall back
on cht.sh
.
These days, wat
is written in Python and it’s a
tiny bit more sophisticated: it also displays custom
Markdown notes which are synced across all my machines using Git.
Say I want to get some information about a video file, but I
can’t remember the exact ffprobe
syntax. I just
type wat ffprobe
in my terminal:
This returns a handy tldr
/cht.sh
summary
and it renders the contents of
~/notes/ffprobe.md
if it exists. In this case, it
looks like I got annoyed enough by ffprobe
to write
down
a note
for the -hide_banner
flag.
I’ve been maintaining command line notes for a long time, in
various tools that just happened to be at hand: OneNote,
Notes.app,
Markdown in a repo… but wat
lets me organize that information
better, and view it inline with excellent community-provided
documentation.