1ZSHCONTRIB(1) General Commands Manual ZSHCONTRIB(1)
2
6 zshcontrib - user contributions to zsh
7
9 The Zsh source distribution includes a number of items contributed by
10 the user community. These are not inherently a part of the shell, and
11 some may not be available in every zsh installation. The most signifi‐
12 cant of these are documented here. For documentation on other contrib‐
13 uted items such as shell functions, look for comments in the function
14 source files.
15
17 Accessing On-Line Help
18 The key sequence ESC h is normally bound by ZLE to execute the run-help
19 widget (see zshzle(1)). This invokes the run-help command with the
20 command word from the current input line as its argument. By default,
21 run-help is an alias for the man command, so this often fails when the
22 command word is a shell builtin or a user-defined function. By
23 redefining the run-help alias, one can improve the on-line help pro‐
24 vided by the shell.
25 The helpfiles utility, found in the Util directory of the distribution,
27 is a Perl program that can be used to process the zsh manual to produce
28 a separate help file for each shell builtin and for many other shell
29 features as well. The autoloadable run-help function, found in Func‐
30 tions/Misc, searches for these helpfiles and performs several other
31 tests to produce the most complete help possible for the command.
32 There may already be a directory of help files on your system; look in
34 /usr/share/zsh or /usr/local/share/zsh and subdirectories below those,
35 or ask your system administrator.
36 To create your own help files with helpfiles, choose or create a direc‐
38 tory where the individual command help files will reside. For example,
39 you might choose ~/zsh_help. If you unpacked the zsh distribution in
40 your home directory, you would use the commands:
41 mkdir ~/zsh_help
43 cd ~/zsh_help
44 man zshall | colcrt - | \
45 perl ~/zsh-4.3.10/Util/helpfiles
46 Next, to use the run-help function, you need to add lines something
48 like the following to your .zshrc or equivalent startup file:
49 unalias run-help
51 autoload run-help
52 HELPDIR=~/zsh_help
53 The HELPDIR parameter tells run-help where to look for the help files.
55 If your system already has a help file directory installed, set HELPDIR
56 to the path of that directory instead.
57 Note that in order for `autoload run-help' to work, the run-help file
59 must be in one of the directories named in your fpath array (see zsh‐
60 param(1)). This should already be the case if you have a standard zsh
61 installation; if it is not, copy Functions/Misc/run-help to an appro‐
62 priate directory.
63 Recompiling Functions
65 If you frequently edit your zsh functions, or periodically update your
66 zsh installation to track the latest developments, you may find that
67 function digests compiled with the zcompile builtin are frequently out
68 of date with respect to the function source files. This is not usually
69 a problem, because zsh always looks for the newest file when loading a
70 function, but it may cause slower shell startup and function loading.
71 Also, if a digest file is explicitly used as an element of fpath, zsh
72 won't check whether any of its source files has changed.
73 The zrecompile autoloadable function, found in Functions/Misc, can be
75 used to keep function digests up to date.
76 zrecompile [ -qt ] [ name ... ]
78 zrecompile [ -qt ] -p args [ -- args ... ]
79 This tries to find *.zwc files and automatically re-compile them
80 if at least one of the original files is newer than the compiled
81 file. This works only if the names stored in the compiled files
82 are full paths or are relative to the directory that contains
83 the .zwc file.
84 In the first form, each name is the name of a compiled file or a
86 directory containing *.zwc files that should be checked. If no
87 arguments are given, the directories and *.zwc files in fpath
88 are used.
89 When -t is given, no compilation is performed, but a return sta‐
91 tus of zero (true) is set if there are files that need to be
92 re-compiled and non-zero (false) otherwise. The -q option qui‐
93 ets the chatty output that describes what zrecompile is doing.
94 Without the -t option, the return status is zero if all files
96 that needed re-compilation could be compiled and non-zero if
97 compilation for at least one of the files failed.
98 If the -p option is given, the args are interpreted as one or
100 more sets of arguments for zcompile, separated by `--'. For
101 example:
102 zrecompile -p \
104 -R ~/.zshrc -- \
105 -M ~/.zcompdump -- \
106 ~/zsh/comp.zwc ~/zsh/Completion/*/_*
107 This compiles ~/.zshrc into ~/.zshrc.zwc if that doesn't exist
109 or if it is older than ~/.zshrc. The compiled file will be
110 marked for reading instead of mapping. The same is done for
111 ~/.zcompdump and ~/.zcompdump.zwc, but this compiled file is
112 marked for mapping. The last line re-creates the file
113 ~/zsh/comp.zwc if any of the files matching the given pattern is
114 newer than it.
115 Without the -p option, zrecompile does not create function
117 digests that do not already exist, nor does it add new functions
118 to the digest.
119 The following shell loop is an example of a method for creating func‐
121 tion digests for all functions in your fpath, assuming that you have
122 write permission to the directories:
123 for ((i=1; i <= $#fpath; ++i)); do
125 dir=$fpath[i]
126 zwc=${dir:t}.zwc
127 if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
128 continue
129 fi
130 files=($dir/*(N-.))
131 if [[ -w $dir:h && -n $files ]]; then
132 files=(${${(M)files%/*/*}#/})
133 if ( cd $dir:h &&
134 zrecompile -p -U -z $zwc $files ); then
135 fpath[i]=$fpath[i].zwc
136 fi
137 fi
138 done
139 The -U and -z options are appropriate for functions in the default zsh
141 installation fpath; you may need to use different options for your per‐
142 sonal function directories.
143 Once the digests have been created and your fpath modified to refer to
145 them, you can keep them up to date by running zrecompile with no argu‐
146 ments.
147 Keyboard Definition
149 The large number of possible combinations of keyboards, workstations,
150 terminals, emulators, and window systems makes it impossible for zsh to
151 have built-in key bindings for every situation. The zkbd utility,
152 found in Functions/Misc, can help you quickly create key bindings for
153 your configuration.
154 Run zkbd either as an autoloaded function, or as a shell script:
156 zsh -f ~/zsh-4.3.10/Functions/Misc/zkbd
158 When you run zkbd, it first asks you to enter your terminal type; if
160 the default it offers is correct, just press return. It then asks you
161 to press a number of different keys to determine characteristics of
162 your keyboard and terminal; zkbd warns you if it finds anything out of
163 the ordinary, such as a Delete key that sends neither ^H nor ^?.
164 The keystrokes read by zkbd are recorded as a definition for an asso‐
166 ciative array named key, written to a file in the subdirectory .zkbd
167 within either your HOME or ZDOTDIR directory. The name of the file is
168 composed from the TERM, VENDOR and OSTYPE parameters, joined by
169 hyphens.
170 You may read this file into your .zshrc or another startup file with
172 the `source' or `.' commands, then reference the key parameter in bind‐
173 key commands, like this:
174 source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
176 [[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
177 [[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
178 # etc.
179 Note that in order for `autoload zkbd' to work, the zkdb file must be
181 in one of the directories named in your fpath array (see zshparam(1)).
182 This should already be the case if you have a standard zsh installa‐
183 tion; if it is not, copy Functions/Misc/zkbd to an appropriate direc‐
184 tory.
185 Dumping Shell State
187 Occasionally you may encounter what appears to be a bug in the shell,
188 particularly if you are using a beta version of zsh or a development
189 release. Usually it is sufficient to send a description of the problem
190 to one of the zsh mailing lists (see zsh(1)), but sometimes one of the
191 zsh developers will need to recreate your environment in order to track
192 the problem down.
193 The script named reporter, found in the Util directory of the distribu‐
195 tion, is provided for this purpose. (It is also possible to autoload
196 reporter, but reporter is not installed in fpath by default.) This
197 script outputs a detailed dump of the shell state, in the form of
198 another script that can be read with `zsh -f' to recreate that state.
199 To use reporter, read the script into your shell with the `.' command
201 and redirect the output into a file:
202 . ~/zsh-4.3.10/Util/reporter > zsh.report
204 You should check the zsh.report file for any sensitive information such
206 as passwords and delete them by hand before sending the script to the
207 developers. Also, as the output can be voluminous, it's best to wait
208 for the developers to ask for this information before sending it.
209 You can also use reporter to dump only a subset of the shell state.
211 This is sometimes useful for creating startup files for the first time.
212 Most of the output from reporter is far more detailed than usually is
213 necessary for a startup file, but the aliases, options, and zstyles
214 states may be useful because they include only changes from the
215 defaults. The bindings state may be useful if you have created any of
216 your own keymaps, because reporter arranges to dump the keymap creation
217 commands as well as the bindings for every keymap.
218 As is usual with automated tools, if you create a startup file with
220 reporter, you should edit the results to remove unnecessary commands.
221 Note that if you're using the new completion system, you should not
222 dump the functions state to your startup files with reporter; use the
223 compdump function instead (see zshcompsys(1)).
224 reporter [ state ... ]
226 Print to standard output the indicated subset of the current
227 shell state. The state arguments may be one or more of:
228 all Output everything listed below.
230 aliases
231 Output alias definitions.
232 bindings
233 Output ZLE key maps and bindings.
234 completion
235 Output old-style compctl commands. New completion is
236 covered by functions and zstyles.
237 functions
238 Output autoloads and function definitions.
239 limits Output limit commands.
240 options
241 Output setopt commands.
242 styles Same as zstyles.
243 variables
244 Output shell parameter assignments, plus export commands
245 for any environment variables.
246 zstyles
247 Output zstyle commands.
248 If the state is omitted, all is assumed.
250 With the exception of `all', every state can be abbreviated by any pre‐
252 fix, even a single letter; thus a is the same as aliases, z is the same
253 as zstyles, etc.
254 Manipulating Hook Functions
256 add-zsh-hook [-dD] hook function
257 Several functions are special to the shell, as described in the
258 section SPECIAL FUNCTIONS, see zshmisc(1), in that they are
259 automatic called at a specific point during shell execution.
260 Each has an associated array consisting of names of functions to
261 be called at the same point; these are so-called `hook func‐
262 tions'. The shell function add-zsh-hook provides a simple way
263 of adding or removing functions from the array.
264 hook is one of chpwd, periodic, precmd or preexec, the special
266 functions in question.
267 functions is name of an ordinary shell function. If no options
269 are given this will be added to the array of functions to be
270 executed. in the given context.
271 If the option -d is given, the function is removed from the
273 array of functions to be executed.
274 If the option -D is given, the function is treated as a pattern
276 and any matching names of functions are removed from the array
277 of functions to be executed.
278
280 In a lot of cases, it is nice to automatically retrieve information
281 from version control systems (VCSs), such as subversion, CVS or git, to
282 be able to provide it to the user; possibly in the user's prompt. So
283 that you can instantly tell on which branch you are currently on, for
284 example.
285 In order to do that, you may use the vcs_info function.
287 The following VCSs are supported, showing the abbreviated name by which
289 they are referred to within the system:
290 Bazaar (bzr)
291 http://bazaar-vcs.org/
292 Codeville (cdv)
293 http://codeville.org/
294 Concurrent Versioning System (cvs)
295 http://www.nongnu.org/cvs/
296 darcs http://darcs.net/
297 git http://git.or.cz/
298 GNU arch (tla)
299 http://www.gnu.org/software/gnu-arch/
300 Mercurial (hg)
301 http://selenic.com/mercurial/
302 Monotone (mtn)
303 http://monotone.ca/
304 Perforce (p4)
305 http://www.perforce.com/
306 Subversion (svn)
307 http://subversion.tigris.org/
308 SVK (svk)
309 http://svk.bestpractical.com/
310 To load vcs_info:
312 autoload -Uz vcs_info
314 It can be used in any existing prompt, because it does not require any
316 $psvar entries to be left available.
317 Quickstart
319 To get this feature working quickly (including colors), you can do the
320 following (assuming, you loaded vcs_info properly - see above):
321 zstyle ':vcs_info:*' actionformats \
323 '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
324 zstyle ':vcs_info:*' formats \
325 '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
326 zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
327 precmd () { vcs_info }
328 PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '
329 Obviously, the last two lines are there for demonstration: You need to
331 call vcs_info from your precmd function. Once that is done you need a
332 single quoted '${vcs_info_msg_0_}' in your prompt.
333 To be able to use '${vcs_info_msg_0_}' directly in your prompt like
335 this, you will need to have the PROMPT_SUBST option enabled.
336 Now call the vcs_info_printsys utility from the command line:
338 % vcs_info_printsys
340 ## list of supported version control backends:
341 ## disabled systems are prefixed by a hash sign (#)
342 bzr
343 cdv
344 cvs
345 darcs
346 git
347 hg
348 mtn
349 p4
350 svk
351 svn
352 tla
353 ## flavours (cannot be used in the enable or disable styles; they
354 ## are enabled and disabled with their master [git-svn -> git])
355 ## they *can* be used contexts: ':vcs_info:git-svn:*'.
356 git-p4
357 git-svn
358 You may not want all of these because there is no point in running the
360 code to detect systems you do not use. So there is a way to disable
361 some backends altogether:
362 zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla
364 You may also pick a few from that list and enable only those:
366 zstyle ':vcs_info:*' enable git cvs svn
368 If you rerun vcs_info_printsys after one of these commands, you will
370 see the backends listed in the disable style (or backends not in the
371 enable style - if you used that) marked as disabled by a hash sign.
372 That means the detection of these systems is skipped completely. No
373 wasted time there.
374 Configuration
376 The vcs_info feature can be configured via zstyle.
377 First, the context in which we are working:
379 :vcs_info:<vcs-string>:<user-context>:<repo-root-name>
380 <vcs-string>
382 is one of: git, git-svn, git-p4, hg, darcs, bzr, cdv, mtn, svn,
383 cvs, svk, tla or p4.
384 <user-context>
386 is a freely configurable string, assignable by the user as the
387 first argument to vcs_info (see its description below).
388 <repo-root-name>
390 is the name of a repository in which you want a style to match.
391 So, if you want a setting specific to /usr/src/zsh, with that
392 being a cvs checkout, you can set <repo-root-name> to zsh to
393 make it so.
394 There are three special values for <vcs-string>: The first is named
396 -init-, that is in effect as long as there was no decision what vcs
397 backend to use. The second is -preinit-; it is used before vcs_info is
398 run, when initializing the data exporting variables. The third special
399 value is formats and is used by the vcs_info_lastmsg for looking up its
400 styles.
401 The initial value of <repo-root-name> is -all- and it is replaced with
403 the actual name, as soon as it is known. Only use this part of the con‐
404 text for defining the formats, actionformats or branchformat styles. As
405 it is guaranteed that <repo-root-name> is set up correctly for these
406 only. For all other styles, just use '*' instead.
407 There are two pre-defined values for <user-context>:
409 default
410 the one used if none is specified
411 command
412 used by vcs_info_lastmsg to lookup its styles
413 You can of course use ':vcs_info:*' to match all VCSs in all user-con‐
415 texts at once.
416 This is a description of all styles that are looked up.
418 formats
420 A list of formats, used when actionformats is not used (which is
421 most of the time).
422 actionformats
424 A list of formats, used if a there is a special action going on
425 in your current repository; (like an interactive rebase or a
426 merge conflict).
427 branchformat
429 Some backends replace %b in the formats and actionformats styles
430 above, not only by a branch name but also by a revision number.
431 This style let's you modify how that string should look like.
432 nvcsformats
434 These "formats" are exported, when we didn't detect a version
435 control system for the current directory. This is useful, if you
436 want vcs_info to completely take over the generation of your
437 prompt. You would do something like PS1='${vcs_info_msg_0_}' to
438 accomplish that.
439 stgitformat
441 The git backend replaces %m in the formats and actionformats
442 styles with stgit-specific information for stgit-initialized
443 branches. This style let's you modify how that string should
444 look like.
445 max-exports
447 Defines the maximum number if vcs_info_msg_*_ variables vcs_info
448 will export.
449 enable A list of backends you want to use. Checked in the -init- con‐
451 text. If this list contains an item called NONE no backend is
452 used at all and vcs_info will do nothing. If this list contains
453 ALL vcs_info will use all backends known to it. Only with ALL in
454 enable, the disable style has any effect. ALL and NONE are actu‐
455 ally tested case insensitively.
456 disable
458 A list of VCSs, you don't want vcs_info to test for repositories
459 (checked in the -init- context, too). Only used if enable con‐
460 tains ALL.
461 disable-patterns
463 A list of patterns that are checked against $PWD. If a pattern
464 matches, vcs_info will be disabled. This style is checked in the
465 :vcs_info:-init-:*:-all- context.
466 Say, ~/.zsh is a directory under version control, in which you
468 do not want vcs_info to be active, do:
469 zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh(|/*)"
470 check-for-changes
472 If enabled, this style (currently only used by the git backend)
473 causes the %c and %u format escapes to be filled with informa‐
474 tion. The strings filled into these escapes can be controlled
475 via the stagedstr and unstagedstr styles.
476 Note, that the actions taken if this style is enabled are poten‐
478 tially expensive (read: they take time, depending on how big the
479 current repository is). Therefore, it is disabled by default.
480 stagedstr
482 This string will be used in the %c escape if there are staged
483 changes in the repository.
484 unstagedstr
486 This string will be used in the %u escape if there are unstaged
487 changes in the repository.
488 command
490 This style causes vcs_info to use the supplied string as the
491 command to use as the vcs's binary. Note, that setting this in
492 ':vcs_info:*' is not a good idea.
493 If the value of this style is empty (which is the default), the
495 used binary name is the name of the backend in use (e.g. svn is
496 used in a svn repository).
497 The repo-root-name part in the context is always the default
499 -all- when this style is looked up.
500 For example, this style can be used to use binaries from
502 non-default installation directories. Assume, git is installed
503 in /usr/bin, but your sysadmin installed a newer version in
504 /usr/bin/local. Now, instead of changing the order of your $PATH
505 parameter, you can do this:
506 zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git
507 use-server
509 This is used by the Perforce backend (p4) to decide if it should
510 contact the Perforce server to find out if a directory is man‐
511 aged by Perforce. This is the only reliable way of doing this,
512 but runs the risk of a delay if the server name cannot be found.
513 If the server (more specifically, the host:port pair describing
514 the server) cannot be contacted its name is put into the asso‐
515 ciative array vcs_info_p4_dead_servers and not contacted again
516 during the session until it is removed by hand. If you do not
517 set this style, the p4 backend is only usable if you have set
518 the environment variable P4CONFIG to a file name and have corre‐
519 sponding files in the root directories of each Perforce client.
520 See comments in the function VCS_INFO_detect_p4 for more detail.
521 use-simple
523 If there are two different ways of gathering information, you
524 can select the simpler one by setting this style to true; the
525 default is to use the not-that-simple code, which is potentially
526 a lot slower but might be more accurate in all possible cases.
527 This style is only used by the bzr backend.
528 get-revision
530 If set to true, vcs_info goes the extra mile to figure out the
531 revision of a repository's work tree (currently for the git and
532 hg backends, where this kind of information is not always
533 vital). For git, the hash value of the currently checked out
534 commit is available via the %i expansion. With hg, the local
535 revision number is available via %i and the corresponding global
536 hash is available via %m. If this style is set in the hg con‐
537 text, the backend supports the branchformat style.
538 use-prompt-escapes
540 Determines if we assume that the assembled string from vcs_info
541 includes prompt escapes. (Used by vcs_info_lastmsg.)
542 The default values for these styles in all contexts are:
544 formats
546 " (%s)-[%b|%a]-"
547 actionformats
548 " (%s)-[%b]-"
549 branchformat
550 "%b:%r" (for bzr, svn and svk)
551 nvcsformats
552 ""
553 stgitformat
554 " %p (%c)"
555 max-exports
556 2
557 enable ALL
558 disable
559 (empty list)
560 disable-patterns
561 (empty list)
562 check-for-changes
563 false
564 stagedstr
565 (string: "S")
566 unstagedstr
567 (string: "U")
568 command
569 (empty string)
570 use-server
571 false
572 use-simple
573 false
574 get-revision
575 false
576 use-prompt-escapes
577 true
578 In normal formats and actionformats, the following replacements are
580 done:
581 %s The vcs in use (git, hg, svn etc.)
583 %b Information about the current branch.
584 %a An identifier, that describes the action. Only makes sense in
585 actionformats.
586 %i The current revision number or identifier.
587 %c The string from the stagedstr style if there are staged changes
588 in the repository.
589 %u The string from the unstagedstr style if there are unstaged
590 changes in the repository.
591 %R base directory of the repository.
592 %r repository name. If %R is /foo/bar/repoXY, %r is repoXY.
593 %S subdirectory within a repository. If $PWD is
594 /foo/bar/reposXY/beer/tasty, %S is beer/tasty.
595 %m A "misc" replacement. It is at the discretion of the backend to
596 decide what this replacement expands to. It is currently used by
597 the hg and git backends. The hg backend replaces %m with the
598 global hash value of the current revision and the git backend
599 replaces it with the string from the stgitformat style.
600 In branchformat these replacements are done:
602 %b the branch name
604 %r the current revision number
605 In stgitformat these replacements are done:
607 %p the name of the patch currently on top of the stack
609 %c the number of unapplied patches
610 Not all vcs backends have to support all replacements. For nvcsformats
612 no replacements are performed at all. It is just a string.
613 Oddities
615 If you want to use the %b (bold off) prompt expansion in formats, which
616 expands %b itself, use %%b. That will cause the vcs_info expansion to
617 replace %%b with %b. So zsh's prompt expansion mechanism can handle it.
618 Similarly, to hand down %b from branchformat, use %%%%b. Sorry for this
619 inconvenience, but it cannot be easily avoided. Luckily we do not clash
620 with a lot of prompt expansions and this only needs to be done for
621 those.
622 Function descriptions (public API)
624 vcs_info [user-context]
625 The main function, that runs all backends and assembles all data
626 into ${vcs_info_msg_*_}. This is the function you want to call
627 from precmd if you want to include up-to-date information in
628 your prompt (see Variable description below). If an argument is
629 given, that string will be used instead of default in the
630 user-context field of the style context.
631 vcs_info_lastmsg
633 Outputs the last ${vcs_info_msg_*_} value. Takes into account
634 the value of the use-prompt-escapes style in ':vcs_info:for‐
635 mats:command:-all-'. It also only prints max-exports values.
636 vcs_info_printsys [user-context]
638 Prints a list of all supported version control systems. Useful
639 to find out possible contexts (and which of them are enabled) or
640 values for the disable style.
641 vcs_info_setsys
643 Initializes vcs_info's internal list of available backends. With
644 this function, you can add support for new VCSs without restart‐
645 ing the shell.
646 All functions named VCS_INFO_* are for internal use only.
648 Variable description
650 ${vcs_info_msg_N_} (Note the trailing underscore)
651 Where N is an integer, eg: vcs_info_msg_0_ These variables are
652 the storage for the informational message the last vcs_info call
653 has assembled. These are strongly connected to the formats,
654 actionformats and nvcsformats styles described above. Those
655 styles are lists. The first member of that list gets expanded
656 into ${vcs_info_msg_0_}, the second into ${vcs_info_msg_1_} and
657 the Nth into ${vcs_info_msg_N-1_}. These parameters are exported
658 into the environment. (See the max-exports style above.)
659 All variables named VCS_INFO_* are for internal use only.
661 Examples
663 Don't use vcs_info at all (even though it's in your prompt):
664 zstyle ':vcs_info:*' enable NONE
665 Disable the backends for bzr and svk:
667 zstyle ':vcs_info:*' disable bzr svk
668 Disable everything but bzr and svk:
670 zstyle ':vcs_info:*' enable bzr svk
671 Provide a special formats for git:
673 zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]'
674 zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'
675 Use the quicker bzr backend
677 zstyle ':vcs_info:bzr:*' use-simple true
678 If you do use use-simple, please report if it does
680 `the-right-thing[tm]'.
681 Display the revision number in yellow for bzr and svn:
683 zstyle ':vcs_info:(svn|bzr):*' branchformat '%b%{'${fg[yellow]}'%}:%r'
684 If you want colors, make sure you enclose the color codes in %{...%},
686 if you want to use the string provided by vcs_info in prompts.
687 Here is how to print the vcs information as a command (not in a
689 prompt):
690 alias vcsi='vcs_info command; vcs_info_lastmsg'
691 This way, you can even define different formats for output via
693 vcs_info_lastmsg in the ':vcs_info:formats:command:*' namespace.
694
696 Installation
697 You should make sure all the functions from the Functions/Prompts
698 directory of the source distribution are available; they all begin with
699 the string `prompt_' except for the special function`promptinit'. You
700 also need the `colors' function from Functions/Misc. All of these
701 functions may already have been installed on your system; if not, you
702 will need to find them and copy them. The directory should appear as
703 one of the elements of the fpath array (this should already be the case
704 if they were installed), and at least the function promptinit should be
705 autoloaded; it will autoload the rest. Finally, to initialize the use
706 of the system you need to call the promptinit function. The following
707 code in your .zshrc will arrange for this; assume the functions are
708 stored in the directory ~/myfns:
709 fpath=(~/myfns $fpath)
711 autoload -U promptinit
712 promptinit
713 Theme Selection
715 Use the prompt command to select your preferred theme. This command
716 may be added to your .zshrc following the call to promptinit in order
717 to start zsh with a theme already selected.
718 prompt [ -c | -l ]
720 prompt [ -p | -h ] [ theme ... ]
721 prompt [ -s ] theme [ arg ... ]
722 Set or examine the prompt theme. With no options and a theme
723 argument, the theme with that name is set as the current theme.
724 The available themes are determined at run time; use the -l
725 option to see a list. The special theme `random' selects at
726 random one of the available themes and sets your prompt to that.
727 In some cases the theme may be modified by one or more argu‐
729 ments, which should be given after the theme name. See the help
730 for each theme for descriptions of these arguments.
731 Options are:
733 -c Show the currently selected theme and its parameters, if
735 any.
736 -l List all available prompt themes.
737 -p Preview the theme named by theme, or all themes if no
738 theme is given.
739 -h Show help for the theme named by theme, or for the prompt
740 function if no theme is given.
741 -s Set theme as the current theme and save state.
742 prompt_theme_setup
744 Each available theme has a setup function which is called by the
745 prompt function to install that theme. This function may define
746 other functions as necessary to maintain the prompt, including
747 functions used to preview the prompt or provide help for its
748 use. You should not normally call a theme's setup function
749 directly.
750
752 Widgets
753 These functions all implement user-defined ZLE widgets (see zshzle(1))
754 which can be bound to keystrokes in interactive shells. To use them,
755 your .zshrc should contain lines of the form
756 autoload function
758 zle -N function
759 followed by an appropriate bindkey command to associate the function
761 with a key sequence. Suggested bindings are described below.
762 bash-style word functions
764 If you are looking for functions to implement moving over and
765 editing words in the manner of bash, where only alphanumeric
766 characters are considered word characters, you can use the func‐
767 tions described in the next section. The following is suffi‐
768 cient:
769 autoload -U select-word-style
771 select-word-style bash
772 forward-word-match, backward-word-match
774 kill-word-match, backward-kill-word-match
775 transpose-words-match, capitalize-word-match
776 up-case-word-match, down-case-word-match
777 select-word-style, match-word-context, match-words-by-style
778 The eight `-match' functions are drop-in replacements for the
779 builtin widgets without the suffix. By default they behave in a
780 similar way. However, by the use of styles and the function
781 select-word-style, the way words are matched can be altered.
782 The simplest way of configuring the functions is to use
784 select-word-style, which can either be called as a normal func‐
785 tion with the appropriate argument, or invoked as a user-defined
786 widget that will prompt for the first character of the word
787 style to be used. The first time it is invoked, the eight
788 -match functions will automatically replace the builtin ver‐
789 sions, so they do not need to be loaded explicitly.
790 The word styles available are as follows. Only the first char‐
792 acter is examined.
793 bash Word characters are alphanumeric characters only.
795 normal As in normal shell operation: word characters are
797 alphanumeric characters plus any characters present in
798 the string given by the parameter $WORDCHARS.
799 shell Words are complete shell command arguments, possibly
801 including complete quoted strings, or any tokens special
802 to the shell.
803 whitespace
805 Words are any set of characters delimited by whitespace.
806 default
808 Restore the default settings; this is usually the same as
809 `normal'.
810 All but `default' can be input as an upper case character, which
812 has the same effect but with subword matching turned on. In
813 this case, words with upper case characters are treated spe‐
814 cially: each separate run of upper case characters, or an upper
815 case character followed by any number of other characters, is
816 considered a word. The style subword-range can supply an alter‐
817 native character range to the default `[:upper:]'; the value of
818 the style is treated as the contents of a `[...]' pattern (note
819 that the outer brackets should not be supplied, only those sur‐
820 rounding named ranges).
821 More control can be obtained using the zstyle command, as
823 described in zshmodules(1). Each style is looked up in the con‐
824 text :zle:widget where widget is the name of the user-defined
825 widget, not the name of the function implementing it, so in the
826 case of the definitions supplied by select-word-style the appro‐
827 priate contexts are :zle:forward-word, and so on. The function
828 select-word-style itself always defines styles for the context
829 `:zle:*' which can be overridden by more specific (longer) pat‐
830 terns as well as explicit contexts.
831 The style word-style specifies the rules to use. This may have
833 the following values.
834 normal Use the standard shell rules, i.e. alphanumerics and
836 $WORDCHARS, unless overridden by the styles word-chars or
837 word-class.
838 specified
840 Similar to normal, but only the specified characters, and
841 not also alphanumerics, are considered word characters.
842 unspecified
844 The negation of specified. The given characters are
845 those which will not be considered part of a word.
846 shell Words are obtained by using the syntactic rules for gen‐
848 erating shell command arguments. In addition, special
849 tokens which are never command arguments such as `()' are
850 also treated as words.
851 whitespace
853 Words are whitespace-delimited strings of characters.
854 The first three of those rules usually use $WORDCHARS, but the
856 value in the parameter can be overridden by the style
857 word-chars, which works in exactly the same way as $WORDCHARS.
858 In addition, the style word-class uses character class syntax to
859 group characters and takes precedence over word-chars if both
860 are set. The word-class style does not include the surrounding
861 brackets of the character class; for example, `-:[:alnum:]' is a
862 valid word-class to include all alphanumerics plus the charac‐
863 ters `-' and `:'. Be careful including `]', `^' and `-' as
864 these are special inside character classes.
865 word-style may also have `-subword' appended to its value to
867 turn on subword matching, as described above.
868 The style skip-chars is mostly useful for transpose-words and
870 similar functions. If set, it gives a count of characters
871 starting at the cursor position which will not be considered
872 part of the word and are treated as space, regardless of what
873 they actually are. For example, if
874 zstyle ':zle:transpose-words' skip-chars 1
876 has been set, and transpose-words-match is called with the cur‐
878 sor on the X of fooXbar, where X can be any character, then the
879 resulting expression is barXfoo.
880 Finer grained control can be obtained by setting the style
882 word-context to an array of pairs of entries. Each pair of
883 entries consists of a pattern and a subcontext. The shell argu‐
884 ment the cursor is on is matched against each pattern in turn
885 until one matches; if it does, the context is extended by a
886 colon and the corresponding subcontext. Note that the test is
887 made against the original word on the line, with no stripping of
888 quotes. Special handling is done between words: the current
889 context is examined and if it contains the string back, the word
890 before the cursor is considered, else the word after cursor is
891 considered. Some examples are given below.
892 Here are some examples of use of the styles, actually taken from
894 the simplified interface in select-word-style:
895 zstyle ':zle:*' word-style standard
897 zstyle ':zle:*' word-chars ''
898 Implements bash-style word handling for all widgets, i.e. only
900 alphanumerics are word characters; equivalent to setting the
901 parameter WORDCHARS empty for the given context.
902 style ':zle:*kill*' word-style space
904 Uses space-delimited words for widgets with the word `kill' in
906 the name. Neither of the styles word-chars nor word-class is
907 used in this case.
908 Here are some examples of use of the word-context style to
910 extend the context.
911 zstyle ':zle:*' word-context "*/*" file "[[:space:]]" whitespace
913 zstyle ':zle:transpose-words:whitespace' word-style shell
914 zstyle ':zle:transpose-words:filename' word-style normal
915 zstyle ':zle:transpose-words:filename' word-chars ''
916 This provides two different ways of using transpose-words
918 depending on whether the cursor is on whitespace between words
919 or on a filename, here any word containing a /. On whitespace,
920 complete arguments as defined by standard shell rules will be
921 transposed. In a filename, only alphanumerics will be trans‐
922 posed. Elsewhere, words will be transposed using the default
923 style for :zle:transpose-words.
924 The word matching and all the handling of zstyle settings is
926 actually implemented by the function match-words-by-style. This
927 can be used to create new user-defined widgets. The calling
928 function should set the local parameter curcontext to :zle:wid‐
929 get, create the local parameter matched_words and call
930 match-words-by-style with no arguments. On return,
931 matched_words will be set to an array with the elements: (1) the
932 start of the line (2) the word before the cursor (3) any
933 non-word characters between that word and the cursor (4) any
934 non-word character at the cursor position plus any remaining
935 non-word characters before the next word, including all charac‐
936 ters specified by the skip-chars style, (5) the word at or fol‐
937 lowing the cursor (6) any non-word characters following that
938 word (7) the remainder of the line. Any of the elements may be
939 an empty string; the calling function should test for this to
940 decide whether it can perform its function.
941 It is possible to pass options with arguments to
943 match-words-by-style to override the use of styles. The options
944 are:
945 -w word-style
946 -s skip-chars
947 -c word-class
948 -C word-chars
949 -r subword-range
950 For example, match-words-by-style -w shell -c 0 may be used to
952 extract the command argument around the cursor.
953 The word-context style is implemented by the function
955 match-word-context. This should not usually need to be called
956 directly.
957 delete-whole-word-match
959 This is another function which works like the -match functions
960 described immediately above, i.e. using styles to decide the
961 word boundaries. However, it is not a replacement for any
962 existing function.
963 The basic behaviour is to delete the word around the cursor.
965 There is no numeric prefix handling; only the single word around
966 the cursor is considered. If the widget contains the string
967 kill, the removed text will be placed in the cutbuffer for
968 future yanking. This can be obtained by defining
969 kill-whole-word-match as follows:
970 zle -N kill-whole-word-match delete-whole-word-match
972 and then binding the widget kill-whole-word-match.
974 copy-earlier-word
976 This widget works like a combination of insert-last-word and
977 copy-prev-shell-word. Repeated invocations of the widget
978 retrieve earlier words on the relevant history line. With a
979 numeric argument N, insert the Nth word from the history line; N
980 may be negative to count from the end of the line.
981 If insert-last-word has been used to retrieve the last word on a
983 previous history line, repeated invocations will replace that
984 word with earlier words from the same line.
985 Otherwise, the widget applies to words on the line currently
987 being edited. The widget style can be set to the name of
988 another widget that should be called to retrieve words. This
989 widget must accept the same three arguments as insert-last-word.
990 cycle-completion-positions
992 After inserting an unambiguous string into the command line, the
993 new function based completion system may know about multiple
994 places in this string where characters are missing or differ
995 from at least one of the possible matches. It will then place
996 the cursor on the position it considers to be the most interest‐
997 ing one, i.e. the one where one can disambiguate between as many
998 matches as possible with as little typing as possible.
999 This widget allows the cursor to be easily moved to the other
1001 interesting spots. It can be invoked repeatedly to cycle
1002 between all positions reported by the completion system.
1003 edit-command-line
1005 Edit the command line using your visual editor, as in ksh.
1006 bindkey -M vicmd v edit-command-line
1008 history-search-end
1010 This function implements the widgets history-begin‐
1011 ning-search-backward-end and history-beginning-search-for‐
1012 ward-end. These commands work by first calling the correspond‐
1013 ing builtin widget (see `History Control' in zshzle(1)) and then
1014 moving the cursor to the end of the line. The original cursor
1015 position is remembered and restored before calling the builtin
1016 widget a second time, so that the same search is repeated to
1017 look farther through the history.
1018 Although you autoload only one function, the commands to use it
1020 are slightly different because it implements two widgets.
1021 zle -N history-beginning-search-backward-end \
1023 history-search-end
1024 zle -N history-beginning-search-forward-end \
1025 history-search-end
1026 bindkey '\e^P' history-beginning-search-backward-end
1027 bindkey '\e^N' history-beginning-search-forward-end
1028 history-beginning-search-menu
1030 This function implements yet another form of history searching.
1031 The text before the cursor is used to select lines from the his‐
1032 tory, as for history-beginning-search-backward except that all
1033 matches are shown in a numbered menu. Typing the appropriate
1034 digits inserts the full history line. Note that leading zeroes
1035 must be typed (they are only shown when necessary for removing
1036 ambiguity). The entire history is searched; there is no dis‐
1037 tinction between forwards and backwards.
1038 With a prefix argument, the search is not anchored to the start
1040 of the line; the string typed by the use may appear anywhere in
1041 the line in the history.
1042 If the widget name contains `-end' the cursor is moved to the
1044 end of the line inserted. If the widget name contains `-space'
1045 any space in the text typed is treated as a wildcard and can
1046 match anything (hence a leading space is equivalent to giving a
1047 prefix argument). Both forms can be combined, for example:
1048 zle -N history-beginning-search-menu-space-end \
1050 history-beginning-search-menu
1051 history-pattern-search
1053 The function history-pattern-search implements widgets which
1054 prompt for a pattern with which to search the history backwards
1055 or forwards. The pattern is in the usual zsh format, however
1056 the first character may be ^ to anchor the search to the start
1057 of the line, and the last character may be $ to anchor the
1058 search to the end of the line. If the search was not anchored
1059 to the end of the line the cursor is positioned just after the
1060 pattern found.
1061 The commands to create bindable widgets are similar to those in
1063 the example immediately above:
1064 autoload -U history-pattern-search
1066 zle -N history-pattern-search-backward history-pattern-search
1067 zle -N history-pattern-search-forward history-pattern-search
1068 up-line-or-beginning-search, down-line-or-beginning-search
1070 These widgets are similar to the builtin functions
1071 up-line-or-search and down-line-or-search: if in a multiline
1072 buffer they move up or down within the buffer, otherwise they
1073 search for a history line matching the start of the current
1074 line. In this case, however, they search for a line which
1075 matches the current line up to the current cursor position, in
1076 the manner of history-beginning-search-backward and -forward,
1077 rather than the first word on the line.
1078 incarg Typing the keystrokes for this widget with the cursor placed on
1080 or to the left of an integer causes that integer to be incre‐
1081 mented by one. With a numeric prefix argument, the number is
1082 incremented by the amount of the argument (decremented if the
1083 prefix argument is negative). The shell parameter incarg may be
1084 set to change the default increment to something other than one.
1085 bindkey '^X+' incarg
1087 incremental-complete-word
1089 This allows incremental completion of a word. After starting
1090 this command, a list of completion choices can be shown after
1091 every character you type, which you can delete with ^H or DEL.
1092 Pressing return accepts the completion so far and returns you to
1093 normal editing (that is, the command line is not immediately
1094 executed). You can hit TAB to do normal completion, ^G to abort
1095 back to the state when you started, and ^D to list the matches.
1096 This works only with the new function based completion system.
1098 bindkey '^Xi' incremental-complete-word
1100 insert-composed-char
1102 This function allows you to compose characters that don't appear
1103 on the keyboard to be inserted into the command line. The com‐
1104 mand is followed by two keys corresponding to ASCII characters
1105 (there is no prompt). For accented characters, the two keys are
1106 a base character followed by a code for the accent, while for
1107 other special characters the two characters together form a
1108 mnemonic for the character to be inserted. The two-character
1109 codes are a subset of those given by RFC 1345 (see for example
1110 http://www.faqs.org/rfcs/rfc1345.html).
1111 The function may optionally be followed by up to two characters
1113 which replace one or both of the characters read from the key‐
1114 board; if both characters are supplied, no input is read. For
1115 example, insert-composed-char a: can be used within a widget to
1116 insert an a with umlaut into the command line. This has the
1117 advantages over use of a literal character that it is more por‐
1118 table.
1119 For best results zsh should have been built with support for
1121 multibyte characters (configured with --enable-multibyte); how‐
1122 ever, the function works for the limited range of characters
1123 available in single-byte character sets such as ISO-8859-1.
1124 The character is converted into the local representation and
1126 inserted into the command line at the cursor position. (The
1127 conversion is done within the shell, using whatever facilities
1128 the C library provides.) With a numeric argument, the character
1129 and its code are previewed in the status line
1130 The function may be run outside zle in which case it prints the
1132 character (together with a newline) to standard output. Input
1133 is still read from keystrokes.
1134 See insert-unicode-char for an alternative way of inserting Uni‐
1136 code characters using their hexadecimal character number.
1137 The set of accented characters is reasonably complete up to Uni‐
1139 code character U+0180, the set of special characters less so.
1140 However, it it is very sporadic from that point. Adding new
1141 characters is easy, however; see the function define-com‐
1142 posed-chars. Please send any additions to zsh-workers@sun‐
1143 site.dk.
1144 The codes for the second character when used to accent the first
1146 are as follows. Note that not every character can take every
1147 accent.
1148 ! Grave.
1149 ' Acute.
1150 > Circumflex.
1151 ? Tilde. (This is not ~ as RFC 1345 does not assume that
1152 character is present on the keyboard.)
1153 - Macron. (A horizontal bar over the base character.)
1154 ( Breve. (A shallow dish shape over the base character.)
1155 . Dot above the base character, or in the case of i no dot,
1156 or in the case of L and l a centered dot.
1157 : Diaeresis (Umlaut).
1158 c Cedilla.
1159 _ Underline, however there are currently no underlined
1160 characters.
1161 / Stroke through the base character.
1162 " Double acute (only supported on a few letters).
1163 ; Ogonek. (A little forward facing hook at the bottom
1164 right of the character.)
1165 < Caron. (A little v over the letter.)
1166 0 Circle over the base character.
1167 2 Hook over the base character.
1168 9 Horn over the base character.
1169 The most common characters from the Arabic, Cyrillic, Greek and
1171 Hebrew alphabets are available; consult RFC 1345 for the appro‐
1172 priate sequences. In addition, a set of two letter codes not in
1173 RFC 1345 are available for the double-width characters corre‐
1174 sponding to ASCII characters from ! to ~ (0x21 to 0x7e) by pre‐
1175 ceding the character with ^, for example ^A for a double-width
1176 A.
1177 The following other two-character sequences are understood.
1179 ASCII characters
1181 These are already present on most keyboards:
1182 <( Left square bracket
1183 // Backslash (solidus)
1184 )> Right square bracket
1185 (! Left brace (curly bracket)
1186 !! Vertical bar (pipe symbol)
1187 !) Right brace (curly bracket)
1188 '? Tilde
1189 Special letters
1191 Characters found in various variants of the Latin alpha‐
1192 bet:
1193 ss Eszett (scafes S)
1194 D-, d- Eth
1195 TH, th Thorn
1196 kk Kra
1197 'n 'n
1198 NG, ng Ng
1199 OI, oi Oi
1200 yr yr
1201 ED ezh
1202 Currency symbols
1204 Ct Cent
1205 Pd Pound sterling (also lira and others)
1206 Cu Currency
1207 Ye Yen
1208 Eu Euro (N.B. not in RFC 1345)
1209 Punctuation characters
1211 References to "right" quotes indicate the shape (like a 9
1212 rather than 6) rather than their grammatical use. (For
1213 example, a "right" low double quote is used to open quo‐
1214 tations in German.)
1215 !I Inverted exclamation mark
1216 BB Broken vertical bar
1217 SE Section
1218 Co Copyright
1219 -a Spanish feminine ordinal indicator
1220 << Left guillemet
1221 -- Soft hyphen
1222 Rg Registered trade mark
1223 PI Pilcrow (paragraph)
1224 -o Spanish masculine ordinal indicator
1225 >> Right guillemet
1226 ?I Inverted question mark
1227 -1 Hyphen
1228 -N En dash
1229 -M Em dash
1230 -3 Horizontal bar
1231 :3 Vertical ellipsis
1232 .3 Horizontal midline ellipsis
1233 !2 Double vertical line
1234 =2 Double low line
1235 '6 Left single quote
1236 '9 Right single quote
1237 .9 "Right" low quote
1238 9' Reversed "right" quote
1239 "6 Left double quote
1240 "9 Right double quote
1241 :9 "Right" low double quote
1242 9" Reversed "right" double quote
1243 /- Dagger
1244 /= Double dagger
1245 Mathematical symbols
1247 DG Degree
1248 -2, +-, -+
1249 - sign, +/- sign, -/+ sign
1250 2S Superscript 2
1251 3S Superscript 3
1252 1S Superscript 1
1253 My Micro
1254 .M Middle dot
1255 14 Quarter
1256 12 Half
1257 34 Three quarters
1258 *X Multiplication
1259 -: Division
1260 %0 Per mille
1261 FA, TE, /0
1262 For all, there exists, empty set
1263 dP, DE, NB
1264 Partial derivative, delta (increment), del (nabla)
1265 (-, -) Element of, contains
1266 *P, +Z Product, sum
1267 *-, Ob, Sb
1268 Asterisk, ring, bullet
1269 RT, 0(, 00
1270 Root sign, proportional to, infinity
1271 Other symbols
1273 cS, cH, cD, cC
1274 Card suits: spades, hearts, diamonds, clubs
1275 Md, M8, M2, Mb, Mx, MX
1276 Musical notation: crotchet (quarter note), quaver (eighth
1277 note), semiquavers (sixteenth notes), flag sign, natural
1278 sign, sharp sign
1279 Fm, Ml Female, male
1280 Accents on their own
1282 '> Circumflex (same as caret, ^)
1283 '! Grave (same as backtick, `)
1284 ', Cedilla
1285 ': Diaeresis (Umlaut)
1286 'm Macron
1287 '' Acute
1288 insert-files
1290 This function allows you type a file pattern, and see the
1291 results of the expansion at each step. When you hit return, all
1292 expansions are inserted into the command line.
1293 bindkey '^Xf' insert-files
1295 narrow-to-region [ -p pre ] [ -P post ]
1297 [ -S statepm | -R statepm ] [ -n ] [ start end ])
1298 narrow-to-region-invisible
1299 Narrow the editable portion of the buffer to the region between
1300 the cursor and the mark, which may be in either order. The
1301 region may not be empty.
1302 narrow-to-region may be used as a widget or called as a function
1304 from a user-defined widget; by default, the text outside the
1305 editable area remains visible. A recursive-edit is performed
1306 and the original widening status is then restored. Various
1307 options and arguments are available when it is called as a func‐
1308 tion.
1309 The options -p pretext and -P posttext may be used to replace
1311 the text before and after the display for the duration of the
1312 function; either or both may be an empty string.
1313 If the option -n is also given, pretext or posttext will only be
1315 inserted if there is text before or after the region respec‐
1316 tively which will be made invisible.
1317 Two numeric arguments may be given which will be used instead of
1319 the cursor and mark positions.
1320 The option -S statepm is used to narrow according to the other
1322 options while saving the original state in the parameter with
1323 name statepm, while the option -R statepm is used to restore the
1324 state from the parameter; note in both cases the name of the
1325 parameter is required. In the second case, other options and
1326 arguments are irrelevant. When this method is used, no recur‐
1327 sive-edit is performed; the calling widget should call this
1328 function with the option -S, perform its own editing on the com‐
1329 mand line or pass control to the user via `zle recursive-edit',
1330 then call this function with the option -R. The argument
1331 statepm must be a suitable name for an ordinary parameter,
1332 except that parameters beginning with the prefix _ntr_ are
1333 reserved for use within narrow-to-region. Typically the parame‐
1334 ter will be local to the calling function.
1335 narrow-to-region-invisible is a simple widget which calls nar‐
1337 row-to-region with arguments which replace any text outside the
1338 region with `...'.
1339 The display is restored (and the widget returns) upon any zle
1341 command which would usually cause the line to be accepted or
1342 aborted. Hence an additional such command is required to accept
1343 or abort the current line.
1344 The return status of both widgets is zero if the line was
1346 accepted, else non-zero.
1347 Here is a trivial example of a widget using this feature.
1349 local state
1350 narrow-to-region -p $'Editing restricted region\n' \
1351 -P '' -S state
1352 zle recursive-edit
1353 narrow-to-region -R state
1354 insert-unicode-char
1356 When first executed, the user inputs a set of hexadecimal dig‐
1357 its. This is terminated with another call to insert-uni‐
1358 code-char. The digits are then turned into the corresponding
1359 Unicode character. For example, if the widget is bound to ^XU,
1360 the character sequence `^XU 4 c ^XU' inserts L (Unicode U+004c).
1361 See insert-composed-char for a way of inserting characters using
1363 a two-character mnemonic.
1364 predict-on
1366 This set of functions implements predictive typing using history
1367 search. After predict-on, typing characters causes the editor
1368 to look backward in the history for the first line beginning
1369 with what you have typed so far. After predict-off, editing
1370 returns to normal for the line found. In fact, you often don't
1371 even need to use predict-off, because if the line doesn't match
1372 something in the history, adding a key performs standard comple‐
1373 tion, and then inserts itself if no completions were found.
1374 However, editing in the middle of a line is liable to confuse
1375 prediction; see the toggle style below.
1376 With the function based completion system (which is needed for
1378 this), you should be able to type TAB at almost any point to
1379 advance the cursor to the next ``interesting'' character posi‐
1380 tion (usually the end of the current word, but sometimes some‐
1381 where in the middle of the word). And of course as soon as the
1382 entire line is what you want, you can accept with return, with‐
1383 out needing to move the cursor to the end first.
1384 The first time predict-on is used, it creates several additional
1386 widget functions:
1387 delete-backward-and-predict
1389 Replaces the backward-delete-char widget. You do not
1390 need to bind this yourself.
1391 insert-and-predict
1392 Implements predictive typing by replacing the self-insert
1393 widget. You do not need to bind this yourself.
1394 predict-off
1395 Turns off predictive typing.
1396 Although you autoload only the predict-on function, it is neces‐
1398 sary to create a keybinding for predict-off as well.
1399 zle -N predict-on
1401 zle -N predict-off
1402 bindkey '^X^Z' predict-on
1403 bindkey '^Z' predict-off
1404 read-from-minibuffer
1406 This is most useful when called as a function from inside a wid‐
1407 get, but will work correctly as a widget in its own right. It
1408 prompts for a value below the current command line; a value may
1409 be input using all of the standard zle operations (and not
1410 merely the restricted set available when executing, for example,
1411 execute-named-cmd). The value is then returned to the calling
1412 function in the parameter $REPLY and the editing buffer restored
1413 to its previous state. If the read was aborted by a keyboard
1414 break (typically ^G), the function returns status 1 and $REPLY
1415 is not set.
1416 If one argument is supplied to the function it is taken as a
1418 prompt, otherwise `? ' is used. If two arguments are supplied,
1419 they are the prompt and the initial value of $LBUFFER, and if a
1420 third argument is given it is the initial value of $RBUFFER.
1421 This provides a default value and starting cursor placement.
1422 Upon return the entire buffer is the value of $REPLY.
1423 One option is available: `-k num' specifies that num characters
1425 are to be read instead of a whole line. The line editor is not
1426 invoked recursively in this case, so depending on the terminal
1427 settings the input may not be visible, and only the input keys
1428 are placed in $REPLY, not the entire buffer. Note that unlike
1429 the read builtin num must be given; there is no default.
1430 The name is a slight misnomer, as in fact the shell's own
1432 minibuffer is not used. Hence it is still possible to call exe‐
1433 cuted-named-cmd and similar functions while reading a value.
1434 replace-string, replace-pattern
1436 replace-string-again, replace-pattern-again
1437 The function replace-string implements two widgets. If defined
1438 under the same name as the function, it prompts for two strings;
1439 the first (source) string will be replaced by the second every‐
1440 where it occurs in the line editing buffer.
1441 If the widget name contains the word `pattern', for example by
1443 defining the widget using the command `zle -N replace-pattern
1444 replace-string', then the replacement is done by pattern match‐
1445 ing. All zsh extended globbing patterns can be used in the
1446 source string; note that unlike filename generation the pattern
1447 does not need to match an entire word, nor do glob qualifiers
1448 have any effect. In addition, the replacement string can con‐
1449 tain parameter or command substitutions. Furthermore, a `&' in
1450 the replacement string will be replaced with the matched source
1451 string, and a backquoted digit `\N' will be replaced by the Nth
1452 parenthesised expression matched. The form `\{N}' may be used
1453 to protect the digit from following digits.
1454 By default the previous source or replacement string will not be
1456 offered for editing. However, this feature can be activated by
1457 setting the style edit-previous in the context :zle:widget (for
1458 example, :zle:replace-string) to true. In addition, a positive
1459 numeric argument forces the previous values to be offered, a
1460 negative or zero argument forces them not to be.
1461 The function replace-string-again can be used to repeat the pre‐
1463 vious replacement; no prompting is done. As with
1464 replace-string, if the name of the widget contains the word
1465 `pattern', pattern matching is performed, else a literal string
1466 replacement. Note that the previous source and replacement text
1467 are the same whether pattern or string matching is used.
1468 For example, starting from the line:
1470 print This line contains fan and fond
1472 and invoking replace-pattern with the source string `f(?)n' and
1474 the replacement string `c\1r' produces the not very useful line:
1475 print This line contains car and cord
1477 The range of the replacement string can be limited by using the
1479 narrow-to-region-invisible widget. One limitation of the cur‐
1480 rent version is that undo will cycle through changes to the
1481 replacement and source strings before undoing the replacement
1482 itself.
1483 smart-insert-last-word
1485 This function may replace the insert-last-word widget, like so:
1486 zle -N insert-last-word smart-insert-last-word
1488 With a numeric prefix, or when passed command line arguments in
1490 a call from another widget, it behaves like insert-last-word,
1491 except that words in comments are ignored when INTERACTIVE_COM‐
1492 MENTS is set.
1493 Otherwise, the rightmost ``interesting'' word from the previous
1495 command is found and inserted. The default definition of
1496 ``interesting'' is that the word contains at least one alpha‐
1497 betic character, slash, or backslash. This definition may be
1498 overridden by use of the match style. The context used to look
1499 up the style is the widget name, so usually the context is
1500 :insert-last-word. However, you can bind this function to dif‐
1501 ferent widgets to use different patterns:
1502 zle -N insert-last-assignment smart-insert-last-word
1504 zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
1505 bindkey '\e=' insert-last-assignment
1506 If no interesting word is found and the auto-previous style is
1508 set to a true value, the search continues upward through the
1509 history. When auto-previous is unset or false (the default),
1510 the widget must be invoked repeatedly in order to search earlier
1511 history lines.
1512 which-command
1514 This function is a drop-in replacement for the builtin widget
1515 which-command. It has enhanced behaviour, in that it correctly
1516 detects whether or not the command word needs to be expanded as
1517 an alias; if so, it continues tracing the command word from the
1518 expanded alias until it reaches the command that will be exe‐
1519 cuted.
1520 The style whence is available in the context :zle:$WIDGET; this
1522 may be set to an array to give the command and options that will
1523 be used to investigate the command word found. The default is
1524 whence -c.
1525 Utility Functions
1527 These functions are useful in constructing widgets. They should be
1528 loaded with `autoload -U function' and called as indicated from
1529 user-defined widgets.
1530 split-shell-arguments
1532 This function splits the line currently being edited into shell
1533 arguments and whitespace. The result is stored in the array
1534 reply. The array contains all the parts of the line in order,
1535 starting with any whitespace before the first argument, and fin‐
1536 ishing with any whitespace after the last argument. Hence (so
1537 long as the option KSH_ARRAYS is not set) whitespace is given by
1538 odd indices in the array and arguments by even indices. Note
1539 that no stripping of quotes is done; joining together all the
1540 elements of reply in order is guaranteed to produce the original
1541 line.
1542 The parameter REPLY is set to the index of the word in reply
1544 which contains the character after the cursor, where the first
1545 element has index 1. The parameter REPLY2 is set to the index
1546 of the character under the cursor in that word, where the first
1547 character has index 1.
1548 Hence reply, REPLY and REPLY2 should all be made local to the
1550 enclosing function.
1551 See the function modify-current-argument, described below, for
1553 an example of how to call this function.
1554 modify-current-argument expr-using-$ARG
1556 This function provides a simple method of allowing user-defined
1557 widgets to modify the command line argument under the cursor (or
1558 immediately to the left of the cursor if the cursor is between
1559 arguments). The argument should be an expression which when
1560 evaluated operates on the shell parameter ARG, which will have
1561 been set to the command line argument under the cursor. The
1562 expression should be suitably quoted to prevent it being evalu‐
1563 ated too early.
1564 For example, a user-defined widget containing the following code
1566 converts the characters in the argument under the cursor into
1567 all upper case:
1568 modify-current-argument '${(U)ARG}'
1570 The following strips any quoting from the current word (whether
1572 backslashes or one of the styles of quotes), and replaces it
1573 with single quoting throughout:
1574 modify-current-argument '${(qq)${(Q)ARG}}'
1576 Styles
1578 The behavior of several of the above widgets can be controlled by the
1579 use of the zstyle mechanism. In particular, widgets that interact with
1580 the completion system pass along their context to any completions that
1581 they invoke.
1582 break-keys
1584 This style is used by the incremental-complete-word widget. Its
1585 value should be a pattern, and all keys matching this pattern
1586 will cause the widget to stop incremental completion without the
1587 key having any further effect. Like all styles used directly by
1588 incremental-complete-word, this style is looked up using the
1589 context `:incremental'.
1590 completer
1592 The incremental-complete-word and insert-and-predict widgets set
1593 up their top-level context name before calling completion. This
1594 allows one to define different sets of completer functions for
1595 normal completion and for these widgets. For example, to use
1596 completion, approximation and correction for normal completion,
1597 completion and correction for incremental completion and only
1598 completion for prediction one could use:
1599 zstyle ':completion:*' completer \
1601 _complete _correct _approximate
1602 zstyle ':completion:incremental:*' completer \
1603 _complete _correct
1604 zstyle ':completion:predict:*' completer \
1605 _complete
1606 It is a good idea to restrict the completers used in prediction,
1608 because they may be automatically invoked as you type. The
1609 _list and _menu completers should never be used with prediction.
1610 The _approximate, _correct, _expand, and _match completers may
1611 be used, but be aware that they may change characters anywhere
1612 in the word behind the cursor, so you need to watch carefully
1613 that the result is what you intended.
1614 cursor The insert-and-predict widget uses this style, in the context
1616 `:predict', to decide where to place the cursor after completion
1617 has been tried. Values are:
1618 complete
1620 The cursor is left where it was when completion finished,
1621 but only if it is after a character equal to the one just
1622 inserted by the user. If it is after another character,
1623 this value is the same as `key'.
1624 key The cursor is left after the nth occurrence of the char‐
1626 acter just inserted, where n is the number of times that
1627 character appeared in the word before completion was
1628 attempted. In short, this has the effect of leaving the
1629 cursor after the character just typed even if the comple‐
1630 tion code found out that no other characters need to be
1631 inserted at that position.
1632 Any other value for this style unconditionally leaves the cursor
1634 at the position where the completion code left it.
1635 list When using the incremental-complete-word widget, this style says
1637 if the matches should be listed on every key press (if they fit
1638 on the screen). Use the context prefix `:completion:incremen‐
1639 tal'.
1640 The insert-and-predict widget uses this style to decide if the
1642 completion should be shown even if there is only one possible
1643 completion. This is done if the value of this style is the
1644 string always. In this case the context is `:predict' (not
1645 `:completion:predict').
1646 match This style is used by smart-insert-last-word to provide a pat‐
1648 tern (using full EXTENDED_GLOB syntax) that matches an interest‐
1649 ing word. The context is the name of the widget to which
1650 smart-insert-last-word is bound (see above). The default behav‐
1651 ior of smart-insert-last-word is equivalent to:
1652 zstyle :insert-last-word match '*[[:alpha:]/\\]*'
1654 However, you might want to include words that contain spaces:
1656 zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'
1658 Or include numbers as long as the word is at least two charac‐
1660 ters long:
1661 zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'
1663 The above example causes redirections like "2>" to be included.
1665 prompt The incremental-complete-word widget shows the value of this
1667 style in the status line during incremental completion. The
1668 string value may contain any of the following substrings in the
1669 manner of the PS1 and other prompt parameters:
1670 %c Replaced by the name of the completer function that gen‐
1672 erated the matches (without the leading underscore).
1673 %l When the list style is set, replaced by `...' if the list
1675 of matches is too long to fit on the screen and with an
1676 empty string otherwise. If the list style is `false' or
1677 not set, `%l' is always removed.
1678 %n Replaced by the number of matches generated.
1680 %s Replaced by `-no match-', `-no prefix-', or an empty
1682 string if there is no completion matching the word on the
1683 line, if the matches have no common prefix different from
1684 the word on the line, or if there is such a common pre‐
1685 fix, respectively.
1686 %u Replaced by the unambiguous part of all matches, if there
1688 is any, and if it is different from the word on the line.
1689 Like `break-keys', this uses the `:incremental' context.
1691 stop-keys
1693 This style is used by the incremental-complete-word widget. Its
1694 value is treated similarly to the one for the break-keys style
1695 (and uses the same context: `:incremental'). However, in this
1696 case all keys matching the pattern given as its value will stop
1697 incremental completion and will then execute their usual func‐
1698 tion.
1699 toggle This boolean style is used by predict-on and its related widgets
1701 in the context `:predict'. If set to one of the standard `true'
1702 values, predictive typing is automatically toggled off in situa‐
1703 tions where it is unlikely to be useful, such as when editing a
1704 multi-line buffer or after moving into the middle of a line and
1705 then deleting a character. The default is to leave prediction
1706 turned on until an explicit call to predict-off.
1707 verbose
1709 This boolean style is used by predict-on and its related widgets
1710 in the context `:predict'. If set to one of the standard `true'
1711 values, these widgets display a message below the prompt when
1712 the predictive state is toggled. This is most useful in combi‐
1713 nation with the toggle style. The default does not display
1714 these messages.
1715 widget This style is similar to the command style: For widget functions
1717 that use zle to call other widgets, this style can sometimes be
1718 used to override the widget which is called. The context for
1719 this style is the name of the calling widget (not the name of
1720 the calling function, because one function may be bound to mul‐
1721 tiple widget names).
1722 zstyle :copy-earlier-word widget smart-insert-last-word
1724 Check the documentation for the calling widget or function to
1726 determine whether the widget style is used.
1727
1729 Two functions are provided to enable zsh to provide exception handling
1730 in a form that should be familiar from other languages.
1731 throw exception
1733 The function throw throws the named exception. The name is an
1734 arbitrary string and is only used by the throw and catch func‐
1735 tions. An exception is for the most part treated the same as a
1736 shell error, i.e. an unhandled exception will cause the shell to
1737 abort all processing in a function or script and to return to
1738 the top level in an interactive shell.
1739 catch exception-pattern
1741 The function catch returns status zero if an exception was
1742 thrown and the pattern exception-pattern matches its name. Oth‐
1743 erwise it returns status 1. exception-pattern is a standard
1744 shell pattern, respecting the current setting of the
1745 EXTENDED_GLOB option. An alias catch is also defined to prevent
1746 the argument to the function from matching filenames, so pat‐
1747 terns may be used unquoted. Note that as exceptions are not
1748 fundamentally different from other shell errors it is possible
1749 to catch shell errors by using an empty string as the exception
1750 name. The shell variable CAUGHT is set by catch to the name of
1751 the exception caught. It is possible to rethrow an exception by
1752 calling the throw function again once an exception has been
1753 caught.
1754 The functions are designed to be used together with the always con‐
1756 struct described in zshmisc(1). This is important as only this con‐
1757 struct provides the required support for exceptions. A typical example
1758 is as follows.
1759 {
1761 # "try" block
1762 # ... nested code here calls "throw MyExcept"
1763 } always {
1764 # "always" block
1765 if catch MyExcept; then
1766 print "Caught exception MyExcept"
1767 elif catch ''; then
1768 print "Caught a shell error. Propagating..."
1769 throw ''
1770 fi
1771 # Other exceptions are not handled but may be caught further
1772 # up the call stack.
1773 }
1774 If all exceptions should be caught, the following idiom might be
1776 preferable.
1777 {
1779 # ... nested code here throws an exception
1780 } always {
1781 if catch *; then
1782 case $CAUGHT in
1783 (MyExcept)
1784 print "Caught my own exception"
1785 ;;
1786 (*)
1787 print "Caught some other exception"
1788 ;;
1789 esac
1790 fi
1791 }
1792 In common with exception handling in other languages, the exception may
1794 be thrown by code deeply nested inside the `try' block. However, note
1795 that it must be thrown inside the current shell, not in a subshell
1796 forked for a pipeline, parenthesised current-shell construct, or some
1797 form of command or process substitution.
1798 The system internally uses the shell variable EXCEPTION to record the
1800 name of the exception between throwing and catching. One drawback of
1801 this scheme is that if the exception is not handled the variable EXCEP‐
1802 TION remains set and may be incorrectly recognised as the name of an
1803 exception if a shell error subsequently occurs. Adding unset EXCEPTION
1804 at the start of the outermost layer of any code that uses exception
1805 handling will eliminate this problem.
1806
1808 Three functions are available to provide handling of files recognised
1809 by extension, for example to dispatch a file text.ps when executed as a
1810 command to an appropriate viewer.
1811 zsh-mime-setup [ -fv ] [ -l [ suffix ... ] ]
1813 zsh-mime-handler
1814 These two functions use the files ~/.mime.types and
1815 /etc/mime.types, which associate types and extensions, as well
1816 as ~/.mailcap and /etc/mailcap files, which associate types and
1817 the programs that handle them. These are provided on many sys‐
1818 tems with the Multimedia Internet Mail Extensions.
1819 To enable the system, the function zsh-mime-setup should be
1821 autoloaded and run. This allows files with extensions to be
1822 treated as executable; such files be completed by the function
1823 completion system. The function zsh-mime-handler should not
1824 need to be called by the user.
1825 The system works by setting up suffix aliases with `alias -s'.
1827 Suffix aliases already installed by the user will not be over‐
1828 written.
1829 For suffixes defined in lower case, upper case variants will
1831 also automatically be handled (e.g. PDF is automatically handled
1832 if handling for the suffix pdf is defined), but not vice versa.
1833 Repeated calls to zsh-mime-setup do not override the existing
1835 mapping between suffixes and executable files unless the option
1836 -f is given. Note, however, that this does not override exist‐
1837 ing suffix aliases assigned to handlers other than zsh-mime-han‐
1838 dler.
1839 Calling zsh-mime-setup with the option -l lists the existing
1841 mappings without altering them. Suffixes to list (which may
1842 contain pattern characters that should be quoted from immediate
1843 interpretation on the command line) may be given as additional
1844 arguments, otherwise all suffixes are listed.
1845 Calling zsh-mime-setup with the option -v causes verbose output
1847 to be shown during the setup operation.
1848 The system respects the mailcap flags needsterminal and copi‐
1850 ousoutput, see mailcap(4).
1851 The functions use the following styles, which are defined with
1853 the zstyle builtin command (see zshmodules(1)). They should be
1854 defined before zsh-mime-setup is run. The contexts used all
1855 start with :mime:, with additional components in some cases. It
1856 is recommended that a trailing * (suitably quoted) be appended
1857 to style patterns in case the system is extended in future.
1858 Some examples are given below.
1859 current-shell
1860 If this boolean style is true, the mailcap handler for
1861 the context in question is run using the eval builtin
1862 instead of by starting a new sh process. This is more
1863 efficient, but may not work in the occasional cases where
1864 the mailcap handler uses strict POSIX syntax.
1865 execute-as-is
1867 This style gives a list of patterns to be matched against
1868 files passed for execution with a handler program. If
1869 the file matches the pattern, the entire command line is
1870 executed in its current form, with no handler. This is
1871 useful for files which might have suffixes but nonethe‐
1872 less be executable in their own right. If the style is
1873 not set, the pattern *(*) *(/) is used; hence executable
1874 files are executed directly and not passed to a handler,
1875 and the option AUTO_CD may be used to change to directo‐
1876 ries that happen to have MIME suffixes.
1877 file-path
1879 Used if the style find-file-in-path is true for the same
1880 context. Set to an array of directories that are used
1881 for searching for the file to be handled; the default is
1882 the command path given by the special parameter path.
1883 The shell option PATH_DIRS is respected; if that is set,
1884 the appropriate path will be searched even if the name of
1885 the file to be handled as it appears on the command line
1886 contains a `/'. The full context is :mime:.suffix:, as
1887 described for the style handler.
1888 find-file-in-path
1890 If set, allows files whose names do not contain absolute
1891 paths to be searched for in the command path or the path
1892 specified by the file-path style. If the file is not
1893 found in the path, it is looked for locally (whether or
1894 not the current directory is in the path); if it is not
1895 found locally, the handler will abort unless the han‐
1896 dle-nonexistent style is set. Files found in the path
1897 are tested as described for the style execute-as-is. The
1898 full context is :mime:.suffix:, as described for the
1899 style handler.
1900 flags Defines flags to go with a handler; the context is as for
1902 the handler style, and the format is as for the flags in
1903 mailcap.
1904 handle-nonexistent
1906 By default, arguments that don't correspond to files are
1907 not passed to the MIME handler in order to prevent it
1908 from intercepting commands found in the path that happen
1909 to have suffixes. This style may be set to an array of
1910 extended glob patterns for arguments that will be passed
1911 to the handler even if they don't exist. If it is not
1912 explicitly set it defaults to [[:alpha:]]#:/* which
1913 allows URLs to be passed to the MIME handler even though
1914 they don't exist in that format in the file system. The
1915 full context is :mime:.suffix:, as described for the
1916 style handler.
1917 handler
1919 Specifies a handler for a suffix; the suffix is given by
1920 the context as :mime:.suffix:, and the format of the han‐
1921 dler is exactly that in mailcap. Note in particular the
1922 `.' and trailing colon to distinguish this use of the
1923 context. This overrides any handler specified by the
1924 mailcap files. If the handler requires a terminal, the
1925 flags style should be set to include the word needstermi‐
1926 nal, or if the output is to be displayed through a pager
1927 (but not if the handler is itself a pager), it should
1928 include copiousoutput.
1929 mailcap
1931 A list of files in the format of ~/.mailcap and
1932 /etc/mailcap to be read during setup, replacing the
1933 default list which consists of those two files. The con‐
1934 text is :mime:. A + in the list will be replaced by the
1935 default files.
1936 mailcap-priorities
1938 This style is used to resolve multiple mailcap entries
1939 for the same MIME type. It consists of an array of the
1940 following elements, in descending order of priority;
1941 later entries will be used if earlier entries are unable
1942 to resolve the entries being compared. If none of the
1943 tests resolve the entries, the first entry encountered is
1944 retained.
1945 files The order of files (entries in the mailcap style)
1947 read. Earlier files are preferred. (Note this
1948 does not resolve entries in the same file.)
1949 priority
1951 The priority flag from the mailcap entry. The
1952 priority is an integer from 0 to 9 with the
1953 default value being 5.
1954 flags The test given by the mailcap-prio-flags option is
1956 used to resolve entries.
1957 place Later entries are preferred; as the entries are
1959 strictly ordered, this test always succeeds.
1960 Note that as this style is handled during initialisation,
1962 the context is always :mime:, with no discrimination by
1963 suffix.
1964 mailcap-prio-flags
1966 This style is used when the keyword flags is encountered
1967 in the list of tests specified by the mailcap-priorities
1968 style. It should be set to a list of patterns, each of
1969 which is tested against the flags specified in the mail‐
1970 cap entry (in other words, the sets of assignments found
1971 with some entries in the mailcap file). Earlier patterns
1972 in the list are preferred to later ones, and matched pat‐
1973 terns are preferred to unmatched ones.
1974 mime-types
1976 A list of files in the format of ~/.mime.types and
1977 /etc/mime.types to be read during setup, replacing the
1978 default list which consists of those two files. The con‐
1979 text is :mime:. A + in the list will be replaced by the
1980 default files.
1981 never-background
1983 If this boolean style is set, the handler for the given
1984 context is always run in the foreground, even if the
1985 flags provided in the mailcap entry suggest it need not
1986 be (for example, it doesn't require a terminal).
1987 pager If set, will be used instead of $PAGER or more to handle
1989 suffixes where the copiousoutput flag is set. The con‐
1990 text is as for handler, i.e. :mime:.suffix: for handling
1991 a file with the given suffix.
1992 Examples:
1994 zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
1996 zstyle ':mime:.txt:' handler less %s
1997 zstyle ':mime:.txt:' flags needsterminal
1998 When zsh-mime-setup is subsequently run, it will look for mail‐
2000 cap entries in the two files given. Files of suffix .txt will
2001 be handled by running `less file.txt'. The flag needsterminal
2002 is set to show that this program must run attached to a termi‐
2003 nal.
2004 As there are several steps to dispatching a command, the follow‐
2006 ing should be checked if attempting to execute a file by exten‐
2007 sion .ext does not have the expected effect.
2008 The command `alias -s ext' should show `ps=zsh-mime-handler'.
2010 If it shows something else, another suffix alias was already
2011 installed and was not overwritten. If it shows nothing, no han‐
2012 dler was installed: this is most likely because no handler was
2013 found in the .mime.types and mailcap combination for .ext files.
2014 In that case, appropriate handling should be added to
2015 ~/.mime.types and mailcap.
2016 If the extension is handled by zsh-mime-handler but the file is
2018 not opened correctly, either the handler defined for the type is
2019 incorrect, or the flags associated with it are in appropriate.
2020 Running zsh-mime-setup -l will show the handler and, if there
2021 are any, the flags. A %s in the handler is replaced by the file
2022 (suitably quoted if necessary). Check that the handler program
2023 listed lists and can be run in the way shown. Also check that
2024 the flags needsterminal or copiousoutput are set if the handler
2025 needs to be run under a terminal; the second flag is used if the
2026 output should be sent to a pager. An example of a suitable
2027 mailcap entry for such a program is:
2028 text/html; /usr/bin/lynx '%s'; needsterminal
2030 pick-web-browser
2032 This function is separate from the two MIME functions described
2033 above and can be assigned directly to a suffix:
2034 autoload -U pick-web-browser
2036 alias -s html=pick-web-browser
2037 It is provided as an intelligent front end to dispatch a web
2039 browser. It may be run as either a function or a shell script.
2040 The status 255 is returned if no browser could be started.
2041 Various styles are available to customize the choice of
2043 browsers:
2044 browser-style
2046 The value of the style is an array giving preferences in
2047 decreasing order for the type of browser to use. The
2048 values of elements may be
2049 running
2051 Use a GUI browser that is already running when an
2052 X Window display is available. The browsers
2053 listed in the x-browsers style are tried in order
2054 until one is found; if it is, the file will be
2055 displayed in that browser, so the user may need to
2056 check whether it has appeared. If no running
2057 browser is found, one is not started. Browsers
2058 other than Firefox, Opera and Konqueror are
2059 assumed to understand the Mozilla syntax for open‐
2060 ing a URL remotely.
2061 x Start a new GUI browser when an X Window display
2063 is available. Search for the availability of one
2064 of the browsers listed in the x-browsers style and
2065 start the first one that is found. No check is
2066 made for an already running browser.
2067 tty Start a terminal-based browser. Search for the
2069 availability of one of the browsers listed in the
2070 tty-browsers style and start the first one that is
2071 found.
2072 If the style is not set the default running x tty is
2074 used.
2075 x-browsers
2077 An array in decreasing order of preference of browsers to
2078 use when running under the X Window System. The array
2079 consists of the command name under which to start the
2080 browser. They are looked up in the context :mime: (which
2081 may be extended in future, so appending `*' is recom‐
2082 mended). For example,
2083 zstyle ':mime:*' x-browsers opera konqueror firefox
2085 specifies that pick-web-browser should first look for a
2087 running instance of Opera, Konqueror or Firefox, in that
2088 order, and if it fails to find any should attempt to
2089 start Opera. The default is firefox mozilla netscape
2090 opera konqueror.
2091 tty-browsers
2093 An array similar to x-browsers, except that it gives
2094 browsers to use use when no X Window display is avail‐
2095 able. The default is elinks links lynx.
2096 command
2098 If it is set this style is used to pick the command used
2099 to open a page for a browser. The context is
2100 :mime:browser:new:$browser: to start a new browser or
2101 :mime:browser:running:$browser: to open a URL in a
2102 browser already running on the current X display, where
2103 $browser is the value matched in the x-browsers or
2104 tty-browsers style. The escape sequence %b in the
2105 style's value will be replaced by the browser, while %u
2106 will be replaced by the URL. If the style is not set,
2107 the default for all new instances is equivalent to %b %u
2108 and the defaults for using running browsers are equiva‐
2109 lent to the values kfmclient openURL %u for Konqueror,
2110 firefox -new-tab %u for Firefox, opera -newpage %u for
2111 Opera, and %b -remote "openUrl(%u)" for all others.
2112
2114 zcalc [ expression ... ]
2115 A reasonably powerful calculator based on zsh's arithmetic eval‐
2116 uation facility. The syntax is similar to that of formulae in
2117 most programming languages; see the section `Arithmetic Evalua‐
2118 tion' in zshmisc(1) for details. The mathematical library
2119 zsh/mathfunc will be loaded if it is available; see the section
2120 `The zsh/mathfunc Module' in zshmodules(1). The mathematical
2121 functions correspond to the raw system libraries, so trigonomet‐
2122 ric functions are evaluated using radians, and so on.
2123 Each line typed is evaluated as an expression. The prompt shows
2125 a number, which corresponds to a positional parameter where the
2126 result of that calculation is stored. For example, the result
2127 of the calculation on the line preceded by `4> ' is available as
2128 $4. The last value calculated is available as ans. Full com‐
2129 mand line editing, including the history of previous calcula‐
2130 tions, is available; the history is saved in the file
2131 ~/.zcalc_history. To exit, enter a blank line or type `:q' on
2132 its own (`q' is allowed for historical compatibility).
2133 If arguments are given to zcalc on start up, they are used to
2135 prime the first few positional parameters. A visual indication
2136 of this is given when the calculator starts.
2137 The constants PI (3.14159...) and E (2.71828...) are provided.
2139 Parameter assignment is possible, but note that all parameters
2140 will be put into the global namespace.
2141 The output base can be initialised by passing the option
2143 `-#base', for example `zcalc -#16' (the `#' may have to be
2144 quoted, depending on the globbing options set).
2145 The prompt is configurable via the parameter ZCALCPROMPT, which
2147 undergoes standard prompt expansion. The index of the current
2148 entry is stored locally in the first element of the array psvar,
2149 which can be referred to in ZCALCPROMPT as `%1v'. The default
2150 prompt is `%1v> '.
2151 A few special commands are available; these are introduced by a
2153 colon. For backward compatibility, the colon may be omitted for
2154 certain commands. Completion is available if compinit has been
2155 run.
2156 The output precision may be specified within zcalc by special
2158 commands familiar from many calculators.
2159 :norm The default output format. It corresponds to the printf
2160 %g specification. Typically this shows six decimal dig‐
2161 its.
2162 :sci digits
2164 Scientific notation, corresponding to the printf %g out‐
2165 put format with the precision given by digits. This pro‐
2166 duces either fixed point or exponential notation depend‐
2167 ing on the value output.
2168 :fix digits
2170 Fixed point notation, corresponding to the printf %f out‐
2171 put format with the precision given by digits.
2172 :eng digits
2174 Exponential notation, corresponding to the printf %E out‐
2175 put format with the precision given by digits.
2176 :raw Raw output: this is the default form of the output from
2178 a math evaluation. This may show more precision than the
2179 number actually possesses.
2180 Other special commands:
2182 :!line...
2183 Execute line... as a normal shell command line. Note
2184 that it is executed in the context of the function, i.e.
2185 with local variables. Space is optional after :!.
2186 :local arg ...
2188 Declare variables local to the function. Note that cer‐
2189 tain variables are used by the function for its own pur‐
2190 poses. Other variables may be used, too, but they will
2191 be taken from or put into the global scope.
2192 :function name [ body ]
2194 Define a mathematical function or (with no body) delete
2195 it. The function is defined using zmathfuncdef, see
2196 below.
2197 Note that zcalc takes care of all quoting. Hence for
2199 example:
2200 function cube $1 * $1 * $1
2202 defines a function to cube the sole argument.
2204 [#base]
2206 This is not a special command, rather part of normal
2207 arithmetic syntax; however, when this form appears on a
2208 line by itself the default output radix is set to base.
2209 Use, for example, `[#16]' to display hexadecimal output
2210 preceded by an indication of the base, or `[##16]' just
2211 to display the raw number in the given base. Bases them‐
2212 selves are always specified in decimal. `[#]' restores
2213 the normal output format. Note that setting an output
2214 base suppresses floating point output; use `[#]' to
2215 return to normal operation.
2216 See the comments in the function for a few extra tips.
2218 zmathfuncdef [ mathfunc [ body ] ]
2220 A convenient front end to functions -M.
2221 With two arguments, define a mathematical function named math‐
2223 func which can be used in any form of arithmetic evaluation.
2224 body is a mathematical expression to implement the function. It
2225 may contain references to position parameters $1, $2, ... to
2226 refer to mandatory parameters and ${1:-defvalue} ... to refer
2227 to optional parameters. Note that the forms must be strictly
2228 adhered to for the function to calculate the correct number of
2229 arguments. The implementation is held in a shell function named
2230 zsh_math_func_mathfunc; usually the user will not need to refer
2231 to the shell function directly. Any existing function of the
2232 same name is silently replaced.
2233 With one argument, remove the mathematical function mathfunc as
2235 well as the shell function implementation.
2236 With no arguments, list all mathfunc functions in a form suit‐
2238 able for restoring the definition. The functions have not nec‐
2239 essarily been defined by zmathfuncdef.
2240
2242 The zsh/newuser module comes with a function to aid in configuring
2243 shell options for new users. If the module is installed, this function
2244 can also be run by hand. It is available even if the module's default
2245 behaviour, namely running the function for a new user logging in with‐
2246 out startup files, is inhibited.
2247 zsh-newuser-install [ -f ]
2249 The function presents the user with various options for cus‐
2250 tomizing their initialization scripts. Currently only ~/.zshrc
2251 is handled. $ZDOTDIR/.zshrc is used instead if the parameter
2252 ZDOTDIR is set; this provides a way for the user to configure a
2253 file without altering an existing .zshrc.
2254 By default the function exits immediately if it finds any of the
2256 files .zshenv, .zprofile, .zshrc, or .zlogin in the appropriate
2257 directory. The option -f is required in order to force the
2258 function to continue. Note this may happen even if .zshrc
2259 itself does not exist.
2260 As currently configured, the function will exit immediately if
2262 the user has root privileges; this behaviour cannot be overrid‐
2263 den.
2264 Once activated, the function's behaviour is supposed to be
2266 self-explanatory. Menus are present allowing the user to alter
2267 the value of options and parameters. Suggestions for improve‐
2268 ments are always welcome.
2269 When the script exits, the user is given the opportunity to save
2271 the new file or not; changes are not irreversible until this
2272 point. However, the script is careful to restrict changes to
2273 the file only to a group marked by the lines `# Lines configured
2274 by zsh-newuser-install' and `# End of lines configured by
2275 zsh-newuser-install'. In addition, the old version of .zshrc is
2276 saved to a file with the suffix .zni appended.
2277 If the function edits an existing .zshrc, it is up to the user
2279 to ensure that the changes made will take effect. For example,
2280 if control usually returns early from the existing .zshrc the
2281 lines will not be executed; or a later initialization file may
2282 override options or parameters, and so on. The function itself
2283 does not attempt to detect any such conflicts.
2284
2286 There are a large number of helpful functions in the Functions/Misc
2287 directory of the zsh distribution. Most are very simple and do not
2288 require documentation here, but a few are worthy of special mention.
2289 Descriptions
2291 colors This function initializes several associative arrays to map
2292 color names to (and from) the ANSI standard eight-color terminal
2293 codes. These are used by the prompt theme system (see above).
2294 You seldom should need to run colors more than once.
2295 The eight base colors are: black, red, green, yellow, blue,
2297 magenta, cyan, and white. Each of these has codes for fore‐
2298 ground and background. In addition there are eight intensity
2299 attributes: bold, faint, standout, underline, blink, reverse,
2300 and conceal. Finally, there are six codes used to negate
2301 attributes: none (reset all attributes to the defaults), normal
2302 (neither bold nor faint), no-standout, no-underline, no-blink,
2303 and no-reverse.
2304 Some terminals do not support all combinations of colors and
2306 intensities.
2307 The associative arrays are:
2309 color
2311 colour Map all the color names to their integer codes, and inte‐
2312 ger codes to the color names. The eight base names map
2313 to the foreground color codes, as do names prefixed with
2314 `fg-', such as `fg-red'. Names prefixed with `bg-', such
2315 as `bg-blue', refer to the background codes. The reverse
2316 mapping from code to color yields base name for fore‐
2317 ground codes and the bg- form for backgrounds.
2318 Although it is a misnomer to call them `colors', these
2320 arrays also map the other fourteen attributes from names
2321 to codes and codes to names.
2322 fg
2324 fg_bold
2325 fg_no_bold
2326 Map the eight basic color names to ANSI terminal escape
2327 sequences that set the corresponding foreground text
2328 properties. The fg sequences change the color without
2329 changing the eight intensity attributes.
2330 bg
2332 bg_bold
2333 bg_no_bold
2334 Map the eight basic color names to ANSI terminal escape
2335 sequences that set the corresponding background proper‐
2336 ties. The bg sequences change the color without changing
2337 the eight intensity attributes.
2338 In addition, the scalar parameters reset_color and bold_color
2340 are set to the ANSI terminal escapes that turn off all
2341 attributes and turn on bold intensity, respectively.
2342 fned name
2344 Same as zed -f. This function does not appear in the zsh dis‐
2345 tribution, but can be created by linking zed to the name fned in
2346 some directory in your fpath.
2347 is-at-least needed [ present ]
2349 Perform a greater-than-or-equal-to comparison of two strings
2350 having the format of a zsh version number; that is, a string of
2351 numbers and text with segments separated by dots or dashes. If
2352 the present string is not provided, $ZSH_VERSION is used. Seg‐
2353 ments are paired left-to-right in the two strings with leading
2354 non-number parts ignored. If one string has fewer segments than
2355 the other, the missing segments are considered zero.
2356 This is useful in startup files to set options and other state
2358 that are not available in all versions of zsh.
2359 is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
2361 is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
2362 is-at-least 2.6-17 || print "You can't use is-at-least here."
2363 nslookup [ arg ... ]
2365 This wrapper function for the nslookup command requires the
2366 zsh/zpty module (see zshmodules(1)). It behaves exactly like
2367 the standard nslookup except that it provides customizable
2368 prompts (including a right-side prompt) and completion of
2369 nslookup commands, host names, etc. (if you use the func‐
2370 tion-based completion system). Completion styles may be set
2371 with the context prefix `:completion:nslookup'.
2372 See also the pager, prompt and rprompt styles below.
2374 run-help cmd
2376 This function is designed to be invoked by the run-help ZLE wid‐
2377 get, in place of the default alias. See `Accessing On-Line
2378 Help' above for setup instructions.
2379 In the discussion which follows, if cmd is a filesystem path, it
2381 is first reduced to its rightmost component (the file name).
2382 Help is first sought by looking for a file named cmd in the
2384 directory named by the HELPDIR parameter. If no file is found,
2385 an assistant function, alias, or command named run-help-cmd is
2386 sought. If found, the assistant is executed with the rest of
2387 the current command line (everything after the command name cmd)
2388 as its arguments. When neither file nor assistant is found, the
2389 external command `man cmd' is run.
2390 An example assistant for the "ssh" command:
2392 run-help-ssh() {
2394 emulate -LR zsh
2395 local -a args
2396 # Delete the "-l username" option
2397 zparseopts -D -E -a args l:
2398 # Delete other options, leaving: host command
2399 args=(${@:#-*})
2400 if [[ ${#args} -lt 2 ]]; then
2401 man ssh
2402 else
2403 run-help $args[2]
2404 fi
2405 }
2406 Several of these assistants are provided in the Functions/Misc
2408 directory. These must be autoloaded, or placed as executable
2409 scripts in your search path, in order to be found and used by
2410 run-help.
2411 run-help-git
2413 run-help-svk
2414 run-help-svn
2415 Assistant functions for the git, svk, and svn commands.
2416 tetris Zsh was once accused of not being as complete as Emacs, because
2418 it lacked a Tetris game. This function was written to refute
2419 this vicious slander.
2420 This function must be used as a ZLE widget:
2422 autoload -U tetris
2424 zle -N tetris
2425 bindkey keys tetris
2426 To start a game, execute the widget by typing the keys. What‐
2428 ever command line you were editing disappears temporarily, and
2429 your keymap is also temporarily replaced by the Tetris control
2430 keys. The previous editor state is restored when you quit the
2431 game (by pressing `q') or when you lose.
2432 If you quit in the middle of a game, the next invocation of the
2434 tetris widget will continue where you left off. If you lost, it
2435 will start a new game.
2436 zargs [ option ... -- ] [ input ... ] [ -- command [ arg ... ] ]
2438 This function works like GNU xargs, except that instead of read‐
2439 ing lines of arguments from the standard input, it takes them
2440 from the command line. This is useful because zsh, especially
2441 with recursive glob operators, often can construct a command
2442 line for a shell function that is longer than can be accepted by
2443 an external command.
2444 The option list represents options of the zargs command itself,
2446 which are the same as those of xargs. The input list is the
2447 collection of strings (often file names) that become the argu‐
2448 ments of the command, analogous to the standard input of xargs.
2449 Finally, the arg list consists of those arguments (usually
2450 options) that are passed to the command each time it runs. The
2451 arg list precedes the elements from the input list in each run.
2452 If no command is provided, then no arg list may be provided, and
2453 in that event the default command is `print' with arguments `-r
2454 --'.
2455 For example, to get a long ls listing of all plain files in the
2457 current directory or its subdirectories:
2458 autoload -U zargs
2460 zargs -- **/*(.) -- ls -l
2461 Note that `--' is used both to mark the end of the option list
2463 and to mark the end of the input list, so it must appear twice
2464 whenever the input list may be empty. If there is guaranteed to
2465 be at least one input and the first input does not begin with a
2466 `-', then the first `--' may be omitted.
2467 In the event that the string `--' is or may be an input, the -e
2469 option may be used to change the end-of-inputs marker. Note
2470 that this does not change the end-of-options marker. For exam‐
2471 ple, to use `..' as the marker:
2472 zargs -e.. -- **/*(.) .. ls -l
2474 This is a good choice in that example because no plain file can
2476 be named `..', but the best end-marker depends on the circum‐
2477 stances.
2478 For details of the other zargs options, see xargs(1) or run
2480 zargs with the --help option.
2481 zed [ -f ] name
2483 zed -b This function uses the ZLE editor to edit a file or function.
2484 Only one name argument is allowed. If the -f option is given,
2486 the name is taken to be that of a function; if the function is
2487 marked for autoloading, zed searches for it in the fpath and
2488 loads it. Note that functions edited this way are installed
2489 into the current shell, but not written back to the autoload
2490 file.
2491 Without -f, name is the path name of the file to edit, which
2493 need not exist; it is created on write, if necessary.
2494 While editing, the function sets the main keymap to zed and the
2496 vi command keymap to zed-vicmd. These will be copied from the
2497 existing main and vicmd keymaps if they do not exist the first
2498 time zed is run. They can be used to provide special key bind‐
2499 ings used only in zed.
2500 If it creates the keymap, zed rebinds the return key to insert a
2502 line break and `^X^W' to accept the edit in the zed keymap, and
2503 binds `ZZ' to accept the edit in the zed-vicmd keymap.
2504 The bindings alone can be installed by running `zed -b'. This
2506 is suitable for putting into a startup file. Note that, if
2507 rerun, this will overwrite the existing zed and zed-vicmd
2508 keymaps.
2509 Completion is available, and styles may be set with the context
2511 prefix `:completion:zed'.
2512 A zle widget zed-set-file-name is available. This can be called
2514 by name from within zed using `\ex zed-set-file-name' (note,
2515 however, that because of zed's rebindings you will have to type
2516 ^j at the end instead of the return key), or can be bound to a
2517 key in either of the zed or zed-vicmd keymaps after `zed -b' has
2518 been run. When the widget is called, it prompts for a new name
2519 for the file being edited. When zed exits the file will be
2520 written under that name and the original file will be left
2521 alone. The widget has no effect with `zed -f'.
2522 While zed-set-file-name is running, zed uses the keymap zed-nor‐
2524 mal-keymap, which is linked from the main keymap in effect at
2525 the time zed initialised its bindings. (This is to make the
2526 return key operate normally.) The result is that if the main
2527 keymap has been changed, the widget won't notice. This is not a
2528 concern for most users.
2529 zcp [ -finqQvwW ] srcpat dest
2531 zln [ -finqQsvwW ] srcpat dest
2532 Same as zmv -C and zmv -L, respectively. These functions do not
2533 appear in the zsh distribution, but can be created by linking
2534 zmv to the names zcp and zln in some directory in your fpath.
2535 zkbd See `Keyboard Definition' above.
2537 zmv [ -finqQsvwW ] [ -C | -L | -M | -p program ] [ -o optstring ] src‐
2539 pat dest
2540 Move (usually, rename) files matching the pattern srcpat to cor‐
2541 responding files having names of the form given by dest, where
2542 srcpat contains parentheses surrounding patterns which will be
2543 replaced in turn by $1, $2, ... in dest. For example,
2544 zmv '(*).lis' '$1.txt'
2546 renames `foo.lis' to `foo.txt', `my.old.stuff.lis' to
2548 `my.old.stuff.txt', and so on.
2549 The pattern is always treated as an EXTENDED_GLOB pattern. Any
2551 file whose name is not changed by the substitution is simply
2552 ignored. Any error (a substitution resulted in an empty string,
2553 two substitutions gave the same result, the destination was an
2554 existing regular file and -f was not given) causes the entire
2555 function to abort without doing anything.
2556 Options:
2558 -f Force overwriting of destination files. Not currently
2560 passed down to the mv/cp/ln command due to vagaries of
2561 implementations (but you can use -o-f to do that).
2562 -i Interactive: show each line to be executed and ask the
2563 user whether to execute it. `Y' or `y' will execute it,
2564 anything else will skip it. Note that you just need to
2565 type one character.
2566 -n No execution: print what would happen, but don't do it.
2567 -q Turn bare glob qualifiers off: now assumed by default, so
2568 this has no effect.
2569 -Q Force bare glob qualifiers on. Don't turn this on unless
2570 you are actually using glob qualifiers in a pattern.
2571 -s Symbolic, passed down to ln; only works with -L.
2572 -v Verbose: print each command as it's being executed.
2573 -w Pick out wildcard parts of the pattern, as described
2574 above, and implicitly add parentheses for referring to
2575 them.
2576 -W Just like -w, with the addition of turning wildcards in
2577 the replacement pattern into sequential ${1} .. ${N} ref‐
2578 erences.
2579 -C
2580 -L
2581 -M Force cp, ln or mv, respectively, regardless of the name
2582 of the function.
2583 -p program
2584 Call program instead of cp, ln or mv. Whatever it does,
2585 it should at least understand the form `program -- old‐
2586 name newname' where oldname and newname are filenames
2587 generated by zmv.
2588 -o optstring
2589 The optstring is split into words and passed down verba‐
2590 tim to the cp, ln or mv command called to perform the
2591 work. It should probably begin with a `-'.
2592 Further examples:
2594 zmv -v '(* *)' '${1// /_}'
2596 For any file in the current directory with at least one space in
2598 the name, replace every space by an underscore and display the
2599 commands executed.
2600 For more complete examples and other implementation details, see
2602 the zmv source file, usually located in one of the directories
2603 named in your fpath, or in Functions/Misc/zmv in the zsh distri‐
2604 bution.
2605 zrecompile
2607 See `Recompiling Functions' above.
2608 zstyle+ context style value [ + subcontext style value ... ]
2610 This makes defining styles a bit simpler by using a single `+'
2611 as a special token that allows you to append a context name to
2612 the previously used context name. Like this:
2613 zstyle+ ':foo:bar' style1 value1 \
2615 + ':baz' style2 value2 \
2616 + ':frob' style3 value3
2617 This defines `style1' with `value1' for the context :foo:bar as
2619 usual, but it also defines `style2' with `value2' for the con‐
2620 text :foo:bar:baz and `style3' with `value3' for :foo:bar:frob.
2621 Any subcontext may be the empty string to re-use the first con‐
2622 text unchanged.
2623 Styles
2625 insert-tab
2626 The zed function sets this style in context `:completion:zed:*'
2627 to turn off completion when TAB is typed at the beginning of a
2628 line. You may override this by setting your own value for this
2629 context and style.
2630 pager The nslookup function looks up this style in the context
2632 `:nslookup' to determine the program used to display output that
2633 does not fit on a single screen.
2634 prompt
2636 rprompt
2637 The nslookup function looks up this style in the context
2638 `:nslookup' to set the prompt and the right-side prompt, respec‐
2639 tively. The usual expansions for the PS1 and RPS1 parameters
2640 may be used (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)).
2641zsh 4.3.10 June 1, 2009 ZSHCONTRIB(1)