Slimline

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

Left Prompt

export SLIMLINE_LEFT_PROMPT_SECTIONS="foo |default|"

Right Prompt

export SLIMLINE_RIGHT_PROMPT_SECTIONS="|default| foo"

Spelling Prompt

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.

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.

Exit Status (exit_status)

This section displays the exit status of the last command if it is != 0.

Execution Time (execution_time)

The execution time of the last command if it exceeds the configurable threshold.

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.

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.

AWS Profile (aws_profile)

This section displays the current aws profile detected via the $AWS_PROFILE environment variable.

Python Virtualenv (virtualenv)

This section displays the current python virtual env detected via the $VIRTUAL_ENV environment variable.

Node.js (nodejs) async

This section displays the nodejs version if the current directory contains a package.json file or node_modules directory.

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:

Vi Mode (vi_mode)

This section displays the current vi mode (if active).

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:

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:

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:

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:

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.

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