Reading Time: 4 minutes

Today’s article is an introduction to the ‘tldr’ utility, a collection of simplified and community-driven man pages. ‘tldr’ enhances Unix/Linux by providing clear, real-world examples for using command line utilities.

When I was a kid, I had the kind of parents who would never tell you the meaning of a word.
“Get the dictionary and look it up,” I was told over and over.
It was good for me, of course, as a learning exercise, but at the time, it seemed almost punitive.
“Ugh, do I haaaave to? Can’t you just tell me??”

Well, if you’re like me, that’s how it feels to work with Unix “man’ pages–you know that all the answers to your questions are in there, somewhere, but the compilers of the pages seem to have forsaken readability for completeness and uniformity.
That doesn’t help, when some commands are notoriously hard to remember:

Unix ‘man’ pages have been around since 1971, first written by Dennis Ritchie and Ken Thompson, the most venerated names in Unix. They are necessary and thorough, don’t get me wrong. I have nothing but respect for them. It’s just that, well, once in a while, they were a bit more, readable and perhaps, concise. For example, here’s (a bit of) what ‘man’ has to say about the ‘ls’ command:

$ man ls

LS(1)                                                                                           User Commands                                                                                           LS(1)

NAME

       ls – list directory contents
SYNOPSIS

       ls [OPTION]… [FILE]…
DESCRIPTION

       List information about the FILEs (the current directory by default).  Sort entries alphabetically if none of -cftuvSUX nor –sort is specified.
       Mandatory arguments to long options are mandatory for short options too.
       -a, –all

              do not ignore entries starting with .
       -A, –almost-all

              do not list implied . and ..
       –author

              with -l, print the author of each file
       -b, –escape

              print C-style escapes for nongraphic characters
       –block-size=SIZE

              scale sizes by SIZE before printing them; e.g., ‘–block-size=M’ prints sizes in units of 1,048,576 bytes; see SIZE format below
       -B, –ignore-backups

              do not list implied entries ending with ~
       -c     with -lt: sort by, and show, ctime (time of last modification of file status information); with -l: show ctime and sort by name; otherwise: sort by ctime, newest first

(That’s just the start. It goes on for a total of 206 lines on my system.)
Reading that feels a bit like taking that long walk to the bookshelf to open the dictionary, only to be overwhelmed with seemingly irrelevant information, when the information you actually needed could have been cleared up with an example or two. (Again, I’m not advocating the dumbing down of the ‘man’ page system–it’s comprehensive, as it needs to be. It’s just that there’s room for something more, especially as more and more casual users discover Linux.)

ls is one of the simplest commands in the *nix shell. Essentially, it lists out the contents of a directory. You can run it by itself:

$ ls

bar  baz  corge  foo  quux  quuz  qux

That will list out the names of the non-hidden files in a directory. If you want to see the hidden files, you add the ‘-a’ option:

$ ls -a

.  ..  bar  baz  corge  foo  .hidden_file  quux  quuz  qux

If you want to list out pretty much everything, add a bunch more options, that spell out “-Flag” (That’s 4 options, ‘F’, ‘l’, ‘a’ and ‘g’, not a word. ‘galF’ would work as well, but ‘Flag’ is easier to remember.):

$ ls -Flag

total 48

drwxrwxr-x  3 jim  4096 Jun  6 17:45 ./

drwxr-xr-x 43 jim  4096 Jun  6 17:45 ../

-rw-rw-r–  1 jim 11962 Jun  6 17:41 bar

-rw-rw-r–  1 jim     0 Jun  6 17:42 baz

-rw-rw-r–  1 jim   544 Jun  6 17:44 corge

-rw-rw-r–  1 jim  7771 Jun  6 17:41 foo

-rw-rw-r–  1 jim  3259 Jun  6 17:45 .hidden_file

-rw-rw-r–  1 jim     4 Jun  6 17:43 quux

-rw-rw-r–  1 jim   182 Jun  6 17:44 quuz

drwxrwxr-x  2 jim  4096 Jun  6 17:43 qux/

Those are (almost) all of the options I’ve ever bothered to memorize. According to ‘man’ there are 59 different options, but no user-friendly examples, accessible for a newbie, or someone in a hurry.

'tldr' to the rescue!
The ‘tldr’ Github page describes itself as:
“A collection of simplified and community-driven man pages.”
That sounds pretty promising. Let’s install it and try it out!

$ sudo npm install -g tldr

(Unfortunately, on two of my systems, that produced hundreds of lines of errors about ‘node-gyp’ and something called ‘webworker-threads’. No worry, there’s a ‘snap’ package I can install:

$ sudo snap install tldr

which worked without a hitch.)
Let’s try it out with ‘ls’:

$ tldr ls

Page not found. Updating cache ..

Creating index…

Done

  ls
  List directory contents.
  – List files one per line:

    ls -1
  – List all files, including hidden files:

    ls -a
  – Long format list (permissions, ownership, size and modification date) of all files:

    ls -la
  – Long format list with size displayed using human readable units (KB, MB, GB):

    ls -lh
  – Long format list sorted by size (descending):

    ls -lS
  – Long format list of all files, sorted by modification date (oldest first):

    ls -ltr

That was even easier than Googling stackoverflow. (Of course, if you were to *ask* on stackoverflow something as simple as options for ‘ls’, you’d immediately get sent to the ‘man’ pages.) Fortunately, there are places to go for questions like this.

If you’re not ready to install tldr on your own system yet, you can always use the online version.

I hope this has been helpful. I only found out about ‘tldr’ this morning, as it was linked to from a post on Reddit and wanted to share it with you all.