Generators documentation
This commit is contained in:
parent
746010bfea
commit
89f176d66f
1 changed files with 185 additions and 0 deletions
185
README.md
185
README.md
|
|
@ -114,3 +114,188 @@ title and/or icon title:
|
||||||
string (unicode characters in the generators' output will be removed).
|
string (unicode characters in the generators' output will be removed).
|
||||||
* `term_separator` is a string that will be inserted between the various parts
|
* `term_separator` is a string that will be inserted between the various parts
|
||||||
of the string.
|
of the string.
|
||||||
|
|
||||||
|
Generators also require specific configuration variables. These are documented
|
||||||
|
in the generators' sections below.
|
||||||
|
|
||||||
|
### Theme files
|
||||||
|
|
||||||
|
Themes are also stored using Perl hashes. The file containing a theme `x` should
|
||||||
|
be named `x.pm` and located in one of the configured theme directories.
|
||||||
|
|
||||||
|
The following entries are used by the script's core :
|
||||||
|
|
||||||
|
* `padding` must contain a single character which is used for padding the top
|
||||||
|
line's middle area, amongst other things.
|
||||||
|
* `transition` may contain a list of up to 8 color indices which can be used
|
||||||
|
when generating transition strings from templates.
|
||||||
|
* 5 entries control each section's appearance.
|
||||||
|
* The sections are identified by `left`, `middle`, `right` and `input` (top
|
||||||
|
left, top middle, top right and bottom left, respectively).
|
||||||
|
* Each section uses the following entries (replacing `${section}` with a
|
||||||
|
section's identifier):
|
||||||
|
* `bg_${section}` is the index of the background color of the section.
|
||||||
|
* `fg_${section}` is the index of the foreground color of the section.
|
||||||
|
* `${section}_prefix` is the template for the prefix of the section.
|
||||||
|
* `${section}_separator` is the template for the separator that is inserted
|
||||||
|
between generated areas in the section.
|
||||||
|
* `${section}_suffix` is the template for the suffix of the section.
|
||||||
|
* `bg_ps2` is the index of the background color of the secondary prompt.
|
||||||
|
* `ps2_suffix` is the template for the suffix of the secondary prompt.
|
||||||
|
|
||||||
|
Templates are strings which may contain `\bX` and `\fX` escape sequences, where
|
||||||
|
`X` is a single digit, and which modify the background or foreground colors,
|
||||||
|
respectively. Values `0` and `1` correspond to the preceding and following
|
||||||
|
background color indices, while values between `2` and `9` will refer to the
|
||||||
|
contents of the `transition` list.
|
||||||
|
|
||||||
|
In addition to the entries above, theme definitions contain entries that are
|
||||||
|
specific to the various generators. These entries are documented below. When
|
||||||
|
the generator-specific entries list color indices, the special `-1` value may
|
||||||
|
be used to indicate that the current area's foreground or background color
|
||||||
|
should be used.
|
||||||
|
|
||||||
|
## Generators
|
||||||
|
|
||||||
|
### Current working directory
|
||||||
|
|
||||||
|
The `cwd` generator will output the current working directory. Its only
|
||||||
|
configuration variable, `cwd_max_width`, indicates the maximal percentage of the
|
||||||
|
terminal's width that the path may occupy before truncation occurs. The
|
||||||
|
following theme entries are required:
|
||||||
|
|
||||||
|
* `cwd_trunc` is the string that replaces the part of the path that is truncated
|
||||||
|
when it is too long compared to the terminal's width.
|
||||||
|
* `cwd_fg_color` and `cwd_bg_color` are the foreground and background color
|
||||||
|
indices for the section.
|
||||||
|
|
||||||
|
### Date/time
|
||||||
|
|
||||||
|
The `datetime` generator will output the current date, the current time, or
|
||||||
|
both. It is controlled by the following configuration entries:
|
||||||
|
|
||||||
|
* `dt_show_date` controls whether the date should be displayed.
|
||||||
|
* `dt_show_time` controls whether the time should be displayed.
|
||||||
|
* `dt_date_fmt` is a `strftime` format that will be used for the date.
|
||||||
|
* `dt_time_fmt` is a `strftime` format that will be used for the date.
|
||||||
|
|
||||||
|
In addition, the following entries must be set in the theme:
|
||||||
|
|
||||||
|
* `dt_bg` is the background color for the section.
|
||||||
|
* `dt_time_fg` is the foreground color for the time.
|
||||||
|
* `dt_date_fg` is the foreground color for the date.
|
||||||
|
|
||||||
|
### Git information
|
||||||
|
|
||||||
|
The `git` generator is meant to display information about the Git repository the
|
||||||
|
current directory is a part of. It is controlled by the following configuration
|
||||||
|
entries:
|
||||||
|
|
||||||
|
* `git_branch_danger` is a list of branch names that will cause the current
|
||||||
|
branch to be displayed with the "danger" color set.
|
||||||
|
* `git_branch_warn` is a list of branch names that will cause the current branch
|
||||||
|
to be displayed with the "warning" color set.
|
||||||
|
* `git_detached_warning` controls the color set that will be used when the head
|
||||||
|
is detached: `0` for the normal set, `1` for the "warning" set and `2` for the
|
||||||
|
"danger" set.
|
||||||
|
* `git_show_status` controls whether the status of the current repository should
|
||||||
|
be displayed.
|
||||||
|
* `git_show_stash` controls whether the stash depth should be displayed.
|
||||||
|
|
||||||
|
The theme entries belowed control the Git information sections' appearance:
|
||||||
|
|
||||||
|
* `git_branch_symbol` is the prefix for the current branch's name.
|
||||||
|
* The color sets for the branch display section are controlled by entries named
|
||||||
|
`git_branch_${set}_fg` and `git_branch_${set}_bg`. The `${set}` must be one of
|
||||||
|
`ok`, `warn` or `danger`.
|
||||||
|
* `git_repstate_bg` / `git_repstate_fg` are the colors of the section that
|
||||||
|
indicates special states (e.g. rebase in progress, bare repository...)
|
||||||
|
* `git_status_pad` is a string that will be inserted between the various parts
|
||||||
|
of the status sections.
|
||||||
|
* Two sets of entries control the sections that correspond to untracked and
|
||||||
|
indexed changes. These sections are identified by replacing `${type}` with
|
||||||
|
either `untracked` and `indexed` in the names below.
|
||||||
|
* `git_${type}_symbol` is the prefix for the section's text,
|
||||||
|
* `git_${type}_bg` is the background color for the section,
|
||||||
|
* `git_${type}_normal_fg` is the foreground color for the normal text in the
|
||||||
|
section,
|
||||||
|
* `git_${type}_add_fg`, `git_${type}_mod_fg` and `git_${type}_del_fg` define
|
||||||
|
the foreground colors for the symbols that indicate new, modified or removed
|
||||||
|
files, respectively.
|
||||||
|
* `git_add_symbol`, `git_mod_symbol` and `git_del_symbol` define the symbols
|
||||||
|
that indicate new, modified or deleted files in the status sections.
|
||||||
|
* `git_stash_symbol` contains the prefix of the stash indicator,
|
||||||
|
* `git_stash_fg` and `git_stash_fg` define the background and foreground colors
|
||||||
|
for the stash indicator.
|
||||||
|
|
||||||
|
### System load
|
||||||
|
|
||||||
|
The `load` generator will output the system's load average for the past minute
|
||||||
|
divided by the host's processor count. It is controlled by the `load_min`
|
||||||
|
configuration entry which specifies a percentage below which the section is not
|
||||||
|
displayed at all. The following theme entries are required:
|
||||||
|
|
||||||
|
* `load_title` is a string that is prepended to the generator's output.
|
||||||
|
* `load_low_fg` and `load_low_bg` are the foreground and background colors used
|
||||||
|
when the load is beneath 34%.
|
||||||
|
* `load_med_fg` and `load_med_bg` are the foreground and background colors used
|
||||||
|
when the load is between 34% and 66%.
|
||||||
|
* `load_high_fg` and `load_high_bg` are the foreground and background colors
|
||||||
|
used when the load is higher than 66%.
|
||||||
|
|
||||||
|
### Previous command state
|
||||||
|
|
||||||
|
The `prevcmd` generator will output information about the previous command's
|
||||||
|
return value. It is controlled by the following configuration entries:
|
||||||
|
|
||||||
|
* `pcmd_show_symbol` controls whether a symbol that represents success or
|
||||||
|
failure should be displayed.
|
||||||
|
* `pcmd_show_code` controls whether the return value should be displayed. It
|
||||||
|
can be set to the usual `0` and `1` values to disable/enable, or to `2` to
|
||||||
|
enable only when the return value indicates failure.
|
||||||
|
* `pcmd_pad_code` controls padding of the return value. `0` disables padding,
|
||||||
|
`1` aligns to the left and `-1` to the right. The global padding character
|
||||||
|
is used.
|
||||||
|
* `pcmd_colors` selects which parts of the output should use the theme's success
|
||||||
|
or failure colors (`0` nothing, `1` symbol, `2` value, `3` both).
|
||||||
|
|
||||||
|
The following theme entries are needed:
|
||||||
|
|
||||||
|
* `pcmd_ok_sym` / `pcmd_err_sym` contain the symbols that represent success or
|
||||||
|
failure, respectively.
|
||||||
|
* `pcmd_ok_fg` and `pcmd_ok_bg` define the foreground and background colors used
|
||||||
|
to represent success. The foreground color may or may not be used, depending
|
||||||
|
on the configuration.
|
||||||
|
* `pcmd_err_fg` and `pcmd_err_bg` define the foreground and background colors
|
||||||
|
used to represent failure. The foreground color may or may not be used,
|
||||||
|
depending on the configuration.
|
||||||
|
* `pcmd_text_fg` controls the foreground color of the strings that are excluded
|
||||||
|
from using success/failure colors by the configuration.
|
||||||
|
|
||||||
|
### Python virtual environment
|
||||||
|
|
||||||
|
The `pyenv` generator will output the name of the currently active Python
|
||||||
|
virtual environment if there is one. The following theme entries are needed:
|
||||||
|
|
||||||
|
* `pyenv_fg` and `pyenv_bg` define the foreground and background colors for the
|
||||||
|
section.
|
||||||
|
|
||||||
|
### User/host
|
||||||
|
|
||||||
|
The `userhost` generator will output the current user and host name. It is
|
||||||
|
controlled by the following configuration entries:
|
||||||
|
|
||||||
|
* `uh_username` controls whether the user name should be displayed.
|
||||||
|
* `uh_hostname` controls whether the host name should be displayed. It can be
|
||||||
|
set to `0` (hidden), `1` (always display) or `2` (display on remote hosts
|
||||||
|
only).
|
||||||
|
* `uh_remote` can be set to `1` in order to display an additional string on
|
||||||
|
remote hosts.
|
||||||
|
|
||||||
|
In addition, the following entries must be set in the theme:
|
||||||
|
|
||||||
|
* `uh_remote_symbol` is the string to append to the section on remote hosts.
|
||||||
|
* `dt_user_fg` and `dt_user_bg` contain the foreground and background colors
|
||||||
|
to use for normal, unprivileged users.
|
||||||
|
* `dt_root_fg` and `dt_root_bg` contain the foreground and background colors
|
||||||
|
to use for the `root` account.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue