Getting Help: man, help and --help

Part I · Module 1 · Chapter 1.6 · Getting Help: man, help and --help

1. Why This Is a Skill and Not a Lookup

Chapter 1.1 made a point that pays off here: most commands are separate programs, written by different people, each with its own option set. Nobody memorises them. What experienced engineers have is not recall but a routine — a reliable way to get an authoritative answer in under a minute.

There is also a reason to prefer the machine over a search engine, and it is not purism. The documentation installed on a machine describes the program that machine actually has — that version, that build, that distribution's choices. A web page describes some version somebody else had. Chapter 1.1's three layers are exactly why those can differ, and §7 shows what it costs when they do.

Three sources, in the order you will usually reach for them:

2. --help: the Fast Answer

Most ordinary commands accept --help and print a summary.

ls --help

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX --sort nor --dirsort.

  -a, --all                  do not ignore entries starting with .
  -h, --human-readable       with -l and -s, print sizes like 1K 234M 2G
  -l                         use a long listing format

Three things in that output are worth noticing.

The usage line comes first, and it is in the notation §4 teaches. It is the densest useful sentence in the whole page.

Options appear in both spellings where both exist — -a, --all — which is the quickest way to find the readable form of a short option you met in somebody else's script.

-l has no long form here. That is a real fact about the program, not an omission in the output. Chapter 1.5 warned that long options are not universal; this is where you verify it per option.

3. man: the Installed Manual

man ls

This opens the manual page for ls in a pager — a program that shows one screenful at a time. A manual page follows a conventional order, and knowing the order is most of the skill:

Three keys get you around the pager:

The pager here is almost always less, which is a capable program in its own right with far more than three keys. Module 4 treats it properly, as the main tool for reading a long file by hand.

4. Reading a SYNOPSIS

This is the part that genuinely has to be taught, because the notation is compact and looks like something you should type.

ls [OPTION]... [FILE]...
grep [OPTION...] PATTERNS [FILE...]

The notation has four pieces:

Applied to the first line: ls may be given any number of options, none required, followed by any number of file or directory names, also none required. Which is exactly the behaviour Chapter 1.4 saw — bare ls lists the working directory.

Applied to the second: grep may be given options, then must be given PATTERNS, because it is not in brackets, then may be given any number of files. That single line tells you the pattern is mandatory and comes first — the positional rule from Chapter 1.5, documented.

An alternatives example, which is also the chapter's pivot:

cd [-L|-P] [dir]

Read it: cd accepts either -L or -P, but not both, and both are optional; it also accepts an optional directory. In three characters the vertical bar has told you the two options are mutually exclusive — something that would take a sentence of prose.

5. help: Asking Bash About Itself

Where did that cd synopsis come from? Not from a manual page.

help cd

cd: cd [-L|-P] [dir]
    Change the current directory to DIR.  The variable $HOME is the
    default DIR.
    ...

A short form is available when the synopsis is all you wanted:

help -s cd

cd: cd [-L|-P] [dir]

And help on its own lists everything it can tell you about:

help

GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
These shell commands are defined internally.  Type `help' to see this list.
Type `help name' to find out more about the function `name'.

That list is worth one look, because it is the definitive answer to a question you might not have known you had: which commands are part of Bash itself.

6. Why help cd and man ls Are Different Questions

This is the conceptual centre of the chapter.

man ls asks the system for the manual of a separate program — a file on disk, written and documented by its own authors, installed by the distribution, with its own version number.

help cd asks Bash about part of itself. There is no separate cd program doing the work. The documentation comes from inside the shell, which is why it arrives instantly, why it has no manual page of its own on many systems, and why its wording changes when your Bash version changes.

Try the mirror image of each and the asymmetry is visible:

man cd

No manual entry for cd

On some systems you instead get a page documenting all the shell's builtins collectively, which is the same answer in a different shape: cd is not a program, so it has no program manual.

help ls

bash: help: no help topics match `ls'.  Try `help help' or `man -k ls' or `info ls'.

Bash is being precise. ls is not one of its features, so it has nothing to say — and it helpfully points you at the tools that do.

7. Manual Sections, Briefly

One more piece of man worth knowing, because it eventually bites.

The manual is divided into numbered sections — different volumes of the same reference. The two you will meet soonest:

• Section 1 — user commands. ls, grep, cp.
• Section 5 — file formats. The format of a configuration file rather than a command.

So man passwd describes the command that changes a password, while man 5 passwd describes the format of the file that stores accounts. Same name, different volumes, different subjects. Section 3 holds C library functions, which is why a C programmer asking about printf wants man 3 printf rather than the shell command.

Searching across the manual is available when you do not know a command's name:

man -k "list directory"

dir (1)              - list directory contents
ls (1)               - list directory contents

The number in parentheses is the section. This search depends on an index the system builds periodically, so it occasionally reports nothing on a freshly installed machine — a limitation of the index, not evidence the command does not exist.

8. When the Documentation and the Program Disagree

A realistic failure, and the reason §1 insisted on asking the local machine.

You read online that sort accepts --parallel to use several processors. On the server it fails:

sort --parallel=4 data.txt

sort: unrecognized option '--parallel=4'

Nothing is broken and nobody lied. The option exists in some versions of sort and not in the one installed here — a distribution decision about userland, exactly as Chapter 1.1 described. The local manual would have said so:

man sort

The habit this produces: when documentation and behaviour disagree, believe the machine, and check the machine's own manual. On shared engineering systems, where you may not control which versions are installed, this stops being a nicety. Module 21 returns to it as a portability discipline, and Part II makes the same check for tool versions part of every reproducible run.

9. Commercial Tools Keep Their Own Documentation

A note for later, offered now because it changes what you expect.

The habit in this chapter — ask the tool first — carries directly into semiconductor work, but the mechanics differ. Large commercial tools usually have no manual page at all. They typically offer a built-in help, often spelled with a single dash:

<tool> -help
<tool> -h

and ship their real documentation as separate vendor manuals, with a licensed documentation browser. Meanwhile, the scripts and wrappers your own team writes have exactly the documentation someone chose to write — which is why Module 21 has a chapter on giving a script a usage message, and Module 35 one on documenting a flow for the next engineer. The quality of the help you get from your team's automation is a decision your team makes.

10. The Routine, in Order

For an unfamiliar command:

1. type cmd — find out what kind of thing it is. A Bash builtin takes you to step 2; anything else to step 3. (Chapter 1.7.)
2. help cmd — for a builtin.
3. cmd --help — fastest answer for a program. Try -help and -h if that fails.
4. man cmd — the authoritative answer. NAME, then SYNOPSIS, then / to search for the option you care about.
5. man -k phrase — when you do not know the name at all.
6. SEE ALSO at the bottom of the page — for the tool that does the job better.

11. Check Your Understanding

Question 1. A synopsis reads cp [OPTION]... SOURCE DEST. How many operands are mandatory, and how do you know?

Question 2. What is wrong with typing ls [FILE], and why is the resulting behaviour hard to predict?

Question 3. man cd reports no manual entry, but cd plainly works. Give the correct explanation, and the command that documents it.

Question 4. help ls says no help topics match. What does that tell you about ls?

Question 5. You need the format of a configuration file, not a command of the same name. How do you ask man for it?

Question 6. A colleague insists an option exists because a web page says so, and your machine rejects it. Which source is authoritative for your machine, and which of Chapter 1.1's layers explains the difference?

12. Remember

• Ask the machine. Local documentation describes the version installed here; a web page describes somebody else's.
• --help is a fast convention, not a guarantee. Some programs reject it, some want -help, and a few treat it as a filename.
• man is the authoritative page. Read NAME, then SYNOPSIS, then search with /. Press q to leave.
• Synopsis notation is notation. Brackets mean optional, ... means repeatable, uppercase means a placeholder you replace, and a vertical bar means choose one. Never type the brackets.
• A mandatory operand is the one without brackets — which is how grep's synopsis tells you the pattern is required and comes first.
• help documents Bash's own builtins, and nothing else. help ls has nothing to say, and that silence is itself a fact about ls.
• "Where is this documented?" is the same question as "what kind of thing is this?" — which is the next chapter.
• When the manual and the behaviour disagree, believe the machine, then read the machine's manual to find out what it actually has.