Modular, fast and elegant ZSH prompt. Displays the right information at the right time.
Features:
- sleek look
- modular layout using configurable sections in the left and right prompt
- the appearance of each section can be customized using format strings
- easily extensible using custom sections (which can be optionally asynchronous)
- fast non-blocking prompt using asynchronous information display
Sections:
- prompt symbol which indicates if asynchronous tasks are running
- current working directory which highlights if it is outside the home directory
~
- exit code of last command if the exit code is not zero
- runtime of executed command if it exceeds a threshold
- username and hostname if connected to a ssh server or optionally always
- current time of day in 24h or 12h format
- current aws profile
- current python virtualenv
- nodejs version
- customizable git information display
- vi mode indicator
With more information (connected to ssh server, runtime and exit status from last command, aws profile and nodejs version):
- slimline
- Requirements
- Installation
- Sections and Formats
- Legacy Options
- Global Options
- Built-in Sections
- Custom Sections
- Example
- Thanks
- License
- zsh
- python 2.6+ to enable git information display
Choose one of the methods below.
antigen bundle mengelbrecht/slimline
zinit light mengelbrecht/slimline
To compile all source files of slimline use the following command instead:
zinit light-mode compile"{*.zsh,lib/*.zsh,sections/*.zsh,zsh-async/*.zsh}" for mengelbrecht/slimline
zgen load mengelbrecht/slimline
Clone the repository:
git clone --recursive https://github.com/mengelbrecht/slimline.git
Source the prompt in your .zshrc
(or other appropriate) file:
source <path-to-slimline>/slimline.zsh
Slimline has two prompts. The left and right prompt. In each prompt sections can be placed and ordered. The appearance of each section can be completely customized.
A section displays information like the current directory or the git status. Slimline provides a number of sections by default but can also be extended with custom sections. Each sections has a format string which can be customized to change the color or text inside the section.
Inside the format of the section placeholders can be used which will be replaced with information
specific to this section. Placeholders are enclosed in pipes |
, eg. the placeholder |path|
in the cwd
section.
Slimline uses a new option format but supports the previous options as fallback by setting the
variable SLIMLINE_PROMPT_VERSION
to 1
:
export SLIMLINE_PROMPT_VERSION=1 # Activate legacy option format
The legacy options are described here.
Variable | Default Value and Description |
---|---|
SLIMLINE_PROMPT_VERSION |
2 |
The version of the prompt options.
To use the legacy options described here set it to 1 .
|
|
SLIMLINE_ENABLE_ASYNC_AUTOLOAD |
1 |
Defines whether zsh-async should be automatically sourced if it was not already sourced. Disabling the automatic loading is useful if zsh-async is installed globally and loaded using a plugin manager (e.g. via antigen or zplugin). |
Variable | Default Value and Description |
---|---|
SLIMLINE_LEFT_PROMPT_SECTIONS |
user_host_info cwd symbol |
The sections to use in the left prompt. The placeholder |default| expands to
the sections above and can be used to extend the default set of sections.
The following example prepends the section foo to the the default sections of the left prompt:
export SLIMLINE_LEFT_PROMPT_SECTIONS="foo |default|" |
|
SLIMLINE_LEFT_PROMPT_SECTION_SEPARATOR |
|
The separator between each section (a space symbol). | |
SLIMLINE_LEFT_PROMPT_FORMAT |
|sections| |
The format string for the left prompt (notice the space at the end).
The placeholder |sections| will be replaced with the section output.
|
Variable | Default Value and Description |
---|---|
SLIMLINE_RIGHT_PROMPT_SECTIONS |
execution_time exit_status git aws_profile virtualenv nodejs vi_mode |
The sections to use in the right prompt. The placeholder |default| expands to
the sections above and can be used to extend the default set of sections.
The following example appends the section foo to the the default sections of the right prompt:
export SLIMLINE_RIGHT_PROMPT_SECTIONS="|default| foo" |
|
SLIMLINE_RIGHT_PROMPT_SECTION_SEPARATOR |
|
The separator between each section (a space symbol). | |
SLIMLINE_RIGHT_PROMPT_FORMAT |
|sections| |
The format string for the right prompt.
The |sections| placeholder will be replaced with the section output.
|
Variable | Default Value and Description |
---|---|
SLIMLINE_SPELLING_PROMPT_FORMAT |
zsh: correct %F{red}|from|%f to %F{green}|to|%f [nyae]? |
The format string for the spelling prompt which is shown for auto correction.
The |from| placeholder will be replaced with the incorrect command
and |to| with the correction.
|
This section displays the prompt symbol. It supports two formats. The working format is used when asynchronous tasks are pending and the ready format for when all tasks are completed.
Variable | Default Value and Description |
---|---|
SLIMLINE_SYMBOL_WORKING_FORMAT |
%F{red}∙%f |
The format to use for the symbol when there are asynchronous tasks pending. | |
SLIMLINE_SYMBOL_READY_FORMAT |
%F{white}∙%f |
The format to use for the symbol when all asynchronous tasks have completed. |
This section displays the current working directory (cwd). It supports two formats. The root format is used when the cwd is outside of the home directory and the other format if the cwd is inside the home directory.
Variable | Default Value and Description |
---|---|
SLIMLINE_CWD_FORMAT |
%F{cyan}|path|%f |
The format to use when the current working directory is inside the home directory ~ .
The placeholder for the path is |path| .
|
|
SLIMLINE_CWD_ROOT_FORMAT |
%F{red}|path|%f |
The format to use when the current working directory is outside the home directory ~ .
The placeholder for the path is |path| .
|
This section displays the exit status of the last command if it is != 0.
Variable | Default Value and Description |
---|---|
SLIMLINE_EXIT_STATUS_FORMAT |
%F{red}|exit_status| ↵%f |
The format to use when the exit status of the last command is != 0.
The placeholder for the exit status value is |exit_status| .
|
The execution time of the last command if it exceeds the configurable threshold.
Variable | Default Value and Description |
---|---|
SLIMLINE_MAX_EXEC_TIME |
5 |
The maximum execution time of a command in seconds until its run time is displayed on exit. | |
SLIMLINE_EXECUTION_TIME_FORMAT |
%F{yellow}|time|%f |
The format of the execution time display.
The placeholder for the execution time in seconds is |time| .
|
This section displays user and host information and supports two formats. The root format is used if the current user is root. By default the user and host information is only displayed if the user is different than the default user or if there is an active ssh session.
Variable | Default Value and Description |
---|---|
SLIMLINE_ALWAYS_SHOW_USER_HOST_INFO |
0 |
Defines whether the user and host information should always be displayed. | |
SLIMLINE_USER_HOST_INFO_DEFAULT_USER |
$USER |
The default user for this prompt. This is used to hide the user and host name if the current user is the same as the default user. | |
SLIMLINE_USER_HOST_INFO_FORMAT |
%F{green}|user|%F{white}@%F{yellow}|host|%f |
The format of user and host info if the user is not root.
The placeholder for the username is |user| and for the hostname is |host| .
|
|
SLIMLINE_USER_HOST_INFO_ROOT_FORMAT |
%F{red}|user|%F{white}@%F{yellow}|host|%f |
The format of user and host info if the user is root.
The placeholder for the username is |user| and for the hostname is |host| .
|
This section displays the current time in 24h format and is disabled by default.
To use it add it to your left or right prompt manually. To use the 12h time format use the |time12|
placeholder.
Variable | Default Value and Description |
---|---|
SLIMLINE_TIME_FORMAT |
%F{white}|time24|%f |
The format to use for displaying the time of day.
The placeholder for the time in 24h format is |time24| .
The placeholder for the time in 12h format is |time12| .
|
This section displays the current aws profile detected via the $AWS_PROFILE
environment variable.
Variable | Default Value and Description |
---|---|
SLIMLINE_AWS_PROFILE_FORMAT |
%F{white}[AWS:%F{blue}|profile|%F{white}]%f |
The format to use for displaying the aws profile.
The placeholder for the profile is |profile| .
|
This section displays the current python virtual env detected via the $VIRTUAL_ENV
environment variable.
Variable | Default Value and Description |
---|---|
SLIMLINE_VIRTUALENV_FORMAT |
%F{white}[VENV:%F{cyan}|basename|%F{white}]%f |
The format to use for displaying the virtualenv information.
The placeholder for the basename of the virtualenv is |basename| .
|
This section displays the nodejs version if the current directory contains a package.json
file or node_modules
directory.
Variable | Default Value and Description |
---|---|
SLIMLINE_NODEJS_FORMAT |
%F{white}[%F{green}⬢ |version|%F{white}]%f |
The format to use for displaying the nodejs information.
The placeholder for the version of nodejs is |version| .
|
This section displays various git status information. It uses gitline to acquire and format the git information. gitline can be extensively customized. Have a look at the gitline options.
Additionally this section has the following options:
Variable | Default Value and Description |
---|---|
SLIMLINE_GIT_FORMAT |
|output| |
The format to use for the git status information.
The placeholder |output| is replaced with the output from gitline.
|
This section displays the current vi mode (if active).
Variable | Default Value and Description |
---|---|
SLIMLINE_VI_MODE_NORMAL_FORMAT |
%F{white}[%F{blue}N%F{white}]%f |
The format to use for the normal mode. | |
SLIMLINE_VI_MODE_INSERT_FORMAT |
%F{white}[%F{yellow}I%F{white}]%f |
The format to use for the insert mode. | |
SLIMLINE_VI_MODE_REPLACE_FORMAT |
%F{white}[%F{red}R%F{white}]%f |
The format to use for the replace mode. |
This section adds a newline to the prompt which is useful when only a left prompt is used. When setting the right prompt to contain no sections the left prompt can be split into multiple lines using this section. The section can be used multiple times to produce more than two lines.
Custom sections can be easily written by following the slimline section naming scheme. This way sections are automatically discovered and can execute asynchronous tasks easily.
Sections use the namespace slimline::section::<name>
where name is replaced by the
section name. Each section needs at least a render
function.
For example a section with the name foo
needs to implement a render function
named slimline::section::foo::render
.
A section can have the following functions:
Function | Required | Description |
---|---|---|
slimline::section::<name>::render |
yes | This function is used to display information in the prompt. |
slimline::section::<name>::init |
no | This function can initialize data and check for requirements for the section. If the function returns 0 the section will be loaded. In case the section shall be deactivated return 1 instead. |
slimline::section::<name>::preexec |
no | If the function is defined it will be executed right before a new command in zsh is executed. |
slimline::section::<name>::precmd |
no | If the function is defined it will be executed before the prompt render and async task functions. |
slimline::section::<name>::async_task |
no | This function will be executed asynchronously by zsh-async and its output will be available in the async_task_complete function. |
slimline::section::<name>::async_task_complete |
no | This function is not required except when the async_task function is defined. This function will receive the output of the async_task function and other information. |
The render function slimline::section::<name>::render
is responsible for emitting a string
which will be displayed in the prompt.
The function receives the following parameters:
Parameter | Description |
---|---|
$1 |
The event which triggered the render function. This will be one of the following: setup , precmd , task_complete , editor_info . |
Example:
slimline::section::foo::render() {
echo "%F{blue}bar%f"
}
The init function slimline::section::<name>::init
is optional and initializes the section if necessary.
The function receives no parameters and returns 0
on success or 1
on failure.
If the function returns 1
the section will be disabled.
Example:
slimline::section::foo::init() {
if slimline::utils::callable "ruby"; then
return 0 # Ok, section can be loaded
fi
slimline::utils::warning "ruby not installed or not in PATH, disabling foo section"
return 1 # Disable the section
}
The prexec function slimline::section::<name>::preexec
is called using the preexec hook of zsh
before a command is executed. This can be useful to capture the state if a command changes it.
For an example see the execution_time
section.
The function receives no parameters.
The precmd function slimline::section::<name>::precmd
is executed before each prompt and before
all asynchronous task functions.
It can be used to reset variables which are set in an async task function.
This way the render function does not display old data in case the async task has not completed yet.
The function receives no parameters.
Example:
slimline::section::foo::precmd() {
unset slimline_section_foo_output
}
The async task function slimline::section::<name>::async_task
can be used to execute
a command asynchronously. This can greatly improve the speed of the prompt when the
section calls a long-running command. Due to the asynchronous execution the prompt can be instantly
rendered and is automatically updated when the task is ready.
For an example see the git
section or nodejs
section.
The function receives the following parameters:
Parameter | Description |
---|---|
$1 |
The current directory of the prompt. This is important for executing commands because the task function is called from a different context and thus may have a different working directory. |
slimline::section::foo::async_task() {
sleep 2
echo "in directory $1"
}
The async task complete function slimline::section::<name>::async_task_complete
is responsible
for handling the result of the async task.
If the async task function is defined the async task complete function needs to be defined too.
This function can be used to save the stdout output of a command in a global variable which
can be used in the render function.
For an example see the git
section or nodejs
section.
The function receives the following parameters:
Parameter | Description |
---|---|
$1 |
The return code of the task. |
$2 |
The stdout output of the task. |
$3 |
The stderr output of the task. |
$4 |
The execution time of the task as floating point value in seconds, e.g. 0.0258 seconds. |
Example:
slimline::section::foo::async_task_complete() {
slimline_section_foo_output=$2
}
Slimline provides some utility functions to simplify the development of sections.
The function slimline::utils::expand
is used to expand a format string using a set of variables.
The format string is automatically read from an environment variable or uses a default format
when the variable is not set.
The function has the following signature:
slimline::utils::expand <name> <default-format> <variable-name-1> <variable-value-1> <variable-name-2> <variable-value-2> ...
The name
parameter is used to read the format string from the environment variable
SLIMLINE_name_FORMAT
(the name is transformed to uppercase for this).
In the following example the format string is read from the environment variable
SLIMLINE_FOO_FORMAT
and the default value of %F{red}|output|%f
is used when it is not set.
Additionally the format string can contain a placeholder |output|
which is automatically
replaced with bar
.
slimline::utils::expand "foo" "%F{red}|output|%f" "output" "bar"
The following functions can be used to log information. Each function accepts a message as parameter.
Function Signature | Description |
---|---|
slimline::utils::info <message> |
Logs an information. |
slimline::utils::warning <message> |
Logs a warning. |
slimline::utils::error <message> |
Logs an error. |
The function slimline::utils::callable
can be used to check if a function or command
with the given name exists and can be called. This is useful to check if e.g. a specific executable is available.
The function has the following signature:
slimline::utils::callable <name>
This is a minimal section which only implements the required render function.
slimline::section::foo::render() {
echo "%F{blue}bar%f"
}
# Add it to the right prompt
export SLIMLINE_RIGHT_PROMPT_SECTIONS="foo |default|"
This section implements the init function to check if ruby is installed. In case it is not installed a warning is logged and the section will be disabled.
slimline::section::foo::init() {
if slimline::utils::callable "ruby"; then
return 0 # Ok, section can be loaded
fi
slimline::utils::warning "ruby not installed or not in PATH, disabling foo section"
return 1 # Disable the section
}
slimline::section::foo::render() {
echo "%F{blue}bar%f"
}
# Add it to the right prompt
export SLIMLINE_RIGHT_PROMPT_SECTIONS="foo |default|"
This section uses an asynchronous task to emit a string with an artificial 2 second delay.
The asynchronous task output is captured in a global variable in the async_task_complete
function.
To prevent displaying old output the global variable is cleared in the precmd
function.
Finally in the render
function the content of the global variable and the execution time
of the async task is displayed. To simplify the render output the expand
function is used.
slimline::section::foo::precmd() {
unset slimline_section_foo_output
unset slimline_section_foo_time
}
slimline::section::foo::async_task() {
sleep 2
echo "bar"
}
slimline::section::foo::async_task_complete() {
slimline_section_foo_output=$2
slimline_section_foo_time=$4
}
slimline::section::foo::render() {
if [[ -z "${slimline_section_foo_output}" ]]; then return; fi
slimline::utils::expand "foo" "%F{blue}|output|%f - %F{green}|time|%f" \
"output" "${slimline_section_foo_output}" \
"time" "${slimline_section_foo_time}"
}
# Add it to the right prompt
export SLIMLINE_RIGHT_PROMPT_SECTIONS="foo |default|"
Here is an example for customizing the prompt symbol as well as the git repository indicator and branch format:
export SLIMLINE_SYMBOL_READY_FORMAT="%F{white}\$%f"
export SLIMLINE_SYMBOL_WORKING_FORMAT="%F{red}\$%f"
# If you have a powerline compatible font you can also use the alternative repo indicator ''.
export GITLINE_REPO_INDICATOR='${reset}git'
export GITLINE_BRANCH='[${blue}${branch}${reset}]'
source "<path-to-slimline>/slimline.zsh"
Released under the MIT License