Commands, options, arguments and help

In a folder that holds a file called -n, the command cat * prints one numbered line instead of the contents of both files, and nothing warns you: cat read the file’s name as its “number the lines” option. Knowing how a command line splits into a name, options and operands is what lets you see that coming.

Below you will take command lines apart into their pieces, watch a glob turn a file name into an option and fix it with --, follow the order in which Bash decides whether a name is an alias, a keyword, a function, a builtin or a program, and find the right help for each kind of command.

A command line is a name, options, option-arguments and operands

Take head -n 2 drinks.txt. The first word, head, is the command name. -n is an optionoption: A word that starts with a dash and changes how a command behaves, such as -n for head. One-letter options without values can usually be grouped behind one dash, as in cat -ne., 2 is its option-argument, the value the option needs, and drinks.txt is an operandoperand: A word after a command's options that the command works on, usually a file name. After --, every word is an operand, even one that starts with a dash., the thing the command works on. POSIX.1-2024’s utility syntax guidelines describe this shape for standard utilities, and most other programs follow it.

The guidelines also allow one-letter options without arguments to be grouped behind a single dash, so cat -ne means cat -n -e. Here are both forms on a three-line file, with -n numbering the lines and -e marking each line’s end with $:

from session import run

# One small file, then the same options written apart and grouped behind one dash.
run("""
printf 'tea\\ncoffee\\nwater\\n' > drinks.txt
head -n 2 drinks.txt
cat -n -e drinks.txt
cat -ne drinks.txt
""")

$ printf 'tea\ncoffee\nwater\n' > drinks.txt
$ head -n 2 drinks.txt
tea
coffee
$ cat -n -e drinks.txt
     1	tea$
     2	coffee$
     3	water$
$ cat -ne drinks.txt
     1	tea$
     2	coffee$
     3	water$

The two cat commands print exactly the same lines, because grouping changes only how the options are written.

Many programs also accept long options, whole words after two dashes such as --help or --color=never. They are a convention of GNU and other projects rather than one of the POSIX guidelines, so a long option that works on Linux may be missing from the macOS version of the same command, as the last section of this lesson shows with ls --help. When a script must run on both, prefer the short options that POSIX describes for the utility.

Two dashes end the options, so a file named like an option stays a file

The shell expands * into the names of the files in the folder before the command starts, and the command cannot tell a word that came from a file name from one you typed. POSIX guideline 10 gives the cure: the first -- that is not an option-argument marks the end of the options, and every word after it is an operand, even one that begins with a dash. Watch a file called -n change what cat * does:

from session import run

# A file whose name starts with a dash, and a glob that hands that name to cat.
run("""
printf 'hello\\n' > -n
printf 'world\\n' > notes.txt
ls
cat *
cat -- *
cat ./*
rm -- -n
ls
""")

$ printf 'hello\n' > -n
$ printf 'world\n' > notes.txt
$ ls
-n
notes.txt
$ cat *
     1	world
$ cat -- *
hello
world
$ cat ./*
hello
world
$ rm -- -n
$ ls
notes.txt

cat * became cat -n notes.txt, so cat numbered the one file it was given and never printed “hello”. Both fixes work: cat -- * ends the options before the file names, and cat ./* makes every name start with ./, which is not a dash. Even removing the file needs the same care, which is why the session uses rm -- -n. ShellCheck warns about a bare * in arguments for exactly this reason (SC2035).

The type builtin shows what a name means, and command tells whether it exists

The same word can mean several things. if is a keyword of the shell’s language, echo is a builtinbuiltin: A command that is part of the shell itself rather than a separate program, such as cd, echo or type in Bash. help NAME documents it. compiled into Bash and also a program in /bin, ls is only a program, and you can make a name into a function or an alias yourself. Bash’s reference manual gives the order in which it decides: aliases and keywords are recognised while the line is read, then come functions, then builtins, then a search of the folders in PATH, remembered in a hash table. Follow one name down that order:

type -a NAME prints every meaning a name has, in that order, and command -v NAME prints how the name would run, or nothing with status 1 when it does not exist. Here they are after a function and an alias have been defined:

from session import run

# What kind of command is each name? A function and an alias are defined first, as you might in a terminal.
run("""
greet() { echo "hi, $1"; }
alias ll='ls -l'
type -a echo printf ls
type if greet ll
command -v ls
!command -v nosuchcmd
command -v nosuchcmd || echo missing
""")

$ greet() { echo "hi, $1"; }
$ alias ll='ls -l'
$ type -a echo printf ls
echo is a shell builtin
echo is /bin/echo
printf is a shell builtin
printf is /usr/bin/printf
ls is /bin/ls
$ type if greet ll
if is a shell keyword
greet is a function
greet ()
{
    echo "hi, $1"
}
ll is aliased to `ls -l'
$ command -v ls
/bin/ls
$ command -v nosuchcmd
[exit status 1]
$ command -v nosuchcmd || echo missing
missing

type -a found echo twice, as a builtin and as /bin/echo; typing echo runs the builtin because builtins come first. For nosuchcmd, command -v printed nothing and ended with status 1, which is why command -v nosuchcmd || echo missing printed “missing”. In a script, command -v is the portable way to ask whether a command exists, because POSIX defines it for every shell.

PATH itself is a list of folders separated by colons, searched from left to right, and the first folder that holds an executable file with the name wins. Bash remembers each program it finds in its hash table, so after you install a new copy of a program earlier in PATH, an open terminal may keep running the old one until you type hash -r or open a new terminal. type tells you when that happens: it answers “ls is hashed (/bin/ls)” for a remembered name.

help, man and the help option each document a different kind of command

Where you find documentation depends on what kind of command you have. Builtins are documented inside Bash, by the help builtin. Programs installed on the system usually have a manual page, which man shows and man -w locates. Many programs, including Bash’s builtins from Bash 4.4 on, also answer --help with a short usage line, but not all of them: macOS’s own ls rejects the option.

from session import run

# Three ways to read about a command: help for builtins, --help for many programs, man for installed manual pages.
run("""
help type | head -n 2
printf --help 2>&1 | head -n 1
!ls --help
man -w ls
""")

$ help type | head -n 2
type: type [-afptP] name [name ...]
    Display information about command type.
$ printf --help 2>&1 | head -n 1
printf: printf [-v var] format [arguments]
$ ls --help
ls: unrecognized option `--help'
usage: ls [-@ABCFGHILOPRSTUWXabcdefghiklmnopqrstuvwxy1%,] [--color=when] [-D format] [file ...]
[exit status 1]
$ man -w ls
/usr/share/man/man1/ls.1

Run type -a first when you are unsure: if it says “shell builtin”, use help; if it prints a path, use man.

Practise: read command lines and find their help

Each question gives a command line or a name and asks what Bash makes of it; the wrong answers come from the mistakes above, and each explains itself:

Interview questions

Warm-up (fresher to 2–5 years): what do -- and command -v do in a script?

-- marks the end of a command’s options: every word after it is an operand, even one that starts with a dash. That protects commands such as rm -- "$file" or cat -- * from file names like -n or -rf, which would otherwise be read as options. command -v NAME prints how the shell would run NAME, a path for a program, the bare name for a builtin or function, or the definition for an alias, and returns status 1 with no output when NAME does not exist. Because POSIX defines it, it is the portable test for “is this command installed?” in a script: if command -v jq >/dev/null; then …. It is preferred to which, a separate program that POSIX does not define.

Two harder questions follow, about a dangerous glob and about a command that runs the wrong program. Work out your answer before you open each first step:

Key takeaways

• A command line splits into the command name, options, their option-arguments and operands, and one-letter options can be grouped behind one dash.
• A glob passes file names as ordinary words, so -- or ./* keeps a name such as -n from becoming an option.
• Bash resolves a name as an alias or keyword first, then as a function, a builtin and finally a program found through PATH, and type -a lists every match in that order.
• command -v is the portable test for whether a command exists, and help, man and --help document builtins, installed programs and many tools respectively.