Master the command line: How to use man pages

If you’ve read Macworld for any length of time—particularly our OS X Hints blog or any other story that asks you to use Terminal—you may have wondered to yourself: How do you learn about all those mysterious commands, such as ls or cd? Is it some kind of arcane knowledge, handed down only to initiates after grueling initiations? Well, no. Actually, anyone can learn about Terminal commands, if they know where to look. Today, I’ll tell you where.

Man up

The key to Terminal wisdom is the man command. It summons manual (or man) pages for almost any command; they’re the equivalent of a help system for the command line. In fact, man itself is a command, whose role is to format and display this documentation.

First, launch Terminal (in your /Applications/Utilities folder). Then, if you type man pwd, for example, Terminal will display the man page for the pwd command.

The beginning of the man page for the pwd command.

All man pages have a common format. They begin with name (the name of the command) and a brief description of what it does. The pwd command I looked at above shows the following:

pwd—return working directory name

Next comes synopsis, which shows the command any any options, or flags, that you can use with it. For pwd, there are two options: -L and -P. These options are explained in the description section:

DESCRIPTION
The pwd utility writes the absolute pathname of the current working directory to the standard output.

Some shells may provide a builtin pwd command which is similar or  identical to this utility.  Consult the builtin(1) manual page.

The options are as follows:

-L      Display the logical current working directory.
-P      Display the physical current working directory (all symbolic links resolved).

If no options are specified, the -L option is assumed.

As you can see here, each of the two options is explained, and a final sentence tells you that the command assumes that the -L option is desired if no other option (and there’s only one) is specified.

As you work from the command line, you’ll find that reading up on the options available for different commands is really important. You’ll learn the myriad ways you can use these tools, and some man pages also contain examples to help you understand them.

Paging man pages

When you look at a man page, you do so in Terminal through another command, called a pager; by default, this is the less command. What a pager does is allow you to view content in Terminal page by page, or line by line. When you’re viewing a man page, you will most often not see the entire page at once. You’ll need to page down to see more.

There are two ways to do this with less. If you press Return, the page will move down one line. And if you press the spacebar, the page will scroll one page (the number of lines visible in your Terminal window). You can tell that there’s more to come by the : (colon) visible at the bottom of the window.

Try it on your Mac: Open Terminal, type man ls, then press Return. The ls command’s man page is quite long, and you’ll need to press the spacebar several times to get to the bottom.

Sometimes, when you’re viewing a man page, you need to go back up and look at something that’s no longer visible. Depending on your Terminal settings, you may be able to scroll the Terminal window. If not, press Control-B to go back a page, and the spacebar, or Control-F, to go forward a page.

When you get to the end of a man page, you’ll see this: (END). You’ll notice that you can’t do anything at that point; you need to quit the less command; do this by pressing the q key.

Other ways to read man pages

If you don’t want to read man pages in Terminal, there are other ways to view this content. Carl Lindberg’s free ManOpen is a simple app that lets you view man pages in a more attractive way than in Terminal. Press Command-O, enter the name of a command, and click Open. ManOpen is especially useful because you can choose specific sections to view from a popup menu, and you can navigate more easily than in Terminal with the less command.

ManOpen lets you view man pages in a friendlier interface than Terminal.

But you can also find man pages on the Web. Just type man and the name of a command into your favorite search engine, and you’ll get plenty of hits. Apple has a documentation repository with man pages here. You can click Alphabetic Index to get a list of all commands, then search for the one you want. Apple’s man pages are useful because a popup menu near the top of the page lets you choose an OS X version, so if you need to see the man page for an older version of OS X, you can do so.

No matter which route you choose, man pages open the door to a goldmine of information about the command line. Use them and you’ll learn all the ins and outs of the commands you use.

Subscribe to the MacWeek Newsletter

Comments