Getting help: man, help and --help

Why this matters

Nobody memorizes the options of hundreds of commands. Experienced people are fast because they know where the answer is and how to read it in seconds. The documentation on a Linux system is complete, offline (useful in this sandbox, which has no network) and matches the exact version installed, which web answers often do not.

Three sources, one rule

There are three main places to look, and which one applies depends on the kind of command (remember type from lesson 2):

The rule: when unsure, run type name first, then pick.

help: builtins

$ help cd
cd: cd [-L|[-P [-e]] [-@]] [dir]
    Change the shell working directory.

    Change the current directory to DIR.  The default DIR is the value of the
    HOME shell variable. ...

help with no arguments lists every builtin, and help -d name gives a one-line description. You will use help heavily from module 7 on, for read, printf, declare, set, test and [[.

--help: the quick summary

Most GNU tools print a compact summary of their options with --help:

$ tail --help
Usage: tail [OPTION]... [FILE]...
Print the last 10 lines of each FILE to standard output.
...
  -n, --lines=[+]NUM       output the last NUM lines, instead of the last 10;
                             or use -n +NUM to skip NUM-1 lines at the start
...

It often scrolls off the screen. Send it through a pager: tail --help | less. (The | is a pipe; module 5 explains it. For now, read it as "feed the output into".)

man: the manual

man opens the manual page of a program in the pager less:

$ man tree

Inside less:

Searching is the real skill. Looking for how to sort by size in ls? Open man ls, type /size, press n until you find -S.

A man page has a standard layout:

• NAME: one line on what it is.
• SYNOPSIS: how to call it (notation below).
• DESCRIPTION: what it does, and often all the options.
• OPTIONS, EXIT STATUS, ENVIRONMENT, FILES, EXAMPLES, SEE ALSO.

Many pages are long; jump straight to EXAMPLES with /EXAMPLES if there is one.

Note: If man says No manual entry for ... in this sandbox, that page was not installed in the container image. Fall back to --help (for GNU tools) or help (for builtins).

SYNOPSIS notation

The synopsis uses a small grammar:

cp [OPTION]... [-T] SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY

• [x] means x is optional.
• x... means one or more x. [x]... means zero or more.
• a|b means a or b.
• UPPERCASE or underlined words are placeholders you replace with your own values.
• Several synopsis lines mean several ways of calling the program.

So the second line says: any number of options, then one or more sources, then exactly one directory at the end.

Sections

The manual is divided into numbered sections, because the same name can mean different things:

man passwd shows section 1, the command. man 5 passwd shows the file format of /etc/passwd. Documentation writes this as passwd(5). Try man 7 hier now: it describes the directory layout you will explore in the next module. And for the curious, man 2 fork and man 2 execve describe the two system calls from lesson 2.

man -k word (the same as apropos word) searches the one-line descriptions of all pages, and whatis name prints just the NAME line. They rely on an index that may not be built in a minimal container, so do not worry if they find nothing here.

Reading documentation well

• Start with the synopsis and the option you need, not the first paragraph.
• Search, do not scroll. / in less, or tail --help | grep lines.
• Try it on test data. The sandbox is ideal for this: make a small file and experiment.
• Check the EXIT STATUS section when you will use a command in a script.

Common mistakes

• man cd for a builtin. Builtins are documented by help. (bash's own man page, man bash, also documents all of them, but it is huge; search it with /^SHELL BUILTIN.)
• Getting stuck in less. Press q. In man you are in less, not in the shell.
• Typing --help for a non-GNU tool. Some programs do not know it and print an error or, worse, treat it as an argument. It is harmless on GNU tools.
• Forgetting the section number. man printf gives the shell command printf(1), not the C function printf(3).

Recap

• type tells you what a command is; help documents builtins, man and --help external programs.
• man pages open in less: Space, b, /search, n, q.
• SYNOPSIS notation: [optional], repeat..., a|b, PLACEHOLDERS.
• Manual sections: 1 commands, 5 file formats, 7 overviews, 8 admin; man 5 passwd.

Going further: read man 7 hier, then help help. Pick one command you used today and find its EXIT STATUS section.