How to read a synopsis
Also called “usage string” or simply “usage.”
The synopsis is a formatted string, usually a single line towards the beginning of the documentation, which shows how to write commands for a specific program. It starts with the program name. The words after that usually align with the following patterns:
A word in all uppercase is a placeholder for a word you have to provide. For example, the synopsis
foo PATH
means a command likefoo './some file.txt'
is valid, butfoo
(no file) orfoo ./1.txt ./2.txt
(two files) is not valid. This word can also reference several other parameters, such asOPTIONS
referring to any of the options documented elsewhere.A word in all lower case is literal – it should be entered verbatim in the command. For example, the synopsis
foo [--help]
means thatfoo
andfoo --help
are the only valid commands.A word enclosed in square brackets means it’s optional. For example, the synopsis
foo [PATH]
means that bothfoo
andfoo './some file.txt'
are both valid.A word followed by an ellipsis means that the word can be repeated. For example, the synopsis
foo PATH…
means thatfoo
takes one or morePATH
arguments, meaningfoo ./first
andfoo ./first ./second
are both valid, butfoo
is not.A pipe character separates mutually exclusive choices. For example, the synopsis
foo --force|--dry-run
means thatfoo --force
andfoo --dry-run
are valid, butfoo --force --dry-run
is not.An equals sign separates an option name from its value. For example, the synopsis
foo [--config=FILE]
means thatfoo
andfoo --config=/etc/foo.conf
are both valid, butfoo --config
andfoo --config=
are not.Complex commands sometimes have more than one synopsis, based on fundamentally different use cases.
This page is a preview of The newline Guide to Bash Scripting