Skip to content

More helpful help for Terminal commands

I use Terminal a fair bit, for any number of things. But I don't use it all the time, and that means I sometimes struggle to remember syntax of commands. "Was it rsync source destination or the other way around? Or was it ln that was backwards of what I thought it should be?"

You can open the man page for a command, of course, but sometimes there's so much there that finding the simple thing you want is tough. Enter tldr, installable via Homebrew or MacPorts. tldr skips most of the detail of the man pages, providing user-curated examples of how to use a given command.

As an example, here's the aforementioned rysnc command's man page:

$man rsync

NAME
       rsync - a fast, versatile, remote (and local) file-copying tool

SYNOPSIS
       Local:
           rsync [OPTION...] SRC... [DEST]

       Access via remote shell:
           Pull:
               rsync [OPTION...] [USER@]HOST:SRC... [DEST]
           Push:
               rsync [OPTION...] SRC... [USER@]HOST:DEST

       Access via rsync daemon:
           Pull:
               rsync [OPTION...] [USER@]HOST::SRC... [DEST]
               rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
           Push:
               rsync [OPTION...] SRC... [USER@]HOST::DEST
               rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)

       Usages with just one...

The information I need is definitely in there, though it takes some detailed reading to pull it out. Compare that to the tldr entry for rysnc:

$ tldr rsync

  rsync

  Transfer files either to or from a remote host (but not between two remote hosts), by default using SSH.
  To specify a remote path, use host:path/to/file_or_directory.
  More information: https://download.samba.org/pub/rsync/rsync.1.

  - Transfer a file:
    rsync path/to/source path/to/destination

  - Use archive mode (recursively copy directories, copy symlinks without resolving and preserve permissions, ownership and modification times):
    rsync --archive path/to/source path/to/destination

  - Compress the data as it is sent to the destination, display verbose and human-readable progress, and keep partially transferred files if interrupted:
    rsync --compress --verbose --human-readable --partial --progress path/to/source path/to/destination

  - Recursively copy directories:
    rsync --recursive path/to/source path/to/destination...

Just what I need: Many examples of the syntax needed for various uses of rsync. There aren't tldr entries for every command, of course, but I always check before opening a man page now. With Homebrew installed, installation is as easy as brew install tldr. A similar command works for MacPorts, but as I use Homebrew, the exact wording is left as an exercise for the reader.

3 thoughts on “More helpful help for Terminal commands”

  1. What a great idea. I still use your keyboardmaestro action to make a “pretty” pdf from a man page. Good stuff.
    Paul

  2. Man pages are one of the most infuriating things in Unix. (and I say this as someone who spends a lot of his workday for the last couple of decades on the command line) Most of the time they're written as if the reader is suppesed to know the program, just needs a reminder about the various parameters.

    Worst are the ones that offer cryptic descriptions, cryptic error messages and no examples.

    I'll give tldr a shot, but sadly I'll probably forget it's installed by the next time I need it!

  3. tldr pages is a really nice reference. Thanks to their wonderfully simple API—a collection of JSON files on GitHub—there are a lot of really nice integrations available.

    I've contributed to the tldr pages docset for Dash https://kapeli.com/dash. If you have Dash installed, look for "tldr pages" in the User Contributed section. I use this in conjunction with the Dash plugin for Alfred https://alfred.app, so I can type in something like tldr rsync into Alfred to get results quickly.

    See the full list of tldr pages clients to see what else is available. https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients

Leave a Reply

Your email address will not be published. Required fields are marked *