Use tldr for command line examples

manual pages are a reference

If you use the command line you’ve probably already seen manual pages, accessed via the man command.

$ man git-log

NAME
git-log - Show commit logs

SYNOPSIS
git log [<options>] [<revision range>] [[--] <path>...]

DESCRIPTION
Shows the commit logs.

The command takes options applicable to the git rev-list command to
control what is shown and how, and options applicable to the git diff-*
commands to control how the changes each commit introduces are shown.

OPTIONS
--follow
Continue listing the history of a file beyond renames (works only for a single file).

--no-decorate, --decorate[=short|full|auto|no]
.
.
.

man pages are great when you need a full reference for a command. “What’s the git-log flag to only show merge commits? (--merges)

But what if you want examples of common use? For that man pages aren’t so helpful. Sometimes you’ll get examples throughout the doc or maybe at the end. Or maybe you can piece together the command patterns from the synopsis.

SYNOPSIS
git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
           [--dry-run] [(-c | -C | --fixup | --squash) <commit>]
           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
           [-i | -o] [-S[<keyid>]] [--] [<file>...]

There’s a better way?

There IS a better way! TLDR pages!

TLDR pages are community driven reference examples accessed by a tldr command made available by a wide range of clients. From brew install tldr to npm install -g tldr and many others: you can probably find a tldr client implementation you can live with. There’s even a generated PDF of tldr pages if you must have it.

What do we get from `tldr`?

Examples!

$ tldr git log

git log

Show a history of commits.
More information: <https://git-scm.com/docs/git-log>.

- Show the sequence of commits starting from the current one, in reverse chronological order:
    git log

- Show the history of a particular file or directory, including differences:
    git log -p path/to/file_or_directory

- Show only the first line of each commit message:
    git log --oneline

- Show an overview of which file(s) changed in each commit:
    git log --stat

- Show a graph of commits in the current branch:
    git log --graph

- Show a graph of all commits, tags and branches in the entire repo:
    git log --oneline --decorate --all --graph

- Show only commits whose messages include a given string (case-insensitively):
    git log -i --grep search_string

Way awesome! Nice, clear examples of how to commonly use the git-log command.

$ tldr tar

tar

Archiving utility.
Often combined with a compression method, such as gzip or bzip.
More information: <https://www.gnu.org/software/tar>.

- Create an archive from files:
    tar cf target.tar file1 file2 file3

- Create a gzipped archive:
    tar czf target.tar.gz file1 file2 file3

- Extract a (compressed) archive into the current directory:
    tar xf source.tar[.gz|.bz2|.xz]

- Extract an archive into a target directory:
    tar xf source.tar -C directory

- Create a compressed archive, using archive suffix to determine the compression program:
    tar caf target.tar.xz file1 file2 file3

- List the contents of a tar file:
    tar tvf source.tar

- Extract files matching a pattern:
    tar xf source.tar --wildcards "*.html"

Yes!

But what about different platforms?

I hear you. There are lots of commands that are available to Linux and not MacOS and vice versa. Not to mention SunOS.

tldr is there for you. You can pass a -p or --platform flag to tldr to tell it the platform docs it should check instead of defaulting to the platform you’re currently using.

If I run tldr service on macOS then I only get back a “page doesn’t exist” message because service is not a command on macOS. But it is a command on Linux! So if I want to lookup the Linux service command from a macOS machine I pass -p linux to the tldr command.

$ tldr service
This page doesn't exist yet!
Submit new pages here: https://github.com/tldr-pages/tldr

$ tldr -p linux service

service

Manage services by running init scripts.
The full script path should be omitted (/etc/init.d/ is assumed).

- Start/Stop/Restart/Reload service (start/stop should always be available):
    service init_script start|stop|restart|reload

- Do a full restart (runs script twice with start and stop):
    service init_script --full-restart

- Show the current status of a service:
    service init_script status

- List the status of all services:
    service --status-all

Pages that don’t exist yet

If you find there’s a command you know about that doesn’t yet have a tldr page then you can submit a PR to the project with the examples. For example how that tldr service on macOS helpfully shared with me where I could submit a PR.

You can check out all the newly proposed tldr commands since they’re all nicely tagged with a new-command label.