Command line

Getting information (man)

It’s common to learn the useful options for the commands you use most. But you must know how to find the options available.

You might be able to search on the web, of course. Make sure you’re looking at the right information for the version and type of command you are trying to use. The Windows commands are available on the Microsoft documentation site.

On Unix, use the man (manual) command. The manual’s information is definitive and thorough, and will be correct for the specific version of the command you’re using.

For example, to get information about the ls command, which lists directory contents, do:

man ls

The information you get from man is always in a similar format. There are other sections too, but these are the main ones:

section what it tells you
NAME The name of the command and what it does.
SYNOPSIS A summary of the command as you might type it: square brackets ([ and ]) indicate that the item is optional. Options are preceded with - and all possible short options are normally listed. Arguments follow, with ... indicating more may be added.
DESCRIPTION A detailed description of what the command does, together with details for each option.
EXAMPLES Sometimes some example commands (with options and arguments) are shown.
DIAGNOSTICS If you write programs that issue this command, it’s useful to know how it communicates what happened when it ran.

You should learn to read the SYNOPSIS section by looking at man for commands you do know. That way you are practising how to extract information about new commands.

Example with ls

If you do man ls and look at the synopsis for that command, you’ll see there are 40 options available. You can tell they are options because they are preceded by -, and you can tell that they are all optional because they are inside square brackets:

  ls [-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1] [file ...]

One of the options listed is a. If you look down in the DESCRIPTION you can read what that option does:

-a   Include directory entries whose names
     begin with a dot (.).

Files whose names begin with . are hidden files. So -a shows hidden files which are not normally listed.

Often these short options are chosen as mnemonics: -a here means “show all files”.

For example, this command — with no options — lists the files (but doesn’t show any hidden files, because by default hidden files are… hidden):


But by adding the -a option, you can list all the files, including hidden ones:

ls -a

Notice how there is no argument on that command. That works because arguments for ls are optional: you know that because the argument(s) in the synopsis are inside square brackets. In the synopsis, the argument was file — you know that is an argument, not an option, because it is not prefixed by a -.

So, you could add an argument — for example, *.txt:

ls -a *.txt

…and this would list all files (including hidden files) whose names end in .txt. The * is a wildcard which matches any characters.

You can have more than one argument: that’s what the ... at the end of the synopsis told you. So:

ls -a *.txt

…will list all the text files and (if it exists).