How can I read documentation about built in zsh commands?
LinuxBashZshBuilt InLinux Problem Overview
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?
Linux Solutions
Solution 1 - Linux
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 - Linux
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 - Linux
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 - Linux
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
.
Solution 5 - Linux
I moved from bash to zsh, and missed the "help" builtin. So I wrote an alias that called it. Then I figured out something better. Though I do sometimes have to hit "n" one or more times to get to the line in the manual that I need.
help(){
#This function used to call the "bash" builtin.
#bash -c "help $@"
#Better way: look it up in the man pages. I often look up "test" which doesn't give a usefull result,
#so I added that as a special case.
if [[ $1 == "test" ]]; then
man --pager="less -p'^CONDITIONAL EXPRESSIONS$'" zshall
else
man --pager="less -p'^ *$@ '" zshall
fi
}
Solution 6 - Linux
I finally got sick of hunting through man pages and online searches each time I needed to get some Zsh info. I went through all of Zsh's man pages and put together a good "help" function that's fairly expansive.
To use this, I would create a file called "help" somewhere in your fpath
and add autoload -Uz help
to your zshrc.
# better help function than zsh's crappy run-help
local ZSHPAGE=zshall LESSQUERY
LESS="-RM~gIsw"
LESS_TERMCAP_mb=$'\E[01;31m'
LESS_TERMCAP_md=$'\E[01;31m'
LESS_TERMCAP_me=$'\E[0m'
LESS_TERMCAP_se=$'\E[0m'
LESS_TERMCAP_so=$'\E[01;44;33m'
LESS_TERMCAP_ue=$'\E[0m'
LESS_TERMCAP_us=$'\E[01;32m'
case "$@" in
""|--help|-h)
local cmds='
RESERVED WORDS
do done esac then elif else fi for case if while function repeat time until select coproc nocorrect foreach end ! [[ { } declare export float integer local readonly typeset
BUILTIN COMMANDS
- . : [ [[ alias autoload bg bindkey break builtin bye cap cd chdir clone command comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues continue declare dirs disable disown echo echotc echoti emulate enable eval exec exit export false fc fg float functions getcap getln getopts hash history integer jobs kill lets limit local log logout noglob popd print printf pushd pushln pwd r read readonly rehash return sched set setcap setopt shift source stat suspend test times trap true ttyctl type typeset ulimit umask unalias unfunction unhash unlimit unset unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp
'
if whence -p fold >/dev/null; then
fold -sw$COLUMNS <<< $cmds
else
print -- $cmds
fi
return;;
'-- '*)
shift
LESSQUERY="$@";;
loop*|while|do|done|if|then|elif|else|fi|until)
LESSQUERY='^COMPLEX COMMANDS$'
ZSHPAGE=zshmisc;;
for)
LESSQUERY='^ for name \.\.\. '
ZSHPAGE=zshmisc;;
foreach|end)
LESSQUERY='^ foreach name \.\.\.'
ZSHPAGE=zshmisc;;
case|esac)
LESSQUERY='^ case word'
ZSHPAGE=zshmisc;;
coproc)
LESSQUERY='coproc'
ZSHPAGE=zshmisc;;
repeat)
LESSQUERY='^ repeat word do'
ZSHPAGE=zshmisc;;
select)
LESSQUERY='^ select name \[ in word'
ZSHPAGE=zshmisc;;
time)
LESSQUERY='^ time \[ pipeline \]'
ZSHPAGE=zshmisc;;
list|'('*|'{'*|subshell)
LESSQUERY='^ time \[ pipeline \]'
ZSHPAGE=zshmisc;;
'!'|not)
LESSQUERY='^ \! exp true if exp is false\.'
ZSHPAGE=zshmisc;;
.)
LESSQUERY='^ \. file \[ arg \.\.\. \]'
ZSHPAGE=zshbuiltins;;
:)
LESSQUERY='^ : \['
ZSHPAGE=zshbuiltins;;
alias)
LESSQUERY='^ alias \['
ZSHPAGE=zshbuiltins;;
autoload)
LESSQUERY='^ autoload \['
ZSHPAGE=zshbuiltins;;
*autoload*)
LESSQUERY='^AUTOLOADING FUNCTIONS$'
ZSHPAGE=zshmisc;;
bg)
LESSQUERY='^ bg \['
ZSHPAGE=zshbuiltins;;
bindkey)
LESSQUERY='^ZLE BUILTINS$'
ZSHPAGE=zshzle;;
break)
LESSQUERY='^ break \[ n \]'
ZSHPAGE=zshbuiltins;;
-|exec|command|noglob|nocorrect|builtin|precommand*)
LESSQUERY='^PRECOMMAND MODIFIERS$'
ZSHPAGE=zshmisc;;
bye)
LESSQUERY='^ bye Same as exit\.'
ZSHPAGE=zshbuiltins;;
cap)
LESSQUERY='^The zsh/cap Module$'
ZSHPAGE=zshmodules;;
cd)
LESSQUERY='^ cd \[ -qsLP \] \[ arg \]'
ZSHPAGE=zshbuiltins;;
chdir)
LESSQUERY='^ chdir Same as cd\.'
ZSHPAGE=zshbuiltins;;
clone)
LESSQUERY='^The zsh/clone Module'
ZSHPAGE=zshmodules;;
compargu*)
LESSQUERY='^ comparguments$'
ZSHPAGE=zshmodules;;
compcall)
LESSQUERY='^ compcall \[ -TD'
ZSHPAGE=zshcompwid;;
compctl)
LESSQUERY='^ compctl \[ -CDT'
ZSHPAGE=zshcompctl;;
compdes*)
LESSQUERY='^ compdescribe$'
ZSHPAGE=zshmodules;;
compfiles)
LESSQUERY='^ compfiles$'
ZSHPAGE=zshmodules;;
compgroups)
LESSQUERY='^ compgroups$'
ZSHPAGE=zshmodules;;
compquote)
LESSQUERY='^ compquote$'
ZSHPAGE=zshmodules;;
comptags)
LESSQUERY='^ comptags$'
ZSHPAGE=zshmodules;;
comptry)
LESSQUERY='^ comptry$'
ZSHPAGE=zshmodules;;
compvalues)
LESSQUERY='^ compvalues$'
ZSHPAGE=zshmodules;;
continue)
LESSQUERY='^ continue \[ n \]'
ZSHPAGE=zshbuiltins;;
dirs)
LESSQUERY='^ dirs \[ -c \]'
ZSHPAGE=zshbuiltins;;
disable)
LESSQUERY='^ disable \[ -afmprs \]'
ZSHPAGE=zshbuiltins;;
disown)
LESSQUERY='^ disown \[ job \.\.\. \]'
ZSHPAGE=zshbuiltins;;
echo)
LESSQUERY='^ echo \[ -neE \]'
ZSHPAGE=zshbuiltins;;
echotc)
LESSQUERY='^The zsh/termcap Module$'
ZSHPAGE=zshmodules;;
echoti)
LESSQUERY='^The zsh/terminfo Module$'
ZSHPAGE=zshmodules;;
emulate)
LESSQUERY='^ emulate \[ -LR \]'
ZSHPAGE=zshbuiltins;;
enable)
LESSQUERY='^ enable \[ -afmprs \]'
ZSHPAGE=zshbuiltins;;
eval)
LESSQUERY='^ eval \[ arg \.\.\. \]'
ZSHPAGE=zshbuiltins;;
exit)
LESSQUERY='^ exit \[ n \]'
ZSHPAGE=zshbuiltins;;
export)
LESSQUERY='^ export \[ name'
ZSHPAGE=zshbuiltins;;
fc)
LESSQUERY='^ fc \[ -e ename \] \[ -LI \]'
ZSHPAGE=zshbuiltins;;
fg)
LESSQUERY='^ fg \[ job \.\.\. \]S'
ZSHPAGE=zshbuiltins;;
functions)
LESSQUERY='^ functions \[ \{\+\|-\}UkmtTuz'
ZSHPAGE=zshbuiltins;;
getcap)
LESSQUERY='^The zsh/cap Module$'
ZSHPAGE=zshmodules;;
getln)
LESSQUERY='^ getln \[ -AclneE \]'
ZSHPAGE=zshbuiltins;;
getopts)
LESSQUERY='^ getopts optstring name'
ZSHPAGE=zshbuiltins;;
hash)
LESSQUERY='^ hash \[ -Ldfmrv \]'
ZSHPAGE=zshbuiltins;;
history)
LESSQUERY='^HISTORY EXPANSION$';;
integer)
LESSQUERY='^ integer \[ \{\+\|-\}Hghlprtux'
ZSHPAGE=zshbuiltins;;
jobs)
LESSQUERY='^ jobs \[ -dlprs \]'
ZSHPAGE=zshbuiltins;;
kill)
LESSQUERY='^ kill \[ -s signal_name'
ZSHPAGE=zshbuiltins;;
limit)
LESSQUERY='^ limit \[ -hs \]'
ZSHPAGE=zshbuiltins;;
local)
LESSQUERY='^ local \[ \{\+\|-\}AHUahlprtux '
ZSHPAGE=zshbuiltins;;
log)
LESSQUERY='^ log List all'
ZSHPAGE=zshbuiltins;;
logout)
LESSQUERY='^ logout \[ n \]'
ZSHPAGE=zshbuiltins;;
popd)
LESSQUERY='^ popd \[ -q \]'
ZSHPAGE=zshbuiltins;;
print)
LESSQUERY='^ print \[ -abcDilmnNoOpPrsSz \]'
ZSHPAGE=zshbuiltins;;
printf)
LESSQUERY='^ printf format \[ arg \.\.\. \]'
ZSHPAGE=zshbuiltins;;
pushd)
LESSQUERY='^ pushd \[ -qsLP \]'
ZSHPAGE=zshbuiltins;;
pushln)
LESSQUERY='^ pushln \[ arg \.\.\. \]'
ZSHPAGE=zshbuiltins;;
pwd)
LESSQUERY='^ pwd \[ -rLP \]'
ZSHPAGE=zshbuiltins;;
r)
LESSQUERY='^ r Same as fc -e -\.'
ZSHPAGE=zshbuiltins;;
read)
LESSQUERY='^ read \[ -rszpqAclneE \]'
ZSHPAGE=zshbuiltins;;
readonly)
LESSQUERY='^ readonly$'
ZSHPAGE=zshbuiltins;;
rehash)
LESSQUERY='^ rehash Same as hash -r\.'
ZSHPAGE=zshbuiltins;;
return)
LESSQUERY='^ return \[ n \]'
ZSHPAGE=zshbuiltins;;
sched|'sched module')
LESSQUERY='^THE ZSH/SCHED MODULE$'
ZSHPAGE=zshmodules;;
set)
LESSQUERY='^ set \[ \{\+\|-\}options'
ZSHPAGE=zshbuiltins;;
setcap)
LESSQUERY='^The zsh/cap Module$'
ZSHPAGE=zshmodules;;
setopt)
LESSQUERY='^ setopt \[ \{\+\|-\}options'
ZSHPAGE=zshbuiltins;;
shift)
LESSQUERY='^ shift \[ -p \]'
ZSHPAGE=zshbuiltins;;
source)
LESSQUERY='^ source file \[ arg'
ZSHPAGE=zshbuiltins;;
stat|zstat|'stat module')
LESSQUERY='^The zsh/stat Module$'
ZSHPAGE=zshmodules;;
times)
LESSQUERY='^ times Print'
ZSHPAGE=zshbuiltins;;
test|'[['*|'['*)
LESSQUERY='^CONDITIONAL EXPRESSIONS$'
ZSHPAGE=zshmisc;;
trap)
LESSQUERY='^ trap \[ arg \] \[ sig \.\.\. \]'
ZSHPAGE=zshbuiltins;;
true)
LESSQUERY='^ true \[ arg \.\.\. \]'
ZSHPAGE=zshbuiltins;;
ttyctl)
LESSQUERY='^ ttyctl \[ -fu \]'
ZSHPAGE=zshbuiltins;;
type)
LESSQUERY='^ type \[ -wfpamsS \]'
ZSHPAGE=zshbuiltins;;
typeset|declare)
LESSQUERY='^ typeset \[ \{\+\|-\}AHUaghlmprtux \]'
ZSHPAGE=zshbuiltins;;
ulimit)
LESSQUERY='^ ulimit \[ -HSa \] \['
ZSHPAGE=zshbuiltins;;
umask)
LESSQUERY='^ umask \[ -S \] \[ mask \]'
ZSHPAGE=zshbuiltins;;
unalias)
LESSQUERY='^ unalias \[ -ams \]'
ZSHPAGE=zshbuiltins;;
unfunction)
LESSQUERY='^ unfunction$'
ZSHPAGE=zshbuiltins;;
unhash)
LESSQUERY='^ unhash \[ -adfms \]'
ZSHPAGE=zshbuiltins;;
unset)
LESSQUERY='^ unset \[ -fmv \]'
ZSHPAGE=zshbuiltins;;
unsetopt)
LESSQUERY='^ unsetopt \[ \{\+\|-\}options'
ZSHPAGE=zshbuiltins;;
vared)
LESSQUERY='^ vared \[ -Aache \]'
ZSHPAGE=zshzle;;
wait)
LESSQUERY='^ wait \[ job \.\.\. \]'
ZSHPAGE=zshbuiltins;;
whence)
LESSQUERY='^ whence \[ -vcwfpamsS \]'
ZSHPAGE=zshbuiltins;;
where)
LESSQUERY='^ where \[ -wpmsS \]'
ZSHPAGE=zshbuiltins;;
which)
LESSQUERY='^ which \[ -wpamsS \]'
ZSHPAGE=zshbuiltins;;
zcompile)
LESSQUERY='^ zcompile \[ -U \] \[ -z \|'
ZSHPAGE=zshbuiltins;;
zformat)
LESSQUERY='^ zformat -f param format'
ZSHPAGE=zshmodules;;
zftp|'ftp module')
LESSQUERY='^The zsh/zftp Module$'
ZSHPAGE=zshmodules;;
zle)
LESSQUERY='^ zle -l \[ -L \| -a \] \[ string \.\.\. \]'
ZSHPAGE=zshzle;;
widget)
LESSQUERY='^ widget \[ -n num \] \[ -Nw \]'
ZSHPAGE=zshzle;;
zmodload)
LESSQUERY='^ zmodload \[ -dL \] \[ \.\.\. \]'
ZSHPAGE=zshbuiltins;;
zparseopts)
LESSQUERY='^ zparseopts \[ -DKME \]'
ZSHPAGE=zshmodules;;
zprof|'zprof module')
LESSQUERY='^THE ZSH/ZPROF MODULE$'
ZSHPAGE=zshmodules;;
zpty|'zpty module')
LESSQUERY='^THE ZSH/ZPTY MODULE$'
ZSHPAGE=zshmodules;;
zregexparse)
LESSQUERY='^ zregexparse$'
ZSHPAGE=zshmodules;;
zsocket|(net|socket)' module')
LESSQUERY='^THE ZSH/NET/SOCKET MODULE$'
ZSHPAGE=zshmodules;;
zstyle|'zutil module')
LESSQUERY='^The zsh/zutil Module$'
ZSHPAGE=zshmodules;;
ztcp|'tcp module')
LESSQUERY='^THE ZSH/NET/TCP MODULE$'
ZSHPAGE=zshmodules;;
attr*mod*|zgetattr|zsetattr|zdelattr|zlistattr)
LESSQUERY='^THE ZSH/ATTR MODULE$'
ZSHPAGE=zshmodules;;
complist*mod*)
LESSQUERY='^THE ZSH/COMPLIST MODULE'
ZSHPAGE=zshmodules;;
computil*mod*)
LESSQUERY='^THE ZSH/COMPUTIL MODULE'
ZSHPAGE=zshmodules;;
curses*|zcurses)
LESSQUERY='^THE ZSH/CURSES MODULE'
ZSHPAGE=zshmodules;;
datetime*|strftime)
LESSQUERY='^THE ZSH/DATETIME MODULE'
ZSHPAGE=zshmodules;;
(db|gdbm)*|ztie|zuntie)
LESSQUERY='^THE ZSH/DB/GDBM MODULE'
ZSHPAGE=zshmodules;;
delto*|delete-to-char|zap-to-char)
LESSQUERY='^THE ZSH/DELTOCHAR MODULE'
ZSHPAGE=zshmodules;;
example*)
LESSQUERY='^THE ZSH/EXAMPLE MODULE'
ZSHPAGE=zshmodules;;
files*mod*|chgrp|chown|ln|mkdir|mv|rm|rmdir|sync)
LESSQUERY='^THE ZSH/FILES MODULE'
ZSHPAGE=zshmodules;;
langinfo*)
LESSQUERY='^THE ZSH/LANGINFO MODULE'
ZSHPAGE=zshmodules;;
mapfile*)
LESSQUERY='^THE ZSH/MAPFILE MODULE'
ZSHPAGE=zshmodules;;
mathfunc*mod*)
LESSQUERY='^THE ZSH/MATHFUNC MODULE'
ZSHPAGE=zshmodules;;
param*mod*)
LESSQUERY='^THE ZSH/PARAMETER MODULE'
ZSHPAGE=zshmodules;;
pcre*)
LESSQUERY='^THE ZSH/PCRE MODULE'
ZSHPAGE=zshmodules;;
regex*mod*)
LESSQUERY='^THE ZSH/REGEX MODULE'
ZSHPAGE=zshmodules;;
system*mod*|syserror|sysopen|sysread|sysseek|syswrite|zsystem*)
LESSQUERY='^THE ZSH/SYSTEM MODULE'
ZSHPAGE=zshmodules;;
zselect*)
LESSQUERY='^THE ZSH/ZSELECT MODULE'
ZSHPAGE=zshmodules;;
start*flag*|invok*|initial*)
LESSQUERY='^INVOCATION$'
ZSHPAGE=zsh;;
(start|shut)*file*|*zshenv|*zshrc|*zprofile|*zlogin|*zlogout|*zdotdir*|*ZDOTDIR*)
LESSQUERY='^STARTUP/SHUTDOWN FILES$'
ZSHPAGE=zsh;;
subscript*)
LESSQUERY='^ Subscript Flags'
ZSHPAGE=zshparam;;
simple*|pipe*)
LESSQUERY='^SIMPLE COMMANDS & PIPELINES'
ZSHPAGE=zshmisc;;
function*)
LESSQUERY='^ function word'
ZSHPAGE=zshmisc;;
alt*)
LESSQUERY='^ALTERNATE FORMS$'
ZSHPAGE=zshmisc;;
reserv*)
LESSQUERY='^RESERVED WORDS$'
ZSHPAGE=zshmisc;;
error*)
LESSQUERY='^ERRORS$'
ZSHPAGE=zshmisc;;
alias*)
LESSQUERY='^ALIASING$'
ZSHPAGE=zshmisc;;
quot*)
LESSQUERY='^QUOTING$'
ZSHPAGE=zshmisc;;
redirect*|*'>'*|*'<'*|*'&>'*|*'2>'*|*'>>'*|*'<<'*)
LESSQUERY='^REDIRECTION$'
ZSHPAGE=zshmisc;;
file*desc*)
LESSQUERY='^OPENING FILE DESCRIPTORS USING PARAMETERS$'
ZSHPAGE=zshmisc;;
multios)
LESSQUERY='^MULTIOS$'
ZSHPAGE=zshmisc;;
anon*func*)
LESSQUERY='^ANONYMOUS FUNCTIONS$'
ZSHPAGE=zshmisc;;
hook*)
LESSQUERY='^ Hook Functions$'
ZSHPAGE=zshmisc;;
trap*)
LESSQUERY='^ Trap Functions$'
ZSHPAGE=zshmisc;;
job*)
LESSQUERY='^JOBS$'
ZSHPAGE=zshmisc;;
math*|'(('*|'$(('|let*|arith*)
LESSQUERY='^ARITHMETIC EVALUATION$'
ZSHPAGE=zshmisc;;
prompt|promptinit|prompt*theme*)
LESSQUERY='^ prompt \[ -c \| -l \]'
ZSHPAGE=zshcontrib;;
PS1|prompt*|PROMPT*)
LESSQUERY='^SIMPLE PROMPT ESCAPES$'
ZSHPAGE=zshmisc;;
history*)
LESSQUERY='^HISTORY EXPANSION$'
ZSHPAGE=zshexpn;;
proc*sub*|*'<('*|*')>'*)
LESSQUERY='^PROCESS SUBSTITUTION$'
ZSHPAGE=zshexpn;;
param*flag*)
LESSQUERY='^ Parameter Expansion Flags$'
ZSHPAGE=zshexpn;;
param*rule*|nested*sub*)
LESSQUERY='^ Rules$'
ZSHPAGE=zshexpn;;
param*ex*)
LESSQUERY='^ Examples$'
ZSHPAGE=zshexpn;;
param*|'${')
LESSQUERY='^PARAMETER EXPANSION$'
ZSHPAGE=zshexpn;;
brace*expan*)
LESSQUERY='^BRACE EXPANSION$'
ZSHPAGE=zshexpn;;
filename*expan*)
LESSQUERY='^FILENAME EXPANSION$'
ZSHPAGE=zshexpn;;
expan*|subst*)
LESSQUERY='^ zshexpn - zsh expansion and substitution$'
ZSHPAGE=zshexpn;;
dyn*dir*)
LESSQUERY='^ Dynamic named directories$'
ZSHPAGE=zshexpn;;
static*dir*)
LESSQUERY='^ Static named directories$'
ZSHPAGE=zshexpn;;
approx*match*)
LESSQUERY='^ Approximate Matching$'
ZSHPAGE=zshexpn;;
recurs*glob*)
LESSQUERY='^ Recursive Globbing$'
ZSHPAGE=zshexpn;;
glob*qual*)
LESSQUERY='^ Glob Qualifiers$'
ZSHPAGE=zshexpn;;
glob*flag*)
LESSQUERY='^ Globbing Flags$'
ZSHPAGE=zshexpn;;
glob*)
LESSQUERY='^ Glob Operators$'
ZSHPAGE=zshexpn;;
ksh*glob*)
LESSQUERY='^ ksh-like Glob Operators'
ZSHPAGE=zshexpn;;
array*sub*)
LESSQUERY='^ Array Subscripts$'
ZSHPAGE=zshparam;;
array*)
LESSQUERY='^ARRAY PARAMETERS$'
ZSHPAGE=zshparam;;
positional*)
LESSQUERY='^POSITIONAL PARAMETERS$'
ZSHPAGE=zshparam;;
shell*(param*|var*)|env*)
LESSQUERY='^PARAMETERS SET BY THE SHELL$'
ZSHPAGE=zshparam;;
watchfmt*)
LESSQUERY='^ WATCHFMT$'
ZSHPAGE=zshparam;;
set*|(shell|spec)*op*)
LESSQUERY='^SPECIFYING OPTIONS$'
ZSHPAGE=zshoptions;;
single*opt*|short*flag*|single*letter*)
LESSQUERY='^SINGLE LETTER OPTIONS$'
ZSHPAGE=zshoptions;;
(shell|zsh)*builtin*)
LESSQUERY='^SHELL BUILTIN COMMANDS$'
ZSHPAGE=zshbuiltins;;
key*)
LESSQUERY='^KEYMAPS$'
ZSHPAGE=zshzle;;
widget*)
LESSQUERY='^USER-DEFINED WIDGETS$'
ZSHPAGE=zshzle;;
highlight*)
LESSQUERY='^CHARACTER HIGHLIGHTING$'
ZSHPAGE=zshzle;;
comp*wid*)
LESSQUERY='^ zshcompwid - zsh completion widgets'
ZSHPAGE=zshcompwid;;
complet*param*|*PREFIX*|*CURRENT*|*SUFFIX*)
LESSQUERY='^COMPLETION SPECIAL PARAMETERS$'
ZSHPAGE=zshcompwid;;
compstate)
LESSQUERY='^ compstate$'
ZSHPAGE=zshcompwid;;
compadd)
LESSQUERY='^ compadd \[ -akqQfenUlo12C '
ZSHPAGE=zshcompwid;;
compset)
LESSQUERY='^ compset -p number'
ZSHPAGE=zshcompwid;;
compcall)
LESSQUERY='^ compcall \[ -TD'
ZSHPAGE=zshcompwid;;
*match*)
LESSQUERY='^COMPLETION MATCHING CONTROL$'
ZSHPAGE=zshcompwid;;
*compsys*)
LESSQUERY='^ zshcompsys - zsh completion system'
ZSHPAGE=zshcompsys;;
compdef*)
LESSQUERY='^ compdef \[ -ane \]'
ZSHPAGE=zshcompsys;;
'#'compdef*)
LESSQUERY='^ #compdef name'
ZSHPAGE=zshcompsys;;
*completer*)
LESSQUERY='^ completer$'
ZSHPAGE=zshcompsys;;
*complet*|*'zstyle '*)
LESSQUERY='^COMPLETION SYSTEM CONFIGURATION$'
ZSHPAGE=zshcompsys;;
utility*func*|_argu*|_descr*)
LESSQUERY='^UTILITY FUNCTIONS$'
ZSHPAGE=zshcompsys;;
control*func*|_func*)
LESSQUERY='^CONTROL FUNCTIONS$'
ZSHPAGE=zshcompsys;;
calendar*)
LESSQUERY='^ calendar \[ -abdDsv'
ZSHPAGE=zshcalsys;;
calsys*)
LESSQUERY='^ zshcalsys - zsh calendar system'
ZSHPAGE=zshcalsys;;
tcp*)
LESSQUERY='^ zshtcpsys - zsh tcp system'
ZSHPAGE=zshtcpsys;;
ftp*|zftp*)
LESSQUERY='^ zshzftpsys - zftp function front-end'
ZSHPAGE=zshzftpsys;;
contrib*)
LESSQUERY='^ zshcontrib - user contributions to zsh'
ZSHPAGE=zshcontrib;;
special*func*)
LESSQUERY='^SPECIAL FUNCTIONS'
ZSHPAGE=zshmisc;;
color*comp*)
LESSQUERY='^ Colored completion listings'
ZSHPAGE=zshmodules;;
colors)
LESSQUERY='^ colors This function'
ZSHPAGE=zshcontrib;;
vcs*|version*control*)
LESSQUERY='^GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS$'
ZSHPAGE=zshcontrib;;
zle*)
LESSQUERY='^ZLE FUNCTIONS$'
ZSHPAGE=zshzle;;
mime*)
LESSQUERY='^MIME FUNCTIONS$'
ZSHPAGE=zshcontrib;;
zcalc*)
LESSQUERY='^ zcalc \[ -ef'
ZSHPAGE=zshcontrib;;
zmathfuncdef)
LESSQUERY='^ zmathfuncdef \['
ZSHPAGE=zshcontrib;;
other*func*)
LESSQUERY='^OTHER FUNCTIONS'
ZSHPAGE=zshcontrib;;
zargs)
LESSQUERY=' zargs \[ option'
ZSHPAGE=zshcontrib;;
tetris*)
LESSQUERY='^ tetris Zsh'
ZSHPAGE=zshcontrib;;
zed)
LESSQUERY='^ zed \[ -f'
ZSHPAGE=zshcontrib;;
zmv|zcp|zln|zkbd)
LESSQUERY='^ zmv \[ -finq'
ZSHPAGE=zshcontrib;;
zstyle+)
LESSQUERY='^ zstyle\+ context'
ZSHPAGE=zshcontrib;;
file*)
LESSQUERY='^FILES$'
ZSHPAGE=zsh;;
except*|throw|catch|always)
LESSQUERY='^EXCEPTION HANDLING$'
ZSHPAGE=zshcontrib;;
*)
LESSQUERY="$@";;
esac
man --pager="less -p'$LESSQUERY'" "$ZSHPAGE"
It uses less as the pager and enables less's termcap support for color man pages. Executing help
with no parameters or --help
or -h
lists reserved words and builtin commands. Typing help
with one of those words brings you right to the entry in the appropriate man page. I went through and narrowed down entries in specific man pages to optimize for speed/efficiency, as opposed to just using man ... zshall
. This help function finds a lot more than just reserved words and builtin commands. It will locate entries for modules, module commands, certain important completion commands such as compadd, compset, etc.
Many sections on things like arithmetic, completion, globbing, arrays, environment variables, exception handling are shown by typing help math
, help complet
, help glob
, help arrays
, help env
, help except
. There are wildcards and multiple match terms to make the help function more friendly. It's a fairly simple case statement with a little over 210 matching conditions. If nothing's matched it defaults to a zshall search. If the matching conditions don't show what you're looking for or seem to get in the way, type help --
following by your search terms to bypass all matching.
I included a lot of what the Zsh man pages cover, but it could be made smarter or more complete by including things like the underscore prefixed completion functions.
edit: I made a bindkey function for ^[h
(esc/alt + h). run-help
is bound there by default, and this replaces it.
_helpprefix(){
OLDBUFFER="$BUFFER"
zle backward-kill-word
BUFFER="help $CUTBUFFER"
zle accept-line
zle -U "$OLDBUFFER"
}
zle -N _helpprefix _helpprefix
bindkey '^[h' _helpprefix
What this does is cut out the last word typed, execute help
with that word and then it pushes back in the original line. So you can use it to run help on read
in a command like this:
find /usr -print0 | while IFS= read
You'll still be right at the end of your command after viewing the entry for read
.
Also something worth noting, if you ever need help with flags for a particular builtin, you can always add a -
after the command and hit tab to see short descriptions of each flag, e.g. read -
+ tab prints this out:
-A -- first name is taken as an array
-E -- input read is echoed
-d -- specify delimiter to terminate input instead of newline
-e -- input read is echoed and not assigned
-k -- specify number of characters to read
-q -- read y or n character from terminal
-r -- raw mode
-s -- suppress terminal echoing
-t -- test if input is available before reading
-u -- specify file descriptor to read from
-z -- read entry from editor buffer stack
Solution 7 - Linux
with Bash, "help" works:
jcomeau@intrepid:~/etc/apache2$ help until
until: until COMMANDS; do COMMANDS; done
Execute commands as long as a test does not succeed.
Expand and execute COMMANDS as long as the final command in the
`until' COMMANDS has an exit status which is not zero.
Exit Status:
Returns the status of the last command executed.
Solution 8 - Linux
Although this was more involved in the past, as of 2017 (Zsh v5.4),
getting a very fast and convenient help hotkey under your fingers is
as simple as putting the following into your .zshrc
(or equivalent
setup files):
unalias run-help
autoload run-help
bindkey "^[h" run-help
Now you can just start typing the full command you're trying to invoke (following opts/args — eg, "hello" — are ignored):
print hello«Alt-h»
and you'll see the run-help
listing.
print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C cols ]
[ -v name ] [ -xX tabstop ] [ -R [ -en ]] [ arg ... ]
With the `-f' option the arguments are printed as described by
printf...
A short listing is available for most commands, extracted from
zshbuiltins(1)
. I see 109 commands documented on my system in
/usr/share/zsh/5.4.2/help/
. Love this feature of Zsh!
Note that not everything is integrated into run-help and you'll
sometimes need to pull up zshall(1)
to find what you're looking for:
% run-help zargs
zargs is an autoload shell function
No manual entry for zargs
It's also great that this Alt-h
(or M-h
if you like) pattern has
essentially replaced any call you'd normally make to man
, for Zsh
commands or anything else. Instead of:
% foo - # oh wait, how does this work
% foo -^C
% ^p^a # recall, go to beginning of line
% man foo
it's now just:
% foo -«Alt-h»
Note for Emacs/vterm etc users: M-h
is probably bound to mark-paragraph
, and so this solution won't work. But you can instead do S-M-h
(that's adding Shift
) and get the desired behavior.
Solution 9 - Linux
The manpage for your shell will probably tell you.
Use the search feature of you pager if reading in the shell (or the find feature of you browser). For less
that is /search string
to start the search and n
to move to the next match.
Solution 10 - Linux
for me, setting HELPDIR
is the key.
[ -d /usr/share/zsh/help ] && HELPDIR=/usr/share/zsh/help
[ -d /usr/local/share/zsh/help ] && HELPDIR=/usr/local/share/zsh/help
alias help=run-help
bindkey '^[^H' run-help # ctrl alt h. Because of zsh-vi-mode delete-forward-word, I can't use ^[^H] here
The end
more intelligently
To use run-helpjust add:
autoload -Uz run-help-sudo # A very simple example
autoload -Uz run-help-ip # A good example
autoload -Uz run-help-git
Press ctrl+alt+h
after you type sudo ls
, you will see the manpage of ls
.
However, this does not show what we expect (maybe because of the use of shift
in run-help
? ) /usr/share/zsh/functions/Misc/run-help sudo ls
You can put this in .zshrc instead of autoload -Uz run-help-sudo
run-help-sudo(){
if [ $# -eq 0 ]; then
man sudo
else
man $1
fi
}
Prefer tldr to man? Want to find the bin?
h(){
/usr/bin/tldr $1 | bat
# todo https://zsh.sourceforge.io/Doc/Release/Expansion.html#Parameter-Expansion-Flags
# parameter expansion
VAR="$(/usr/bin/tldr $1)"
if [[ ${VAR} == *"No tldr entry for"* ]]
then
PAGER=LESS run-help $1
fi
echo ''
whence -ca $1
# todo
# man --pager="less --pattern 'MY_key word' " zshcontrib
# man --pager="less --pattern 'keyboard definition'" zshcontrib
# todo
# use run-help-git etc
}
from https://zsh.sourceforge.io/Doc/Release/User-Contributions.html
> if cmd is a file system path, it is first reduced to its rightmost component (the file name).
>
> Help is first sought by looking for a file named cmd in the directory
> named by the HELPDIR parameter. If no file is found, an assistant
> function, alias, or command named run-help-cmd is sought. If found,
> the assistant is executed with the rest of the current command line
> (everything after the command name cmd) as its arguments. When neither
> file nor assistant is found, the external command ‘man cmd’ is run. If
> no file is found, an assistant function, alias, or command named
> run-help-cmd
is sought
run-help
does is :
what (maybe have covered this answer's function? )
#!/bin/zsh
#
# Figure out where to get the best help, and get it.
#
# Install this function by placing it in your FPATH and then
# adding to your .zshrc the lines:
# unalias run-help
# autoload -Uz run-help
#
emulate -RL zsh
local HELPDIR=${HELPDIR:-/usr/share/zsh/help}
[[ $1 == "." ]] && 1="dot"
[[ $1 == ":" ]] && 1="colon"
# Check whether Util/helpfiles has been used to generate zsh help
if [[ $# == 0 || $1 == "-l" ]]
then
if [[ -d $HELPDIR ]]
then
echo "Here is a list of topics for which special help is available:"
echo ""
print -rc $HELPDIR/*(:t)
else
echo "There is no list of special help topics available at this time."
fi
return 0
elif [[ -n "${HELPDIR:-}" && -r $HELPDIR/$1 && $1 != compctl ]]
then
${=PAGER:-/usr/bin/pager} $HELPDIR/$1
return $?
fi
# No zsh help; use "whence" to figure out where else we might look
local what places noalias newline='
'
integer i=0 didman=0
places=( "${(@f)$(builtin whence -va $1)}" )
if [[ $places = *"not found"* && $1 != ${(Q)1} ]]; then
# Different when unquoted, so try stripping quotes.
places=( "${(@f)$(builtin whence -va ${(Q)1})}" )
if (( ${#places} )); then
set -- "${(Q)@}"
fi
# Quotation is significant to aliases, so suppress lookup.
noalias=1
fi
{
while ((i++ < $#places))
do
what=$places[$i]
[[ -n $noalias && $what = *" is an alias "* ]] && continue
builtin print -r $what
case $what in
(*( is an alias for (noglob|nocorrect))*)
[[ ${what[(w)7]:t} != ${what[(w)1]} ]] &&
run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)7]:t}
;;
(*( is an alias)*)
[[ ${what[(w)6]:t} != ${what[(w)1]} ]] &&
run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)6]:t}
;;
(*( is a * function))
case ${what[(w)1]} in
(comp*) man zshcompsys;;
(zf*) man zshftpsys;;
(run-help) man zshcontrib;;
(*) builtin functions ${what[(w)1]} | ${=PAGER:-/usr/bin/pager};;
esac;;
(*( is a * builtin))
case ${what[(w)1]} in
(compctl) man zshcompctl;;
(comp*) man zshcompwid;;
(bindkey|vared|zle) man zshzle;;
(*setopt) man zshoptions;;
(cap|getcap|setcap) ;&
(clone) ;&
(ln|mkdir|mv|rm|rmdir|sync) ;&
(sched) ;&
(echotc|echoti|sched|stat|zprof|zpty|zsocket|zstyle|ztcp) man zshmodules;;
(zftp) man zshftpsys;;
(*) man zshbuiltins;;
esac
;;
(*( is hashed to *))
man ${what[(w)-1]:t}
;;
(*( is a reserved word))
man zshmisc
;;
(*)
if ((! didman++))
then
if whence "run-help-$1:t" >/dev/null
then
local cmd_args
builtin getln cmd_args
builtin print -z "$cmd_args"
cmd_args=( ${(z)cmd_args} )
# Discard environment assignments, etc.
while [[ $cmd_args[1] != ${run_help_orig_cmd:-$1} ]]
do
shift cmd_args || return 1
done
eval "run-help-$1:t ${(q@)cmd_args[2,-1]}"
else
POSIXLY_CORRECT=1 man $@:t
fi
fi
;;
esac
if ((i < $#places && ! didman))
then
builtin print -nP "%SPress any key for more help or q to quit%s"
builtin read -k what
[[ $what != $newline ]] && echo
[[ $what == [qQ] ]] && break
fi
done
} always {
unset run_help_orig_cmd
}