Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 95 ยท Getting Started

Getting Help: man, --help and Learning Commands

Learn how to find out what any Linux command does - man pages, --help, the help builtin, type and command -v - and how to read usage syntax with brackets.

Nobody remembers every option of every command, and nobody is expected to. The real skill of a confident Linux user is finding the answer in ten seconds, on any machine, without internet access. The system documents itself: almost every command carries its own short help, many have a long manual page, and the shell can tell you where a command lives and what kind it is.

In this lesson you will learn the main places to look, in the order you should try them, and how to read the compact "usage" notation that all of them share. It follows The Shell: Commands, Arguments and Options, and it will make every later lesson easier because you can verify anything yourself.

Our sandbox has no manual pages and no pager (man and less are not installed). So the man examples below are read-only snippets, while --help, help, type and command -v run for real in the editor. On your own Linux machine all of them work, and man is the one you will use most.

The order to try

When you meet an unknown command, work from the cheapest source to the most detailed:

  1. type name or command -v name: does it exist, and what is it?
  2. name --help: a short summary of usage and options, printed straight to the terminal.
  3. help name: for Bash builtins, which have no manual page of their own.
  4. man name: the full manual, in a pager you scroll with the arrow keys and leave with q.
  5. Search: man -k word or apropos word when you do not know the command name.

Is the command there? type and command -v

Before reading help, make sure the command exists on this machine. command -v prints how the shell would run a name and sets a failing exit status when there is no such command. That makes it the right way to test for a tool inside a script, better than the older which.

Bash Does this command exist?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

command -v ls prints /bin/ls, the path of the program. For a builtin such as cd it prints just the name, because there is no file. The loop checks several tools at once and prints found or missing; this exact pattern appears at the top of many professional scripts to fail early when a dependency is absent. We discard the path with > /dev/null, because we only care about the exit status. The type command from the previous lesson gives the same information in a more talkative form.

--help: the quick summary

Nearly every GNU command understands --help and prints a usage summary. It is fast, always matches the installed version and needs no pager. Because the output is long, people often shorten it with head.

Bash Reading --help output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first line is the usage line, followed by a one-sentence description and then one line per option, usually listing both the short and the long spelling. Option help reads in the form -p, --parents: you can type either one.

Two conventions are worth knowing. --version prints the version, which matters when examples from the internet behave differently on your machine. And on some commands (git, docker, most modern tools) help is organized by subcommand: git help commit or git commit --help.

Bash Versions and subcommand help

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

sort --version shows the GNU coreutils release. This matters because macOS and BSD systems ship different tools with different options, and the first thing to check when a command misbehaves is which version you have. git help -a lists the available subcommands; we show only the first lines.

help: documentation for builtins

Builtins live inside Bash, so there is no separate program to run and no manual page of their own (the big bash(1) manual covers them all in one long page). Bash 5 does answer cd --help with the same text, but that is a Bash convenience that other shells lack, and not every builtin supports it. The portable, documented route is the help builtin.

Bash The help builtin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

help cd prints the full text for that builtin. help -d prints a one-line description and help -s just the short usage synopsis, which is often all you need. Run help without arguments to list all builtins.

Reading usage syntax

Help texts and manuals describe how to call a command in a compact notation. It looks cryptic at first but follows a few rules.

Notation Meaning
word Type it literally
[ ... ] Optional
... Can be repeated
a | b Choose one of a or b
<file> or FILE Replace with your own value
-n NUM Option that takes a value

Take the first line of mkdir --help as an example:

TEXT
Usage: mkdir [OPTION]... DIRECTORY...

It says: mkdir, then zero or more options, then one or more directory names. Compare with cp:

TEXT
Usage: cp [OPTION]... [-T] SOURCE DEST
  or:  cp [OPTION]... SOURCE... DIRECTORY
  or:  cp [OPTION]... -t DIRECTORY SOURCE...

A command can have several forms. Here copy one file to a destination, copy several sources into a directory, or name the target directory first with -t. With that notation in mind, you can read the help of an unknown tool without ever having seen it. Capitalized words such as SOURCE, DEST and DIRECTORY are placeholders for values you provide.

man: the full manual

The manual is organized in numbered sections. You will mostly use section 1 (commands), 5 (file formats such as passwd), 7 (overviews) and 8 (system administration); sections 2 and 3 document system calls and library functions for C programmers. A name followed by the section in parentheses, as in crontab(5), tells you which page is meant, because crontab exists both as a command and as a file format.

This block is read-only: the sandbox has no man.

CONSOLE
$ man ls                 # the manual page for ls
$ man 5 passwd           # section 5: the /etc/passwd file format
$ man -k copy            # search page titles and summaries for "copy"
$ apropos "disk usage"   # the same search, other spelling
$ man -f printf          # which pages are called printf?

Inside the pager (the viewer called less), these keys do the work:

Key Action
Space / b Page down / page up
/text then Enter Search forward; n for the next match, N for the previous
g / G Jump to the start / end
q Quit

A manual page has a standard layout: NAME, SYNOPSIS (the usage notation), DESCRIPTION, OPTIONS, EXAMPLES (when the authors wrote any), EXIT STATUS, and SEE ALSO, which links related commands. Searching with / for an option such as /--recursive is the fastest way to find what you need in a long page.

When you do not know the name

Sometimes you know what you want to do but not which command does it. Try these approaches:

  • man -k keyword or apropos keyword searches the one-line descriptions of all installed pages.
  • Tab completion at a real prompt: type ls and press Tab twice to list every command beginning with those letters.
  • compgen -c lists all command names the shell knows; it is a builtin, so it works even here.
  • Look at related commands in the SEE ALSO section of a page you do know.
  • Search online or ask a colleague, then verify with the local --help, since the exact options vary between versions.
Bash Searching command names with compgen

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first part lists the checksum tools (sha1sum, sha224sum and so on), which you could then look up with --help. The second part avoids printing a machine-specific number and prints a stable sentence instead; writing examples that do not depend on the machine is a good habit for scripts too.

Reading help effectively

  • Start with the SYNOPSIS or usage line, then scan the options for the verb you want ("recursive", "force", "verbose").
  • Look for EXAMPLES at the end of a manual page; they are the quickest route to a working command.
  • Check the exit status section when you plan to use the command in if or &&.
  • When an option does not work, run --version: you may be on a BSD or an older release.
  • Prefer the long option in scripts; --recursive documents itself, -r does not.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command tells you, inside a script, whether a tool is installed?

    command -v prints how the name would run and returns a failing status when it does not exist, so it works well in if tests.
  2. 2. Where do you find documentation for a Bash builtin such as cd?

    Builtins are part of the shell, so Bash gives them the help builtin. type only tells you the kind of command, not how to use it.
  3. 3. In the usage line Usage: mkdir [OPTION]... DIRECTORY..., what is required?

    Square brackets mark optional parts. DIRECTORY... is not in brackets and may repeat, so one or more directories are required.
  4. 4. What does man -k copy do?

    -k (same as apropos) looks for a keyword in the names and descriptions of installed manual pages.
  5. 5. Why does crontab(5) carry a number?

    Manual sections separate pages with the same name; section 1 is the command, section 5 the file format.

Summary

  • Try type or command -v first to confirm a command exists and what kind it is.
  • command --help gives a quick summary, --version shows which release you have, and builtins use help name.
  • man name opens the full manual in a pager (/ searches, q quits); man -k or apropos finds commands by keyword.
  • Usage lines use [optional], ... for repetition and capital placeholders; learn to read them and you can read any tool.
  • Manual pages are grouped in sections, written as name(section).
  • Our sandbox has no man or less, so those parts are read-only here.

Next: The Linux Filesystem