zsh Tip: run-help is extremely helpful

Properly configured, the zsh run-help function offers additional help files and much easier access to documentation than the man command.

To enable it, simply add these lines to your ~/.zshrc startup file:

unalias run-help 2>/dev/null       # don't display err if already done
autoload -Uz run-help              # load the function
alias help=run-help                # optionally alias run-help to help

Test the changes shown here by entering them in the terminal. Any changes will be reverted when the window is closed.

You’ll also want to set the shell parameter HELPDIR to the location of the help directory, typically in a subdirectory of /usr/share/zsh/ or /usr/local/share/zsh.

HELPDIR=/usr/share/zsh/5.8.1/help # macOS 13

Update: Because macOS updates to zsh also change the location of the help directory, I’ve updated my .zshrc file to set HELPDIR dynamically.

HELPDIR="/usr/share/zsh/$(zsh --version | cut -d' ' -f2)/help"

(This works on macOS, but there are probably better, more reliable ways to accomplish. Please let me know if you have any suggestions.)

If HELPDIR points to the correct directory, run-help should show this information for the history command:

 % help history
fc [ -e ename ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ last ] ]
fc -l [ -LI ] [ -nrdfEiD ] [ -t timefmt ] [ -m match ]
      [ old=new ... ] [ first [ last ] ]
fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
fc -P
fc -ARWI [ filename ]
       The fc command controls the interactive history mechanism.  Note…

(To see how much easier this is, try locating the same information with man history. Go ahead. I’ll wait.)

But, wait, there’s more!

Run run-help with option-h

Enter a command (without pressing enter) and press ESC-h to run the help function for it. (Option-h if your terminal is configured to use option as meta key.)

Use bindkey to verify the bindings:

%  bindkey | grep run-help
"^[H" run-help
"^[h" run-help

Credit

Ironically, the documentation for run-help is too deeply hidden in the zshcontrib man page to be found by run-help. I might have found it eventually, but probably not. Credit goes to helpful contributors at Stack Exchange.

Appendum

I discovered additional help modules (mentioned in the zshcontrib man pages) which can be enabled by autoloading them:

autoload run−help−git
autoload run−help−ip
autoload run−help−openssl
autoload run−help−p4
autoload run−help−sudo
autoload run−help−svk
autoload run−help−svn