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:
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:
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
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
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
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
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.