Master the command line: how to use man pages

Kirk McElhearn
28 July, 2013
View more articles fromthe author

If you’ve read this site for any length of time – particularly the 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 orcd? Is it some kind of arcane knowledge, handed down only to initiates after gruelling 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, the role of which is to format and display this documentation.

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:

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 lscommand’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 manpages 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 pop-up 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 favourite 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 pop-up 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.

by Kirk McElhearn, Macworld

Leave a Comment

Please keep your comments friendly on the topic.

Contact us