ZSHBUILTINS(1)

📦

version 5.9.2 · 6 versions

5.9.2 · arch rolling, nixpkgs unstable (latest)
5.9.1 · nixos 26.05
5.8 · centos-stream 9
5.8.1 · ubuntu jammy
5.9 · alpine 3.22, alpine 3.23, alpine 3.24, centos-stream 10, fedora 43, fedora 44, opensuse-leap 16.0
5.9 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

zshbuiltins — zsh built-in commands. Yep bestie, this is the zshbuiltins(1) page, and it is literally the whole built-in command squad. slay 💅✨

🌸 SHELL BUILTIN COMMANDS 🌸

Okay so first, the vibe check on how options work around here. Some shell builtin commands take options as described in individual entries; these are often referred to in the list below as flags to avoid confusion with shell options, which may also have an effect on the behaviour of builtin commands. In this introductory section, option always has the meaning of an option to a command that should be familiar to most command line users.

Typically, options are single letters preceded by a hyphen (-). Options that take an argument accept it either immediately following the option letter or after white space, for example print -C3 {1..9} or print -C 3 {1..9} are equivalent. Arguments to options are not the same as arguments to the command; the documentation indicates which is which. Options that do not take an argument may be combined in a single word, for example print -rca -- * and print -r -c -a -- * are equivalent.

Some shell builtin commands also take options that begin with + instead of -. The list below makes clear which commands these are.

Options (together with their individual arguments, if any) must appear in a group before any non-option arguments; once the first non-option argument has been found, option processing is terminated.

All builtin commands other than echo and precommand modifiers, even those that have no options, can be given the argument -- to terminate option processing. This indicates that the following words are non-option arguments, but is otherwise ignored. This is useful in cases where arguments to the command may begin with -. For historical reasons, most builtin commands (including echo) also recognize a single - in a separate word for this purpose; note that this is less standard and use of -- is recommended.

💅 tiny but iconic note: -- is the recommended “stop reading options” signal. periodt.

✨ `- simple command` ✨

See the section Precommand Modifiers in zshmisc(1).

🦋 `. file [ arg ... ]` 🦋

. file [ arg ... ]

Read commands from file and execute them in the current shell environment.

If file does not contain a slash, or if PATH_DIRS is set, the shell looks in the components of $path to find the directory containing file. Files in the current directory are not read unless . appears somewhere in $path. If a file named file.zwc is found, is newer than file, and is the compiled form (created with the zcompile builtin) of file, then commands are read from that file instead of file.

If any arguments arg are given, they become the positional parameters; the old positional parameters are restored when the file is done executing. However, if no arguments are given, the positional parameters remain those of the calling context, and no restoring is done.

If file was not found the return status is 127; if file was found but contained a syntax error the return status is 126; else the return status is the exit status of the last command executed.

🎀 `: [ arg ... ]` 🎀

: [ arg ... ]

This command does nothing, although normal argument expansions is performed which may have effects on shell parameters. A zero exit status is returned.

💜 `alias` 💜

alias [ {+|-}gmrsL ] [ name[=value] ... ]

For each name with a corresponding value, define an alias with that value. A trailing space in value causes the next word to be checked for alias expansion. If the -g flag is present, define a global alias; global aliases are expanded even if they do not occur in command position:

% perldoc --help 2>&1 | grep 'built-in functions'
    -f   Search Perl built-in functions
% alias -g HG='--help 2>&1 | grep'
% perldoc HG 'built-in functions'
    -f   Search Perl built-in functions

If the -s flag is present, define a suffix alias: if the command word on a command line is in the form text.name, where text is any non-empty string, it is replaced by the text value text.name. Note that name is treated as a literal string, not a pattern. A trailing space in value is not special in this case. For example,

alias -s ps='gv --'

will cause the command *.ps to be expanded to gv -- *.ps. As alias expansion is carried out earlier than globbing, the *.ps will then be expanded. Suffix aliases constitute a different name space from other aliases (so in the above example it is still possible to create an alias for the command ps) and the two sets are never listed together.

For each name with no value, print the value of name, if any. With no arguments, print all currently defined aliases other than suffix aliases. If the -m flag is given the arguments are taken as patterns (they should be quoted to preserve them from being interpreted as glob patterns), and the aliases matching these patterns are printed. When printing aliases and one of the -g, -r or -s flags is present, restrict the printing to global, regular or suffix aliases, respectively; a regular alias is one which is neither a global nor a suffix alias. Using + instead of -, or ending the option list with a single +, prevents the values of the aliases from being printed.

If the -L flag is present, then print each alias in a manner suitable for putting in a startup script. The exit status is nonzero if a name (with no value) is given for which no alias has been defined.

For more on aliases, include common problems, see the section ALIASING in zshmisc(1).

🌈 `autoload` 🌈

autoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ name ... ]

See the section Autoloading Functions in zshmisc(1) for full details. The fpath parameter will be searched to find the function definition when the function is first referenced.

If name consists of an absolute path, the function is defined to load from the file given (searching as usual for dump files in the given location). The name of the function is the basename (non-directory part) of the file. It is normally an error if the function is not found in the given location; however, if the option -d is given, searching for the function defaults to $fpath. If a function is loaded by absolute path, any functions loaded from it that are marked for autoload without an absolute path have the load path of the parent function temporarily prepended to $fpath.

If the option -r or -R is given, the function is searched for immediately and the location is recorded internally for use when the function is executed; a relative path is expanded using the value of $PWD. This protects against a change to $fpath after the call to autoload. With -r, if the function is not found, it is silently left unresolved until execution; with -R, an error message is printed and command processing aborted immediately the search fails, i.e. at the autoload command rather than at function execution..

The flag -X may be used only inside a shell function. It causes the calling function to be marked for autoloading and then immediately loaded and executed, with the current array of positional parameters as arguments. This replaces the previous definition of the function. If no function definition is found, an error is printed and the function remains undefined and marked for autoloading. If an argument is given, it is used as a directory (i.e. it does not include the name of the function) in which the function is to be found; this may be combined with the -d option to allow the function search to default to $fpath if it is not in the given location.

The flag +X attempts to load each name as an autoloaded function, but does not execute it. The exit status is zero (success) if the function was not previously defined and a definition for it was found. This does not replace any existing definition of the function. The exit status is nonzero (failure) if the function was already defined or when no definition was found. In the latter case the function remains undefined and marked for autoloading. If ksh-style autoloading is enabled, the function created will contain the contents of the file plus a call to the function itself appended to it, thus giving normal ksh autoloading behaviour on the first call to the function. If the -m flag is also given each name is treated as a pattern and all functions already marked for autoload that match the pattern are loaded.

With the -t flag, turn on execution tracing; with -T, turn on execution tracing only for the current function, turning it off on entry to any called functions that do not also have tracing enabled.

With the -U flag, alias expansion is suppressed when the function is loaded.

With the -w flag, the names are taken as names of files compiled with the zcompile builtin, and all functions defined in them are marked for autoloading.

The flags -z and -k mark the function to be autoloaded using the zsh or ksh style, as if the option KSH_AUTOLOAD were unset or were set, respectively. The flags override the setting of the option at the time the function is loaded.

Note that the autoload command makes no attempt to ensure the shell options set during the loading or execution of the file have any particular value. For this, the emulate command can be used:

emulate zsh -c 'autoload -Uz func'

arranges that when func is loaded the shell is in native zsh emulation, and this emulation is also applied when func is run.

Some of the functions of autoload are also provided by functions -u or functions -U, but autoload is a more comprehensive interface.

🫶 `bg [ job ... ]` + `job ... &` 🫶

bg [ job ... ]
job ... &

Put each specified job in the background, or the current job if none is specified.

⭐ `bindkey` ⭐

See the section Zle Builtins in zshzle(1).

🔥 `break [ n ]` 🔥

break [ n ]

Exit from an enclosing for, while, until, select or repeat loop. If an arithmetic expression n is specified, then break n levels instead of just one.

👑 `builtin name [ args ... ]` 👑

builtin name [ args ... ]

Executes the builtin name, with the given args.

🌸 `bye` 🌸

Same as exit.

🐚 `cap`

See the section The zsh/cap Module'</cyan> in zshmodules(1)`. bestie it's giving "go read the module page", iykyk ✨

📁 `cd`

cd [ -qsLP ] [ arg ]
cd [ -qsLP ] old new
cd [ -qsLP ] {+|-}n

Okay so this is the "take me somewhere else" builtin, and she has layers 💅

Form one: change the current directory to arg, or to the value of $HOME if arg isn't specified. If arg is -, you go to the previous directory. Iconic little shortcut, no cap 🎀

Otherwise, if arg begins with a slash, just try to change to the directory given by arg. Simple.

If arg does not begin with a slash, the behaviour depends on whether the current directory . occurs in the list of directories contained in the shell parameter cdpath:

If . does not occur there: first attempt to change to the directory arg under the current directory, and if that fails but cdpath is set and contains at least one element, attempt to change to the directory arg under each component of cdpath in turn until successful.
If . does occur in cdpath, then cdpath is searched strictly in order so that . is only tried at the appropriate point.

The order of testing cdpath is modified if the option POSIX_CD is set, as described in the documentation for the option 👑

If no directory is found, the option CDABLE_VARS is set, and a parameter named arg exists whose value begins with a slash, treat its value as the directory. In that case, the parameter is added to the named directory hash table. slay, variable-powered navigation 🌈

Form two: cd substitutes the string new for the string old in the name of the current directory, and tries to change to this new directory. Find-and-replace but make it a location 🦋

Form three: cd extracts an entry from the directory stack and changes to that directory.

An argument of the form +n identifies a stack entry by counting from the left of the list shown by the dirs command, starting with zero.
An argument of the form -n counts from the right.
If the PUSHD_MINUS option is set, the meanings of + and - in this context are swapped 🙃
If the POSIX_CD option is set, this form of cd is not recognised and will be interpreted as the first form. periodt.

Heads up: if the -q (quiet) option is specified, the hook function chpwd and the functions in the array chpwd_functions are not called. This is useful for calls to cd that do not change the environment seen by an interactive user 💖

-s — cd refuses to change the current directory if the given pathname contains symlinks.
-P — symbolic links are resolved to their true values. (Also happens if the CHASE_LINKS option is set.)
-L — symbolic links are retained in the directory (and not resolved) regardless of the state of the CHASE_LINKS option.

🔁 `chdir`

Same as cd. literally the same girl, different name 💫

🧬 `clone`

See the section The zsh/clone Module'</cyan> in zshmodules(1)`.

⚡ `command`

command [ -pvV ] simple command

The simple command argument is taken as an external command instead of a function or builtin, and is executed. If the POSIX_BUILTINS option is set, builtins will also be executed but certain special properties of them are suppressed. Spooky. 👀

-p — causes a default path to be searched instead of that in $path.
-v — command is similar to whence.
-V — equivalent to whence -v.

See also the section Precommand Modifiers'</cyan> in zshmisc(1)` ✨