mengelbrecht / slimline

Minimal, customizable, fast and elegant ZSH prompt

slimline

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
  • Optional
• Installation
  • antigen
  • zinit
  • zgen
  • Manually
• Sections and Formats
• Legacy Options
• Global Options
  • Left Prompt
  • Right Prompt
  • Spelling Prompt
• Built-in Sections
  • Prompt Symbol (symbol)
  • Current Working Directory (cwd)
  • Exit Status (exit_status)
  • Execution Time (execution_time)
  • User and Host Info (user_host_info)
  • Time (time)
  • AWS Profile (aws_profile)
  • Python Virtualenv (virtualenv)
  • Node.js (nodejs) async
  • Git (git) async
  • Vi Mode (vi_mode)
• Custom Sections
  • Functions
    • Render
    • Init
    • Preexec
    • Precmd
    • Async Task
    • Async Task Complete
  • Utility Functions
    • Section Format Expansion
    • Logging
    • Callable Check
  • Complete Section Examples
    • Minimal Section
    • Section with init function
    • Section with asynchronous task
• Example
• Thanks
• License

Requirements

• zsh

Optional

• python 2.6+ to enable git information display

Installation

Choose one of the methods below.

antigen

antigen bundle mengelbrecht/slimline

zinit

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

zgen load mengelbrecht/slimline

Manually

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

Sections and Formats

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.

Legacy Options

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.

Global Options

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).

Left Prompt

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.

Right Prompt

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.

Spelling Prompt

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.

Built-in Sections

Prompt Symbol (symbol)

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.

Current Working Directory (cwd)

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|.

Exit Status (exit_status)

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|.

Execution Time (execution_time)

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|.

User and Host Info (user_host_info)

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|.

Time (time)

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|.

AWS Profile (aws_profile)

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|.

Python Virtualenv (virtualenv)

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|.

Node.js (nodejs) async

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|.

Git (git) async

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.

Vi Mode (vi_mode)

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.

Newline (newline)

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

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.

Functions

Render

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"
}

Init

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
}

Preexec

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.

Precmd

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
}

Async Task

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"
}

Async Task Complete

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
}

Utility Functions

Slimline provides some utility functions to simplify the development of sections.

Section Format Expansion

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"

Logging

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.

Callable Check

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>

Complete Section Examples

Minimal Section

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|"

Section with init function

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|"

Section with asynchronous task

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|"

Example

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"

Thanks

• mafredri/zsh-async
• sindresorhus/pure
• denysdovhan/spaceship-prompt
• sorin-ionescu/prezto

License

Released under the MIT License