General commands for getting help and/or documentation for command line utilities in terminal on macOS?

Some command line interfaces or command line utilities give some comprehensive documentation or help when --help is appended to the name of the command, for example git:

git --help
# shows comprehensive help docs

Some others show only the command and its arguments (that's all), for example grep:

grep --help
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
    [-e pattern] [-f file] [--binary-files=value] [--color=when]
    [--context[=num]] [--directories=action] [--label] [--line-buffered]
    [--null] [pattern] [file ...]

And others give some assistance, but only because --help is not recognised as a legal option, for examples ls:

ls --help
ls: illegal option -- -
usage: ls [-@ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1%] [file ...]

and netstat:

netstat --help
netstat: illegal option -- -
Usage:  netstat [-AaLlnW] [-f address_family | -p protocol]
    netstat [-gilns] [-f address_family]
    netstat -i | -I interface [-w wait] [-abdgRtS]
    netstat -s [-s] [-f address_family | -p protocol] [-w wait]
    netstat -i | -I interface -s [-f address_family | -p protocol]
    netstat -m [-m]
    netstat -r [-Aaln] [-f address_family]
    netstat -rs [-s]

Question

Are there any generally safe way(s) of getting documentation or help with a CLI or utility without having to google (i.e. from within the terminal)? I currently try --help or -h, but other than that I go straight to google, but would like to know if there are other things to (safely) try before going to google.

Solution 1:

Have you heard of using the man command. For example: man ls or man grep. You can get comprehensive documentation on man by entering man man.

Some of the basic keys used by the man command are the f key to page forward, the b key to page backward and the q key to quit.

Try using the mouse to highlight the command, then right click on the highlighted text and select Open man page. See example below.

Note: The highlighted text can not contain spaces.

Some commands are builtin. This means the command is part on the current shell. If you are using the zsh shell (which is the macOS default shell), then you will need to enter man zshbuiltins for documentation.

Solution 2:

Also consider using apropos to "search the whatis database for strings" that can help find the right command.

Use the -t option of man to "format the manual page" in a manner that Preview.app can display:

man -t apropos | open -f -a Preview.app

Solution 3:

An analogous action for obtaining a man-page, described in the answer by @David Anderson, above, can be performed with a shell function that leverages the special URL, x-man-page and the open command. This allows viewing man-pages in a Terminal session without taking over the Terminal window from which man was requested. Instead, a new window will be opened to display the man-page contents.

With bash, add this to your ~/.bashrc file; with zsh add the same to ~/.zshrc:

function xmanpage ()
{
    if [ $#   -eq 1 ]; then
        open x-man-page://$1;
    elif [ $# -eq 2 ]; then
        open x-man-page://$1/$2;
    fi
}

If only a name is passed to the function, the man-page for section-1 (user commands) is returned. To select man-pages from another section, specify the section number of the object, followed by the name in interest. For instance, to see the stat command information: