Linux command line users must be familiar with "man" command. It stands for manual pages, which means that every Linux command or utility comes with the set of instructions or possible usage of the command. Man pages are of great help while working on the command line, but often, the documentation available via man pages is too lengthy or too confusing to learn. It also does not provide any real life examples too. All it include is the details of what that particular command does, and what are its available switches ( also called options ).
TLDR (Too Long Didn’t Read) is a community driven efforts to improve default Linux man pages, it provides an easy to under documentation for every command or utility and it also demonstrates the usage of the command with pretty simple examples. In this article, we will be learning the process to install TLDR and how to use it to work better on Linux terminals.
How to install TLDR on Ubuntu and CentOS Systems
The easiest way to install TLDR is by using NPM and Nodejs. So we need to first install these two components on our system. Ubuntu system users can install NPM and Nodejs by using the following command.
sudo apt-get install nodejs npm
CentOS users will need to first enable Yum's EPEL repository. Run the following command to install Epel repository, once it is active, then we will be able to install nodejs and npm using YUM.
yum install epel-release -y
Run the following command on CentOS system to install Node and NPM.
sudo yum install nodejs npm
Alright, run following command on your system now to complete the installation process.
sudo npm install -g tldr
Congratulations, you have successfully equipped your Linux system with an easy to understand command manuals.
TLDR examples
The syntax to get help using TLDR is pretty simple, use the following format.
tldr Command
Where replace "Command" with actual utility or command name you are trying to get documentation for.
The documentation for "ls" command looks like as shown below.
# tldr ls 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
Isn't it extremely easy and descriptive way? here is how tar command's documentation looks like:
# tldr tar tar Archiving utility. Optional compression with gzip / bzip. - 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 an archive in a target folder: tar xf source.tar -C folder - Extract a gzipped archive in the current directory: tar xzf source.tar.gz - Extract a bzipped archive in the current directory: tar xjf source.tar.bz2 - Create a compressed archive, using archive suffix to determine the compression program: tar caf target.tar.xz file1 file2 file3
As you can see, it offers a very intuitive way to search information about commands. It shows examples of the different usages of every command, which makes them very easy to understand.
You can also list all the available commands in the repository by typing:
$ tldr -l
Contributing
If you don't find a command or you have more examples for an existing command, you're welcome to contribute to the project!
Firstly and very important, make sure you respect all these items:
Guidelines
- It's best to keep pages at around 5 examples. If it's really needed, pages can be longer, but can't exceed 8 examples. The page doesn't have to cover everything, that's what man is for.
- When you are in doubt with something, go for the secure method that you know it will work always. For example: Commands that require sudo should include it directly in the examples.
- Include spelled-out options in addition to single-letter options. This gives the possibility to the user to understand what he/she is doing.
- In the examples, start with the easier options and then continue with the more complex ones.
- Avoid explaining general UNIX concepts, only focus on the commands' specific details.
Markdown format
The format of each page should be like this:
# command-name > Short, snappy description. > Preferably one line; two are acceptable if necessary. - Example description: `command -opt1 -opt2 -arg1 {{arg_value}}` - Example description: `command -opt1 -opt2`
There is a formatter that enforces the above format. It's run automatically in every pull request, but you can install it to see how your contributions will look like:
$ sudo npm install tldr-lint $ tldrl -f {{page.md}}
You can check more uses or tldrl by typing:
$ tldr tldrl
Token syntax
Use {{token}} syntax for user-provided values to allow tldr clients to highlight them. Multi-word tokens shoul use snake_case.
Guidelines for choosing token names:
- Token values have to be short and descriptive. For example: {{file_route}} or {{home/user/.bashrc}}
- If the example is clearer using an actual value rather than writing the input variable,parameter name, or whatever, use the actual value. For example: Use shutdown -h {{5}} rather than shutdown -h {{time_in_HHmm}}
- For any reference to paths to files or folders, use the format {{path/to/<placeholder>}}. For example, ln -s {{path/to/file}} {{path/to/symlink}}. In case of a possible reference both to a file or a folder, use {{path/to/file_or_folder}}
- Follow the {{path/to/<placeholder>}} convention when there is a path-related command, except when the file location is implicit.
- If there is a command that expects a file to have a specific extension, show it. Example: unrar x {{compressed_file.rar}}. If a generic extension is needed, use {{.ext}}
This are only guidelines, no strict rules, just try to follow them and make the examples the most intuitive possible.
Submitting a pull request
You can use the method that you prefer:
Github's web interface
The easiest way is to edit the page directly from the Github UI. You can see some instructions over here.
Command line
- Fork the repository from the Github UI
- Clone your fork to your local computer
https://help.github.com/articles/editing-files-in-another-user-s-repository/
- Create a feature branch
git checkout -b {{branch_name}}
- Make your changes
- Commit the changes
git commit --all -m "{{commit_message}}"</>
- Push to your fork
git push origin {{branch_name}}</>
- Go to the github page for your fork and click the green pull request button.
Send only related changes in the same request.
For the commit message, use this command:
<command>: type of change
Example: ls: add page
You can also refer to the official repository to find more documentation.
Updating TLDR
It is important to keep TLDR updated so you may have most up-to-date information available. It is continuously adding more and more documentation to it and you can update it by using the following command.
tldr --update
Using Online ( Web-based)
You can also view the documentation/help for Linux command using the online version. Developers have a web URL which you can use to search for the documentation or help for any Linux utility/command. Head to the following URL and simply type your desired command/utility name and press "Enter", you will be presented with community documentation of the searched command and it is pretty eye candy interface.
Hope you enjoyed this article, we have discussed the installation and usage process for TLDR command in this tutorial. You can also use the online version of this utility to improve your daily Linux command line working productivity. It saves you a lot of time and provides you much-needed information in extremely easy and detailed way possible. Try it today! do let us know in the comments section about your experience with this utility.
Using copy & paste commands in Linux Mint 18,1 Mate doesn't work.
jim@mate ~ $ tldr ls
/usr/bin/env: ‘node’: No such file or directory
jim@mate ~ $
jim@mate ~ $ tldr --update
/usr/bin/env: ‘node’: No such file or directory
jim@mate ~ $
Hi Jim
It appears nodejs is not properly working on your system. If nodejs is installed, try adding its symlink:
ln -s /usr/bin/nodejs /usr/bin/node
I get following error message when using tldr
peter@Dell:~$ tldr update
/usr/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
if (e.code !== 'MODULE_NOT_FOUND') throw e;
^
Error: Could not locate the bindings file. Tried:
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/out/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/out/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/default/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/compiled/8.9.1/linux/ia32/WebWorkerThreads.node
at bindings (/usr/lib/node_modules/tldr/node_modules/bindings/bindings.js:93:9)
at Object. (/usr/lib/node_modules/tldr/node_modules/webworker-threads/index.js:1:105)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)
at tryModuleLoad (module.js:497:12)
at Function.Module._load (module.js:489:3)
at Module.require (module.js:579:17)
at require (internal/module.js:11:18)
at Object. (/usr/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:29:19)
Are you getting same error when you command as root ?
try
npm install -g --ignore-scripts tldr
tldr --update
I get exactly the same error message in root or user and on every command i.e tldr ls, tldr fdisk, tldr update and so on
Which OS and version you are using?
Thank you Bobbin Zachariah, the result is:
root@Dell:~# npm install -g --ignore-scripts tldr
npm WARN deprecated node-uuid@1.4.8: Use uuid module instead
/usr/bin/tldr -> /usr/lib/node_modules/tldr/bin/tldr
+ tldr@3.1.1
updated 1 package in 14.027s
root@Dell:~# tldr update
/usr/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
if (e.code !== 'MODULE_NOT_FOUND') throw e;
^
Error: Could not locate the bindings file. Tried:
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/out/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/Debug/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/out/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/Release/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/build/default/WebWorkerThreads.node
→ /usr/lib/node_modules/tldr/node_modules/webworker-threads/compiled/8.9.1/linux/ia32/WebWorkerThreads.node
at bindings (/usr/lib/node_modules/tldr/node_modules/bindings/bindings.js:93:9)
at Object. (/usr/lib/node_modules/tldr/node_modules/webworker-threads/index.js:1:105)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)
at tryModuleLoad (module.js:497:12)
at Function.Module._load (module.js:489:3)
at Module.require (module.js:579:17)
at require (internal/module.js:11:18)
at Object. (/usr/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:29:19)
I am using Debian 9 and nodejs was installed from synaptic
Thanks. We will check and get back
Peter, I could replicate your problem and solved it, try this:
#Find the location of the missing file
$ sudo find -name "WebWorkerThreads.node"
In my case, it was located in ./node_modules/webworker-threads/build/Release/ and ./node_modules/webworker-threads/build/Release/obj.target/
#Copy the found build directory into the path that TLDR is checking
$ sudo cp -r ./node_modules/webworker-threads/build/ /usr/lib/node_modules/tldr/node_modules/webworker-threads/
And it will now work. Just tell me if you have any problem!
@ Peter .. Ivo from our team tested..see his reply above.. Let us know how it goes. Good luck
The find command returns no such file or directory. It would appear the file is missing.
nodejs version installed is
8.9.1-nodesource1 according to synaptic package manager.
I have added myself to sudoers list and am able to enter my password but all attempts to follow your instructions fail because the above file cannot be found.
I am a relative newcomer to cli but it would appear I need to download that file from somewhere or use an earlier version of nodejs.
I do appreciated your help because it accelerates my learning curve. Thanks again
Ok so I tried a different syntax of the file command
sudo find / -name WebWorkerThreads.node
The search commenced ok but finished in about 30 seconds back to user prompt
Problem solved! It was to do with npm permissions. Found solution on npmjs website under " fixing npm permissions"
Here is the text
You may receive an EACCES error when you try to install a package globally. This indicates that you do not have permission to write to the directories that npm uses to store global packages and commands.
You can fix this problem using one of three options:
Change the permission to npm's default directory.
Change npm's default directory to another directory.
Install Node with a package manager that takes care of this for you.
Apparently, according to option 3 above, Synaptic should have taken care of it but didn't.
I used option 2 and all is now working
Thanks everybody for your guidance
Peter Rowe
Awesome. Good job !!!
In the same vein, there is also cheat.sh (both a binary & web app)
Dear Aun,
This is very good example of TLDR. Are you able to write another article on various types of systemd, sysvinit etc. It adds too much confusion.
Apparently inittab is no longer used and I am thoroughly confused.
Also with various distros this changes again, adding another layer, so to speak, of confusion.
So if you can write with a a table then it will be good.
Best Wishes,
PG