Getting help

Where do you look first?

Nobody remembers every option of every command. Experienced people look things up all the time, and the fastest place to look is the command itself. Almost every GNU command on Linux answers --help with a short summary, and most have a full manual page you open with man.

Try ls --help before reaching for a search engine. It describes the version of ls installed on the machine in front of you, which matters on servers where the tools may be older or different from the ones a website describes. A web page can be about another system; the built-in help can’t be.

What does --help show?

--help prints a usage line, a one-line description and the options, then stops. On real Linux, ls --help is long, around a hundred lines, so you often scroll back or search it. The practice terminal keeps the help short and lists only what it supports, as in ls --help printing eight options from -l to -r.

Read the options list for a word that matches your need: “size”, “newest”, “hidden”. The left side shows the short option, and real help often adds a long form beside it, such as -a, --all. Both mean the same. Long ones are easier to read in scripts; short ones are quicker to type and can be combined, as in -lhS.

$ ls --help
ls: Lists what is in a folder.

Options:
  -l        long format: permissions, owner, size and date
  -a        all, including hidden files that start with a dot
  -h        human-readable sizes such as 4.0K
  -R        recursive: every folder inside, too
  -t        newest first
  -S        largest first
  -1        one name per line
  -r        reverse the order

How do you read a usage line?

Real help and manual pages start with a usage line such as Usage: tail [OPTION]... [FILE].... It’s a small grammar. Words in capitals are placeholders you replace with your own values. Square brackets mean optional. Three dots mean you can give more than one. So tail takes any number of options, then any number of files, and works even with none of either (it then reads from a pipe, which a later lesson covers).

Options that need a value show it next to them, such as -n, --lines=NUM. You can write that as -n 4, -n4 or --lines=4. When a value is missing or isn’t the right kind, you get an error like head: invalid number of lines. Some usage lines show choices separated by |, meaning pick one.

Usage: tail [OPTION]... [FILE]...
  -n, --lines=NUM   output the last NUM lines

How do you use man?

man ls opens the manual page for ls. On a real system it opens in the same viewer as less: Space pages down, b goes back, / followed by a word searches, n jumps to the next match, q quits. Manual pages have standard sections: NAME, SYNOPSIS (the usage lines), DESCRIPTION (every option), and often EXAMPLES and SEE ALSO near the end.

The fastest way to use one is to search. In man ls, type /size and press Enter to land on the options that mention size. Many people jump straight to EXAMPLES with /EXAMPLES. In the practice terminal man prints the same short help as --help, since it has no scrolling viewer.

If you know what you want to do but not the command, man -k word (also called apropos) searches every manual page’s one-line summary, so man -k compress lists gzip, zip, tar and friends. The practice terminal doesn’t have it; a real Linux or Mac does.

What is help, and why does man cd fail on real systems?

Some commands aren’t separate programs. cd, export, alias, source and history are built into bash itself, because they need to change the shell you’re typing into. Built-ins don’t have their own manual pages, so on a typical Linux system man cd says No manual entry for cd or opens the giant bash manual.

Bash has its own command for them: help cd prints a summary of cd and its options, and help on its own lists every built-in. To tell what kind of command something is, type cd says cd is a shell builtin, here and on a real system. The practice terminal answers help, man and --help for every command it knows, built-in or not, and help with no name lists all of them.

How do error messages help you?

Error messages follow a pattern: the program that complained, then what it complained about, then why. bash: tial: command not found comes from bash, not from tail, and means no program has that name, so check the spelling. head: invalid number of lines comes from head, which ran and objected to its value. It also quotes the bad value, 'five', so you can see exactly what it was given.

An unrecognised option on Linux says something like ls: unrecognized option '--biggest-first' followed by Try 'ls --help' for more information. That second line is the tool telling you where to look. The practice terminal prints the same message for unknown long options, though it still ignores some unknown short ones, such as ls -z.

When an error is confusing, copy the first line exactly into a search. Errors are standard text, so other people have usually met the same one. Leave out your own file names when you search.

$ tial -n 3 repairs.log
bash: tial: command not found
$ head -n five repairs.log
head: invalid number of lines: 'five'

How is help different on a Mac?

Mac commands come from BSD, and many don’t accept --help at all. ls --help on a Mac prints an error such as unrecognized option or illegal option, then a short usage line. Use man ls there instead; Mac manual pages are complete and describe the Mac version, including options that differ from Linux, such as sed -i ''.

That difference is a common reason a command copied from a Linux tutorial fails on a Mac. When in doubt, read the manual on the machine where the command will run.

What do AI tools get wrong here?

AI assistants sometimes invent options that sound right, such as ls --biggest-first or tail --newest. They look plausible, and the command fails. When a suggested option is new to you, check it with --help or man before relying on it, especially in a command that deletes or overwrites anything.

They also mix GNU and BSD options, or describe a newer version of a tool than the one on your server. If the help on your machine doesn’t list an option, the help wins. Paste the exact error back to the assistant along with the output of --help, and its next suggestion is far more likely to work.

Field notes

• Most commands print a summary of their options when you add --help.
• man opens the full manual page; press q to leave it.
• In a usage line, capital words are placeholders and square brackets mean optional.
• Search a manual page by typing / and a word, then Enter.

Easy to get wrong

Options are case-sensitive. On real Linux -s shows block sizes next to each name, while -S sorts largest first.

cd is built into bash, so most systems have no separate manual page for it. help covers built-ins.

The error names the program and the problem. Running the same line again gives the same result.

Questions people ask

How do I get out of man?

Press q. The same key leaves less. Ctrl+C usually doesn’t close either of them.

What is tldr?

tldr is a separate tool you can install that shows a few short, common examples for each command. It’s handy alongside man, but it isn’t on most servers and the practice terminal doesn’t have it.

Why does --help scroll off the screen?

Real help texts are long. Pipe it into less, as in ls --help | less, so you can page through and search. The Pipes lesson explains |.

Is the help in this practice terminal complete?

No. It lists only the options this terminal supports. A real Linux system lists many more, and the manual on that machine is the final word.