You should make sure all the functions from the Functions/Prompts
directory of the source distribution are available; they all begin with
the string ‘prompt_’ except for the special function ‘promptinit’.
You also need the ‘colors’ and ‘add-zsh-hook’ functions from
Functions/Misc.
All these functions may already be installed on your system; if not,
you will need to find them and copy them. The directory should appear as
one of the elements of the fpath array (this should already be the
case if they were installed), and at least the function promptinit
should be autoloaded; it will autoload the rest. Finally, to initialize
the use of the system you need to call the promptinit function. The
following code in your .zshrc will arrange for this; assume the
functions are stored in the directory ~/myfns:
fpath=(~/myfns $fpath) autoload -U promptinit promptinit
Use the prompt command to select your preferred theme. This command
may be added to your .zshrc following the call to promptinit in
order to start zsh with a theme already selected.
prompt [ -c | -l ]prompt [ -p | -h ] [ theme ... ]prompt [ -s ] theme [ arg ... ]Set or examine the prompt theme. With no options and a theme
argument, the theme with that name is set as the current theme. The
available themes are determined at run time; use the -l option to see
a list. The special theme ‘random’ selects at random one of the
available themes and sets your prompt to that.
In some cases the theme may be modified by one or more arguments, which should be given after the theme name. See the help for each theme for descriptions of these arguments.
Options are:
-cShow the currently selected theme and its parameters, if any.
-lList all available prompt themes.
-pPreview the theme named by theme, or all themes if no theme is given.
-hShow help for the theme named by theme, or for the
prompt function if no theme is given.
-sSet theme as the current theme and save state.
prompt_theme_setupEach available theme has a setup function which is called by the
prompt function to install that theme. This function may define
other functions as necessary to maintain the prompt, including functions
used to preview the prompt or provide help for its use. You should not
normally call a theme’s setup function directly.
prompt offThe theme ‘off’ sets all the prompt variables to minimal values with
no special effects.
prompt defaultThe theme ‘default’ sets all prompt variables to the same state as
if an interactive zsh was started with no initialization files.
prompt restoreThe special theme ‘restore’ erases all theme settings and sets prompt
variables to their state before the first time the ‘prompt’ function
was run, provided each theme has properly defined its cleanup (see below).
Note that you can undo ‘prompt off’ and ‘prompt default’ with
‘prompt restore’, but a second restore does not undo the first.
The first step for adding your own theme is to choose a name for it,
and create a file ‘prompt_name_setup’ in a directory in your
fpath, such as ~/myfns in the example above. The file should
at minimum contain assignments for the prompt variables that your
theme wishes to modify. By convention, themes use PS1, PS2,
RPS1, etc., rather than the longer PROMPT and RPROMPT.
The file is autoloaded as a function in the current shell context, so it may contain any necessary commands to customize your theme, including defining additional functions. To make some complex tasks easier, your setup function may also do any of the following:
prompt_optsThe array prompt_opts may be assigned any of "bang", "cr",
"percent", "sp", and/or "subst" as values. The corresponding
setopts (promptbang, etc.) are turned on, all other prompt-related
options are turned off. The prompt_opts array preserves setopts even
beyond the scope of localoptions, should your function need that.
Use of add-zsh-hook and add-zle-hook-widget is recommended (see
the Manipulating Hook Functions section above).
All hooks that follow the naming pattern prompt_theme_hook
are automatically removed when the prompt theme changes or is disabled.
If your function makes any other changes that should be undone when the theme is disabled, your setup function may call
prompt_cleanup command
where command should be suitably quoted. If your theme is ever
disabled or replaced by another, command is executed with eval.
You may declare more than one such cleanup hook.
Define or autoload a function prompt_name_preview to display
a simulated version of your prompt. A simple default previewer is
defined by promptinit for themes that do not define their own.
This preview function is called by ‘prompt -p’.
Define or autoload a function prompt_name_help to display
documentation or help text for your theme.
This help function is called by ‘prompt -h’.