Reading manuals and --help

Why this matters

Most commands have more options than anyone can remember. A beginner who guesses a flag gets an error, guesses another one, and after twenty minutes still does not know whether the command can do the job at all. A person who knows where the documentation is gets the answer in a minute.

The documentation has one more advantage. It comes with the program on your machine, so it describes the version you actually run. A tutorial written for a different version can list flags that your version does not have.

This lesson covers three skills. The first is reading the sections of a manual page. The second is finding a flag by searching for what you want to do. The third is reading examples before options, because an example usually teaches a command faster than a list of flags. Lesson four explains how flags are written, so this lesson does not repeat that.

The outputs in this lesson come from a Linux system (Ubuntu 26.04) that uses GNU grep 3.12 and ls from uutils coreutils 0.8.0, a rewrite of the standard file commands in the Rust language. Your output may differ in wording, and the ls options may print different error text. The method works the same way.

Where the documentation lives

There are three places to look. Each one is written by the people who maintain the program.

• The help text is printed by the program when you run it with --help. It is short, usually one screen, and lists every option with a one-line explanation.
• The manual page, called a man page, is the long reference. You open it with the man command, for example man ls. Most programs on Linux and macOS have one.
• The shell's built-in help covers commands that belong to the shell itself. The shell is the program that reads what you type and runs it. Commands built into it are called builtins. cd is the most common builtin, and it has no manual page of its own. The mistakes section below shows what happens when you look for one.

A fourth tool helps when you do not know the command's name. man -k (also called apropos) searches the one-line summary of every manual page on the machine. You will use it in the third worked example.

The shape of a manual page

Every manual page is split into sections with names in capital letters. The names are the same across pages, so once you know the layout, you can jump straight to the part you need. Here are the headings of the grep page, printed with a command that shows only the heading lines:

man grep | grep -E '^[A-Z][A-Z ]+$'

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
REGULAR EXPRESSIONS
EXIT STATUS
ENVIRONMENT
NOTES
COPYRIGHT
BUGS
EXAMPLE
SEE ALSO

The next sections go through the ones you will use most.

NAME

The NAME section is one line. It says what the command is for, and it confirms that you opened the page you meant. The cp page starts like this:

NAME
       cp - copy files and directories

If the name line does not match what you wanted, stop there. You probably typed a name that belongs to a different program.

SYNOPSIS

The SYNOPSIS section shows the shapes a command can take. Square brackets mean a part is optional, and ... means the part can repeat. The grep page has three shapes:

SYNOPSIS
       grep [OPTION]... PATTERNS [FILE]...
       grep [OPTION]... -e PATTERNS ... [FILE]...
       grep [OPTION]... -f PATTERN_FILE ... [FILE]...

Read the first line in plain words: options come first, then a pattern (the text to search for), then zero or more file names. The second and third lines show two other ways to give the pattern. The third one gives the patterns in a file named by PATTERN_FILE, so you can search for a long list of words without typing each one.

If you see a shape you do not recognise, the DESCRIPTION section explains it in prose.

DESCRIPTION

DESCRIPTION says what the program does and how it behaves. The first sentence is usually the best summary. For cp:

DESCRIPTION
       Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

Read the DESCRIPTION before the options when you are unsure what a command does. It tells you the big picture, and the options then make sense.

OPTIONS

OPTIONS lists every option with a short explanation. It is the longest section on most pages, and you should search it rather than read it from top to bottom. Searching is covered in lesson one, and the search keys work the same way in a man page.

When you cannot use the viewer, send the page into grep through a pipe, which passes one command's output to the next command, and search for the word you want. This finds the entry for the --ignore-case option and prints the two lines after it:

man grep | grep -n -A2 'i, --ignore-case'

67:       -i, --ignore-case
68-              Ignore  case  distinctions  in  patterns  and input data, so that
69-              characters that differ only in case match each other.

The number at the start of each line is its line number in the page. -A2 asks for two lines after each match. You can use any number.

EXIT STATUS

Every program ends with a small number called its exit status. It tells you whether the command worked. The convention is 0 for success and any other number for a problem, and each program defines its own meanings. The EXIT STATUS section lists them. The start of the grep page's section says:

EXIT STATUS
       Normally the exit status is 0 if a line is selected, 1 if no lines
       were selected, and 2 if an error occurred.

So grep returns 1 when nothing matched. That is not an error in the sense of a broken command, but a script can tell the two cases apart. Lesson seven uses exit status in scripts.

The sections you will meet less often

• ENVIRONMENT lists the environment variables the program reads. Lesson five explains what those are.
• BUGS lists known problems. Read it when a behaviour surprises you, because it may already be a known issue.
• SEE ALSO names related pages. Use it to find the sibling command, such as the sed and awk pages that the grep page names.
• AUTHOR, COPYRIGHT and REPORTING BUGS are about who wrote the program and where to report problems. You can skip them when you are working.
• VERSION says which version the page describes. Compare it with your installed version when a flag from the page does not work. The footer of the grep page shows the version too: GNU grep 3.12.

Pages do not all have the same sections

The headings above are common, but a page only has the sections its author wrote. Four pages on the same machine show the differences:

If you look for an EXAMPLES heading and it is not there, do not assume the page has no examples. Check the headings list first, then search the page for the flag you want.

Section numbers

Some names exist on more than one page. The command printf has a manual page for the shell command and another for a function in the C programming language. Each page has a section number in brackets. Two examples:

man printf
man 3 printf

The first command shows the page for the command, which is section 1, and its header reads PRINTF(1). The second command asks for section 3, the C library function, and its header reads printf(3) with the title "Library Functions Manual". Section 1 covers commands you type, section 3 covers C library functions, and section 5 covers file formats. The man command shows the first match it finds, which is the lowest section number.

To see every section that has a page with a given name, use man -f:

man -f passwd

passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands
passwd (5)           - the password file

The page for the password file is in section 5, so man 5 passwd shows it. A plain man passwd would show the command in section 1 instead.

Finding a flag without guessing

Guessing works like this: you try -s, get an error, try -S, get an error, and so on. Searching works like this: you describe the result you want in plain words, and the documentation gives you the flag. Use these four steps.

1. Search the help text for a word that describes what you want, not the flag name.
2. Read the line above or below each hit. The flag and its description sit next to each other.
3. Check the same word on the manual page, where the explanation is longer.
4. Try the flag on a small test folder, then read the output before you use it on real files.

Use the next three examples to practise the method. Each one is harder than the one before.

Example one: sort files by size

You want ls to list the biggest files first. Start by making a small test folder with three files of different sizes:

mkdir lab
cd lab
printf 'hi\n' > small.txt
printf 'hello world\n' > medium.txt
head -c 3000 /dev/zero > big.bin

The head -c 3000 /dev/zero command writes 3000 zero bytes into big.bin. You do not need to understand it yet. The > symbol sends a command's output into a file, and the working with files lesson covers it.

Now search the help for a word that describes the result. The word "size" matches many lines, so start with "largest":

ls --help | grep -B1 'largest'

  -S
          Sort by file size, largest first.

The flag is the line above the description, so it is -S. Run it:

ls -S

big.bin
medium.txt
small.txt

The biggest file comes first. The search word mattered. "size" matched several lines of the help, including options for printing sizes, and you would have had to read each one. "largest" matched the one line that describes the sort.

Example two: list only the names of matching files

You want grep to print only the names of files that contain a word, not the matching lines. Make a file to search first:

printf 'apple\nbanana\ncherry\n' > fruit.txt

Search the help for the result you want, which is names of files:

grep --help | grep 'names of'

  -L, --files-without-match  print only names of FILEs with no selected lines
  -l, --files-with-matches  print only names of FILEs with selected lines

Two lines match, and they are a pair. The -l option prints the names of files that have a match. The -L option prints the names of files that have no match. The help text makes the difference clear, so you do not need to guess which one you want.

Now check the manual page for the longer explanation of -l:

man grep | grep -n -A3 'files-with-matches'

The manual says -l suppresses the normal output and prints the name of each input file that would have printed a line. Then run it on the three files:

grep -l an *.txt

fruit.txt

Only fruit.txt contains an, because banana has it. The other two files do not, so they are not printed.

Example three: find a command when you know only the task

Sometimes you do not know the name of the command at all. You know the task: you want to count the bytes in a file. Start with the task, not the command. Search the one-line summaries with man -k, using a phrase from the task:

man -k 'byte count' | head -3

gnuwc (1)            - print newline, word, and byte counts for each file
rust-wc (1)          - Print newline, word, and byte counts for each FILE, an...
wc (1)               - Print newline, word, and byte counts for each FILE, an...

This machine has three entries for word counting under different names. Their descriptions match, so the name you type is the only difference. wc is the plain name, and it is the one most people type.

The wc page has no EXAMPLES section, so go to its OPTIONS. Search the help text for the word "newline counts" to find the option for lines:

wc --help | grep 'newline counts'

  -l, --lines            print the newline counts

Then run it on the test file:

wc -l fruit.txt

3 fruit.txt

The count is 3 because the file has three lines. Each line ends with a newline character, which is the invisible character that marks the end of a line, so the count of newlines equals the count of lines.

Read the examples first

An example shows a command in use, with the output it gives. Read it in this order: the command, then the output, then the text under it that explains why the command is written that way. Skipping to the options before reading the example makes the options harder to understand.

The grep page has one example in its EXAMPLE section. It reads like this:

EXAMPLE
       The following example outputs the location and contents of any line
       containing "f" and ending in ".c", within all files in the current
       directory whose names contain "g" and end in ".h". The -n option
       outputs line numbers, the -- argument treats expansions of "*g*.h"
       starting with "-" as file names not options, and the empty file
       /dev/null causes file names to be output even if only one file name
       happens to be of the form "*g*.h".
 
         $ grep -n -- 'f.*\.c$' *g*.h /dev/null
         argmatch.h:1:/* definitions and prototypes for argmatch.c

Look at what the explanation does. It says why /dev/null is at the end. That file is always empty, so it never matches, but it makes grep print file names even when only one file matches the *g*.h pattern. The explanation also says why the -- appears. You can read this part without knowing those details, and the example tells you what each piece is for.

The --help text of grep also contains one short example, right after its usage line:

Example: grep -i 'hello world' menu.h main.c

Short help often has one example like this. It is the quickest way to see the usual shape of a command.

Longer pages can have many examples. The find page has an EXAMPLES section with several entries. Each entry gives a heading, a short paragraph on what the command does, the command, and then a note on its limits. The first entry removes files named core under /tmp. The page then explains that its simple version breaks on file names with spaces, and gives a safer version. Reading that note is the reason to read the whole entry. Run that first command in a folder you care about and it deletes every file named core below that folder. The habit to build is this. Read an example. Copy it into your test folder, not into a folder with real work in it. Change one word, run it again, and watch what changes.

Common mistakes

Looking up a shell builtin with man

Run man cd and you get this:

No manual entry for cd

The cd command is a builtin, so it is part of the shell. There is no separate file for man to open. Ask the shell instead:

help cd

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

To confirm that a name is a builtin, use type:

type cd

cd is a shell builtin

The full shell manual is the bash page, and it has a section named SHELL BUILTIN COMMANDS. If you use zsh, which is the default shell on recent macOS versions, help cd may not work. The builtins of zsh are described on the zshbuiltins page, which you open with man zshbuiltins.

Expecting -h to print help

The ls command prints help with --help. Its -h option does something else. Look at what happens when you run ls -h in the test folder:

ls -h

big.bin
fruit.txt
medium.txt
small.txt

The -h option is --human-readable. It changes how file sizes are written, and it only matters when the sizes are shown. Add the long listing and the sizes appear in units such as K for kilobytes:

ls -lh

total 16K
-rw-r--r-- 1 chiranjeet chiranjeet 3.0K Nov  5 12:34 big.bin
-rw-r--r-- 1 chiranjeet chiranjeet   20 Nov  5 12:34 fruit.txt
-rw-r--r-- 1 chiranjeet chiranjeet   12 Nov  5 12:34 medium.txt
-rw-r--r-- 1 chiranjeet chiranjeet    3 Nov  5 12:34 small.txt

Your owner name and dates will differ. The lesson for the mistake is the size column: 3.0K is big.bin written in human units, where the plain 3000 would have been bytes.

Guessing a flag spelling

Suppose you type --colr instead of --color:

grep --colr x fruit.txt

grep: unrecognized option '--colr'
Usage: grep [OPTION]... PATTERNS [FILE]...
Try 'grep --help' for more information.

The message names the bad option, and it tells you the next step: run --help. Do that and search for the word you want:

grep --help | grep -A1 'color\b' | head -3

      --color[=WHEN],
      --colour[=WHEN]       use markers to highlight the matching strings;

The correct spelling is --color. The --colour line is the same option with the British spelling.

Each program words its errors differently. The same mistake in ls on this system prints:

error: unexpected argument '-z' found
 
  tip: to pass '-z' as a value, use '-- -z'
 
Usage: ls [OPTION]... [FILE]...
 
For more information, try '--help'.

This message is longer, but the last line gives the same next step.

If a flag from a web page is rejected even after you find it in your help text, check the version. Run grep --version and compare it with the version on the page you read.

Searching the summaries with a phrase that is not in them

man -k searches the words of the one-line summaries. The phrase "word count" does not appear in the wc summary, which says "newline, word, and byte counts", so this search finds nothing:

man -k 'word count'

word count: nothing appropriate.

Use the words the summary really uses, such as byte count, which found wc in the third example. When you get no result, try a shorter word from your task.

Practice

Each exercise is followed by its answer. Try the exercise on your own machine first.

Exercise 1. Run ls --help and find the option that makes ls show hidden files. A hidden file is one whose name starts with a dot. Then run ls with that option in your test folder, and say what the two extra entries are.

Show the answer

The option is -a, also written --all. Its help line reads "Do not ignore hidden files (files with names that start with '.')." Running ls -a in a folder shows two extra entries, . and ... The first is the folder itself and the second is the folder above it. Hidden files, such as a file named .bashrc, appear in the same list when they exist.

Exercise 2. Which section of the manual describes the format of the password file? Find the page with man -f passwd, then open it.

Show the answer

Section 5. The man -f passwd output lists passwd (5) as "the password file", so the command is man 5 passwd. The header of that page reads PASSWD(5) with the title "File Formats and Configuration". A plain man passwd opens the command in section 1 instead.

Exercise 3. You want to find the command that counts bytes in a file, and you cannot remember its name. Use man -k with the phrase "byte count" and name the command you would use.

Show the answer

Use wc. The summary reads "Print newline, word, and byte counts for each FILE". Run man -k 'byte count' and look for the line that starts with wc (1). Its description also explains that wc counts lines, words and bytes, and one option picks each count, so wc -l gives only the lines.

Exercise 4. Run grep -q zebra fruit.txt and then echo $?. The -q option makes grep print nothing and only set its exit status, and $? holds the exit status of the last command. What number do you see, and what does it mean?

Show the answer

The output is 1. The EXIT STATUS section says 1 means no lines were selected, so zebra is not in fruit.txt. The number 0 would mean a match was found, and 2 would mean an error, such as a file that does not exist. Run grep zebra nope.txt to see the 2 case, which prints grep: nope.txt: No such file or directory before the exit status.

Exercise 5. The command grep --colr x fruit.txt fails. Use the help text to find the correct option, then run grep --color=auto an fruit.txt and say which line it prints.

Show the answer

The correct option is --color. Search with grep --help | grep -A1 'color\b' to find it. The command grep --color=auto an fruit.txt prints banana, the only line in fruit.txt that contains an. The auto part tells grep to use colour only when the output goes to a terminal. Here the output goes to the lesson's test folder rather than a terminal, so the line prints as plain text.

Summary

• A man page uses the same section names on every page, but a page only has the sections its author wrote, so check the headings first.
• SYNOPSIS shows the shapes of a command, DESCRIPTION says what it does, OPTIONS lists the flags, and EXIT STATUS lists the result codes.
• Search the help text or the OPTIONS section with a word that describes the result you want, then read the line next to each hit.
• Use man -k with words from a summary line, and man -f to see every section that has a page with a given name.
• Read the example and the text under it before you copy a command, and try it first in a test folder.
• Shell builtins such as cd are documented by help and by the shell's own manual, not by man.