How can I read documentation about built in zsh commands?

It's frustrating when I do something like man bindkey and i get:

BUILTIN(1)                BSD General Commands Manual               BUILTIN(1)

NAME
     builtin, !, %, ., :, @, {, }, alias, alloc, bg, bind, bindkey, break, breaksw, builtins, case, cd, chdir, command,
     complete, continue, default, dirs, do, done, echo, echotc, elif, else, end, endif, endsw, esac, eval, exec, exit,
     export, false, fc, fg, filetest, fi, for, foreach, getopts, glob, goto, hash, hashstat, history, hup, if, jobid,
     jobs, kill, limit, local, log, login, logout, ls-F, nice, nohup, notify, onintr, popd, printenv, pushd, pwd, read,
     readonly, rehash, repeat, return, sched, set, setenv, settc, setty, setvar, shift, source, stop, suspend, switch,
     telltc, test, then, time, times, trap, true, type, ulimit, umask, unalias, uncomplete, unhash, unlimit, unset,
     unsetenv, until, wait, where, which, while -- shell built-in commands

SYNOPSIS
     builtin [-options] [args ...]

DESCRIPTION
     Shell builtin commands are commands that can be executed within the running shell's process.  Note that, in the

Is there an easy way to access the documentation for such commands?

Solution 1:

The key information for getting a more useful help utility is actually included with Zsh, it's just a matter of finding the critical—and poorly discoverable—man page: man zshcontrib (here on the web), which describes the run-help widget:

By default, run-help is an alias for the man command, so this often fails when the command word is a shell builtin or a user-defined function. By redefining the run-help alias, one can improve the on-line help provided by the shell.

It further explains how to replace it with a built-in improvement.

After setting this up, calling run-help for names of builtins, completion functions and so forth will now try to show you extracted documentation, or show you the right containing man page, etc. For example run-help bindkey outputs:

bindkey
   See the section `Zle Builtins' in zshzle(1).

which could be better. For a better example, run-help history shows the Zsh man page section for fc, which is the command that underlies history.

Also handy to note: ESC-h will call run-help for the command on the current input line.

I presume this setup isn't the default because extracting the granular help data and setting HELPDIR to point to it might be a packaging decision left to OS distributions. There's also a user choice: the autoload run-help util is useful without setting HELPDIR at all. It seems to be good at taking you to the right man page even if it can't jump to the exact section for one item. Some may prefer this to running into cases like the bindkey example above which just wastes time. (Why they default to alias run-help=man then, I cannot fathom).

For Zsh version 5.0.3 or newer

The helpfiles extractions are likely included with the Zsh distribution. It's just a matter of finding them on your system to set HELPDIR if you wish—likely candidates are in /usr/share/zsh or /usr/local/share/zsh, look for a help subdirectory.

For versions of Zsh before 5.0.3

You will likely need to follow the procedure detailed in man zshcontrib yourself to generate the help files. It's a little annoying to need to do this, but otherwise quick and painless.

Find your installed version with zsh --version and obtain the corresponding source tarball from the sourceforge archive. Then run the helpfiles script as shown in the man page and set the target as HELPDIR in your ~/.zshrc.

Solution 2:

Try either of these:

man zshbuiltins

or

man zshall

The man pages for zsh are divided up by topic, man zsh is mostly a table of contents and introduction while man zshall is everything (24628 lines on my system compared to 5242 for man bash).

As for bindkey, man zshbuiltins will refer you to man zshzle.

Solution 3:

You can add those lines to your .zshrc profile:

unalias run-help 2>/dev/null
autoload run-help
HELPDIR=/path/to/zsh_help_directory
alias help=run-help

where /path/to/zsh_help_directory must be substituted by your zsh help folder. If you are on OS X with zsh installed via Homebrew, this folder is /usr/local/share/zsh/help

This will enable bash-like help for zsh.

It should be pointed out that if the default installation path of your zsh login shell's help files exists and contains the desired files, the third line HELPDIR=/path/to/zsh_help_directory won't be required.

Source your .zshrc ($ source .zshrc) and check that everything works fine with for instance (pick up any zsh builtin you want, here I picked autoload):

$ help autoload

Notice that the 2>/dev/null part is needed because without it, std error 'unalias: no such hash table element: run-help' would occur every time you source your .zshrc file while run-help is already unaliased.

Solution 4:

Other answers are too long...

Set up the run-help function by adding the following to your .zshrc:

unalias run-help
autoload run-help

Tip: Reload the config with . ~/.zshrc.

Now you should see a manual entry when you run run-help bindkey. If it doesn't work, you need to see more instructions for Accessing On-Line Help (man zshcontrib).

In some cases, run-help will not find a manual entry and you have to search through man zshall.