TLDR

TLDR is a great application that provides simplified versions of man pages for many commonly used command line applications. Just about any command that you can think of there is a TLDR for it: git, ack, jq, composer, vim, curl, wget, and many more. Instead of providing a verbose man page, it just has a simple description as to what the command does as well as a few common ways of using the command.

For an example, this is the result of tldr composer:

  composer

  A package-based dependency manager for PHP projects.
  More information: https://getcomposer.org/.

  - Add a package as a dependency for this project, adding it to composer.json:
    composer require user/package_name

  - Install all the dependencies in this project's composer.json:
    composer install

  - Uninstall a package from this project, removing it as a dependency from composer.json:
    composer remove user/package_name

  - Update all the dependencies in this project's composer.json:
    composer update

  - Update composer to the latest version:
    composer self-update

It's a great tool that I highly recommend. The most common way to use it is as Node.js client, but there are other ways to install it.

npm install -g tldr

Building your custom TLDR

After using it for awhile, I got to thinking about a lot of custom commands that I use personally, and how it would be nice to have some of those listed within TLDR. Examples are custom vim mappings that I use or custom aliases. While TLDR is open source and welcomes contributions to the repo, my custom commands would be of no use to the general public. So I got to thinking how I could customize it just for my use.

The first step was to fork the main repo: https://github.com/tldr-pages/tldr

Next, you can add all of the custom pages that you want. I added mine inside the "pages/common" folder, but you can also choose to add them to a language specific folder. Refer to other pages on how to format the page.

After adding your custom pages, you will need to build the zip file that is at the root of the repo, and commit that file as well. You can build the zip file by running:

bash scripts/build.sh

Then you can commit everything and push up the changes.

You will also need to create a custom .tldrrc file to put in your home directory. I just copied the default file and changed the repository to point to the zip file in my own repo.

{
  "pagesRepository": "https://github.com/tldr-pages/tldr",
  "repository": "https://github.com/<your-github-username>/tldr/blob/master/tldr.zip?raw=true",
  "themes": {
    "simple": {
      "commandName": "bold, underline",
      "mainDescription": "bold",
      "exampleDescription": "",
      "exampleCode": "",
      "exampleToken": "underline"
    },
    "base16": {
      "commandName": "bold",
      "mainDescription": "",
      "exampleDescription": "green",
      "exampleCode": "red",
      "exampleToken": "cyan"
    },
    "ocean": {
      "commandName": "bold, cyan",
      "mainDescription": "",
      "exampleDescription": "green",
      "exampleCode": "cyan",
      "exampleToken": "dim"
    },
    "inverse": {
      "commandName": "bold, inverse",
      "mainDescription": "inverse",
      "exampleDescription": "black",
      "exampleCode": "inverse",
      "exampleToken": "green, bgBlack, inverse"
    },
    "matrix": {
      "commandName": "bold",
      "mainDescription": "underline",
      "exampleDescription": "green, bgBlack",
      "exampleCode": "green, bgBlack",
      "exampleToken": "green, bold, bgBlack"
    }
  },
  "theme": "base16"
}

Now there are two different commands that you can use to ensure that your TLDR has the updated pages.

# Clear cache
tldr -c

# Update the local cache
tldr -u

Vim Users

If you're a vim user, there is a vim plugin that you can use to integrate.

# Run the command
:Tldr <command>

# Refresh the local cache of commands
:TldrUpdateDocs

In order to make the vim plugin point to your custom repo, you will need to add this in your vimrc.

let g:tldr_source_zip_url = 'https://github.com/<your-github-username>/tldr/archive/master.zip'

Zsh Users

Zsh users can also take advantage of autocomplete features. See here on how to set that up.