mirror of
https://github.com/dcarrillo/prezto.git
synced 2024-11-20 08:31:13 +00:00
1ff9421f7b
Zsh and Prezto files don't always reside in `~/`. Instead, they have
a more spec compliant location (`${ZDOTDIR:-$HOME}/`). Make them
unambiguous in the documentation. Likewise, for `$GNUPGHOME`.
Further, add instruction for optionally setting up Prezto in
`$XDG_CONFIG_HOME`.
While at this, also add clarification on relative ordering of some of
the modules, apply more formatting tweaks and doc improvements.
168 lines
4.7 KiB
Markdown
168 lines
4.7 KiB
Markdown
# Prompt
|
|
|
|
Loads prompt [themes][1].
|
|
|
|
## Settings
|
|
|
|
### Prompt Theme
|
|
|
|
To select a prompt theme, add the following to _`${ZDOTDIR:-$HOME}/.zpreztorc`_,
|
|
and replace `'<name>'` with the name of the theme you wish to load. Setting it
|
|
to `'random'` will load a random theme every time.
|
|
|
|
```sh
|
|
zstyle ':prezto:module:prompt' theme '<name>'
|
|
```
|
|
|
|
### Prompt Display Length
|
|
|
|
To change working directory prompt display length from 'short', set the
|
|
following to 'long' (without `~` expansion) or 'full' (with `~` expansion) in
|
|
_`${ZDOTDIR:-$HOME}/.zpreztorc`_.
|
|
|
|
```sh
|
|
zstyle ':prezto:module:prompt' pwd-length 'short'
|
|
```
|
|
|
|
### Display Return Value
|
|
|
|
Some prompts display the return value in the prompt. If a prompt has support,
|
|
this can be disabled with the following snippet.
|
|
|
|
```sh
|
|
zstyle ':prezto:module:prompt' show-return-val 'no'
|
|
```
|
|
|
|
## Theming
|
|
|
|
A prompt theme is an autoloadable function file with a special name,
|
|
`prompt_name_setup`, placed anywhere in `$fpath`, but for the purpose of this
|
|
project, themes **should** be placed in the _modules/prompt/functions_
|
|
directory.
|
|
|
|
### Required Variables
|
|
|
|
To ensure that your function works with the editor-info module you'll need to
|
|
set the following variable in _`${ZDOTDIR:-$HOME}/.zpreztorc`_:
|
|
|
|
```sh
|
|
# Tell prezto we can manage this prompt
|
|
zstyle ':prezto:module:prompt' managed 'yes'
|
|
```
|
|
|
|
This is to ensure compatibility with outside prompts, while allowing prezto
|
|
and prezto-compatible prompts to take full advantage of the editor module.
|
|
This should be set in the `prompt_name_setup` function after you've added
|
|
any additional hooks with `add-zsh-hook precmd prompt_name_precmd`. See below
|
|
for additional information about functions and hooks.
|
|
|
|
### Theme Functions
|
|
|
|
There are three theme functions, a setup function, a help function, and
|
|
a preview function. The setup function **must** always be defined. The help
|
|
function and the preview functions are optional.
|
|
|
|
#### `prompt_name_setup`
|
|
|
|
This function is called by the `prompt` function to install the theme. This
|
|
function may define other functions as necessary to maintain the prompt,
|
|
including a function that displays help or a function used to preview it.
|
|
|
|
**Do not call this function directly.**
|
|
|
|
The most basic example of this function can be seen below.
|
|
|
|
```sh
|
|
function prompt_name_setup {
|
|
PROMPT='%m%# '
|
|
RPROMPT=''
|
|
}
|
|
```
|
|
|
|
#### `prompt_name_help`
|
|
|
|
If the `prompt_name_setup` function is customizable via parameters, a help
|
|
function **should** be defined. The user will access it via `prompt -h name`.
|
|
|
|
The most basic example of this function can be seen below.
|
|
|
|
```sh
|
|
function prompt_name_help {
|
|
cat <<EOH
|
|
This prompt is color-scheme-able. You can invoke it thus:
|
|
|
|
prompt theme [<color1>] [<color2>]
|
|
|
|
where the color is for the left-hand prompt.
|
|
EOH
|
|
}
|
|
```
|
|
|
|
#### `prompt_name_preview`
|
|
|
|
If the `prompt_name_setup` function is customizable via parameters, a preview
|
|
function **should** be defined. The user will access it via `prompt -p name`.
|
|
|
|
The most basic example of this function can be seen below.
|
|
|
|
```sh
|
|
function prompt_name_preview {
|
|
if (( $# > 0 )); then
|
|
prompt_preview_theme theme "$@"
|
|
else
|
|
prompt_preview_theme theme red green blue
|
|
print
|
|
prompt_preview_theme theme yellow magenta black
|
|
fi
|
|
}
|
|
```
|
|
|
|
### Hook Functions
|
|
|
|
There are many Zsh [hook][2] functions, but mostly the _precmd_ hook will be
|
|
used.
|
|
|
|
#### `prompt_name_precmd`
|
|
|
|
This hook is called before the prompt is displayed and is useful for getting
|
|
information to display in a prompt.
|
|
|
|
When calling functions to get information to display in a prompt, do not assume
|
|
that all the dependencies have been loaded. Always check for the availability of
|
|
a function before you calling it.
|
|
|
|
**Do not register hook functions. They will be automatically registered by the
|
|
`prompt` function.**
|
|
|
|
The most basic example of this function can be seen below.
|
|
|
|
```sh
|
|
function prompt_name_precmd {
|
|
if (( $+functions[git-info] )); then
|
|
git-info
|
|
fi
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Fonts aren't displaying properly
|
|
|
|
On most systems, themes which use special characters need to have a patched font
|
|
installed and configured properly.
|
|
|
|
Powerline provides some information on [terminal support][4] and [how to install
|
|
patched fonts][5] which should fix most font issues.
|
|
|
|
## Authors
|
|
|
|
_The authors of this module should be contacted via the [issue tracker][3]._
|
|
|
|
- [Sorin Ionescu](https://github.com/sorin-ionescu)
|
|
|
|
[1]: https://zsh.sourceforge.net/Doc/Release/User-Contributions.html#Prompt-Themes
|
|
[2]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions
|
|
[3]: https://github.com/sorin-ionescu/prezto/issues
|
|
[4]: https://powerline.readthedocs.io/en/master/usage.html#terminal-emulator-requirements
|
|
[5]: https://powerline.readthedocs.io/en/latest/installation.html#fonts-installation
|