Read
SettingsMount machine

Module 1 · First steps in the terminal

Getting help: --help and reading usage lines

No manual pages on this machine, and none on many servers either: how to ask a command to describe itself, and how to decode the brackets, dots and capitals of a usage line.

Lesson 7 of 10015 min

What you will learn

  • Get a command's built-in help with `--help`.
  • Read a usage line: `[optional]`, `REQUIRED`, `...`.
  • Find a specific option without reading everything.

Nobody remembers every option of every command. What experienced users remember is how to look them up in two seconds. On a full Linux distribution the main tool is man (lesson 7 of most courses teaches man ls). The practice machine, like many containers, routers and rescue systems, has no manual pages at all. What it does have — what almost every command has — is --help.

~% mkdir --help
BusyBox v1.28.4 (2018-06-02 20:33:24 EST) multi-call binary.

Usage: mkdir [OPTIONS] DIRECTORY...

Create DIRECTORY

	-m MODE	Mode
	-p	No error if exists; make parent directories as needed

Reading the usage line

The line starting with Usage: is a compact grammar of the command, and it follows conventions shared by nearly all Unix software:

NotationMeansIn `mkdir [OPTIONS] DIRECTORY...`
[something]Optional; you may leave it out.Options are not required.
SOMETHINGA placeholder in capitals: replace with your own value.DIRECTORY becomes docs.
...The previous item may repeat.You can name several directories at once.
a|bOne or the other.-R,-r in cp --help: two spellings of one option.
-x ARGAn option that takes a value.-m MODE needs a mode after it: -m 700.

So mkdir [OPTIONS] DIRECTORY... reads: "optionally some options, then one or more directory names". mkdir docs is valid. mkdir -p a/b/c is valid. mkdir alone is not — a required item is missing — and the command will print this very usage text to tell you so. That is the other time you will see it: whenever you call a command wrongly, the usage line is the error message.

Finding one option fast

Help texts can be long — ls --help here is thirty lines, on GNU systems two hundred. You rarely want to read them; you want the one line about dates, or recursion, or overwriting. Skim the left column for the option letter you half-remember, or for a keyword in the description. From module 3 you will pipe help into grep to search it: ls --help 2>&1 | grep -i sort. Until then, skim.

~% touch --help
BusyBox v1.28.4 (2018-06-02 20:33:24 EST) multi-call binary.

Usage: touch [-c] [-d DATE] [-t DATE] [-r FILE] FILE...

Update the last-modified date on the given FILE[s]

	-c	Don't create files
	-d DT	Date/time to use
	-t DT	Date/time to use
	-r FILE	Use FILE's date/time
~% touch -d 2020-01-01 old.txt
~% ls -l old.txt
-rw-r--r--    1 root     root             0 Jan  1  2020 old.txt

Other places help lives

On a full system, man COMMAND opens the manual page, COMMAND --help prints the short form, and info or /usr/share/doc hold longer documents. Here, busybox --list prints the names of all 265 commands available, and busybox alone describes the project. A good habit regardless of system: when a command surprises you, ask it for --help before asking a search engine. The answer is specific to the exact version in front of you, which a web page never is.

Commands in this lesson

CommandWhat it does
COMMAND --helpBuilt-in usage text and option list.
busybox --listEvery command this BusyBox provides.
type NAMEIs NAME a builtin (no `--help`) or a program?
touch -d DATE FILECreate or stamp FILE with the given date (found via `--help`).
mkdir -p DIR/SUBCreate a directory and any missing parents (found via `--help`).

Quiz

  1. In `Usage: mv [-fin] SOURCE DEST`, what do the brackets mean?

    • You must type the brackets
    • The options inside are optional
    • Those options are deprecated

  2. What does `DIRECTORY...` mean in a usage line?

    • A directory whose name ends in three dots
    • One or more directory names
    • The directory is optional

  3. Why does `cd --help` fail on the practice machine?

    • `cd` is a shell builtin and has no help text
    • `--help` is not supported by BusyBox
    • You need to be root

  4. You run `mkdir` with no arguments. What happens?

    • It creates a directory with a random name
    • It prints its usage text, because a required argument is missing
    • It creates a directory called `DIRECTORY`

  5. Which is the correct way to get help for `ls` here?

    • `man ls`
    • `ls -l --help`
    • `ls --help`

Practice

  1. Show the built-in help of `ls`.

  2. Read `touch --help` to find the option that sets a date, then create /root/lab/l7/old.txt with the date 2020-01-01. `ls -l` should show `Jan 1 2020`.

  3. Read `mkdir --help` to find the option that creates missing parent directories, then create /root/lab/l7/x/y/z with a single command.

Open this lesson in the app to do the tasks in a real Linux machine and have them checked.