LIQUIDPROMPT(7)

NAME
liquidprompt - Liquid Prompt theming

Liquid Prompt has a strong data and theming engine, allowing it to be extremely flexible and customizable.

The Default Theme has a templating engine (previously called "themes" in Liquid Prompt version 1), that allows for custom prompt ordering in the default theme.

If you just want to change icons and/or colors, you can just rely on "presets", which are just regular configuration files. Presets can generally be combined, and some themes may use —or be compatible with— different presets. See Config Options.

Liquid Prompt ships with some Included Themes other than the default as well.

See the Liquid Prompt Theme List on the wiki for user created themes.

If you want to create your own theme, see Custom Themes.

DEFAULT THEME

•   Preview

•   Configuration

•   Templates

•   Template Sections

•   Development environment sections

  Preview

If there is nothing special about the current context, the appearance of Liquid Prompt is similar to that of a default prompt: [image: [user:~] $] [image]

If you are running a background command and are also in the "main" branch of a Git repository on a server: [image: 1& [user@server:~/liquidprompt] main ±] [image]

When Liquid Prompt is displaying nearly everything (a rare event!), it may look like this: [image: 🕤 ⌁24% ⌂1.68 θ90° 3d/2&/1z [user@server:~/ … /liquidprompt/docs/theme ⚞3] [pyenv] main(+10/-5,+3/-1)+* 20s 125 ±] [image]

See Templates for what each section will look like.

  Configuration

As the default theme, all of the normal Config Options are respected.

LP_PS1_FILE: string =
    A template file that is sourced for each prompt. Must set LP_PS1. See Templates for details.

LP_PS1: string =
    If set, the default theme sets PS1 to this value. Not very useful to set it in the config, instead set it in the LP_PS1_FILE.

  Templates

The default theme supports templated sections. Each piece of the theme is saved to a variable, and can be arranged in any order in a template. If you want to change the theme enough to move things around, but not enough to make your own theme, templates will let you change the order of the default theme's pieces.

As the default theme of Liquid Prompt was the only theme until version 2.0, templates were sometimes referred to as "themes" in version 1.X.

For a template file to be loaded, its filepath must be set in LP_PS1_FILE.

A template file does nothing more than set LP_PS1 to a value. The following sections are available to be used.

An example template file is available: minimal.ps1.

  Template Sections

All of the available template sections are listed below. Their order is the default order if the user does not configure a different template. [image: Sections of the prompt.] [image]

NOTE: Omitting a template section from your template will not disable that feature. While it will not be displayed in the prompt, Liquid Prompt does not know that, and will still generate that template section. If you want to speed up your prompt by disabling a section, you must disable it with its respective LP_ENABLE_* option.

LP_PS1_PREFIX: Not actually a part of the default theme, it is used in the default template as the starting section. See LP_PS1_PREFIX and prompt_tag() for details.

LP_TIME
    The current time, displayed as either numeric values or as an analog clock, depending on the value of LP_TIME_ANALOG. See LP_ENABLE_TIME.

LP_BATT
    The current battery status:

•   a green ⏚ (LP_MARK_BATTERY) if charging, above the given threshold, but not charged

•   a yellow ⏚ if charging and under the given threshold

•   a yellow ⌁ (LP_MARK_ADAPTER) if discharging but above the given threshold

•   a red ⌁ if discharging and under the given threshold

    And if LP_PERCENTS_ALWAYS is enabled, also the current battery percent. See LP_ENABLE_BATT.

LP_LOAD
    The average of the processors load, displayed with an intensity color map as load increases. See LP_ENABLE_LOAD.

LP_TEMP
    The highest temperature of the available system sensors, displayed with an intensity color map as temperature increases. See LP_ENABLE_TEMP.

LP_WIFI
    The lowest wireless signal strength, displayed with an intensity color map as strength decreases. See LP_ENABLE_WIFI_STRENGTH.

    New in version 2.1.

LP_JOBS
    The number of detached sessions. See LP_ENABLE_DETACHED_SESSIONS.

    Also the number of running and sleeping shell jobs. See LP_ENABLE_JOBS.

LP_BRACKET_OPEN
    An opening bracket, designed to go around the core of the prompt (generally user, host, current working directory). See LP_MARK_BRACKET_OPEN.

    If running in a terminal multiplexer, will be colored. See LP_COLOR_IN_MULTIPLEXER.

LP_USER
    The current user, in bold yellow if it is root and in light white if it is not the same as the login user. See LP_USER_ALWAYS.

LP_HOST
    A green @ if the connection has X11 support; a yellow one if not.

    The current host – in bold red if you are connected via a telnet connection and blue (or other unique colors) if connected via SSH. See LP_HOSTNAME_ALWAYS.

LP_PERM
    A green colon (LP_MARK_PERM) if the user has write permissions in the current directory and a red one if not. See LP_ENABLE_PERM.

LP_PWD
    The current working directory in bold, shortened if it takes too much space. See LP_ENABLE_SHORTEN_PATH.

LP_DIRSTACK
    The size of the directory stack, prefixed with LP_MARK_DIRSTACK, all colored with LP_COLOR_DIRSTACK. Can be enabled by LP_ENABLE_DIRSTACK.

    New in version 2.0.

LP_BRACKET_CLOSE
    A closing bracket, designed to go around the core of the prompt (generally user, host, current working directory). See LP_MARK_BRACKET_CLOSE.

    If running in a terminal multiplexer, will be colored. See LP_COLOR_IN_MULTIPLEXER.

LP_PROXY
    A ↥ (LP_MARK_PROXY) if an HTTP proxy is in use. See LP_ENABLE_PROXY.

LP_ENVVARS
    Some user-defined environment variable's states. Watched variables should be defined in the LP_ENV_VARS array.

    Set variables are displayed in bold blue, unset variables in blue. See also LP_ENABLE_ENV_VARS.

    New in version 2.2.

LP_SHLVL
    The number of nested shells, prefixed with LP_MARK_SHLVL, all colored with LP_COLOR_SHLVL. Can be disabled by LP_ENABLE_SHLVL.

    New in version 2.1.

LP_DEV_ENV
    Sections related to development environments (see section dev_env below).

    See also LP_MARK_DEV_OPEN, LP_MARK_DEV_MID, and LP_MARK_DEV_CLOSE.

    New in version 2.2.

LP_VCS

•   The name of the current branch if you are in a version control repository (Git, Mercurial, Subversion, Bazaar, or Fossil):

•   in green if everything is up-to-date

•   in red if there are changes

•   in yellow if there are pending commits to push

•   The number of added/deleted lines if changes have been made and the number of pending commits

•   The number of commits ahead/behind the remote tracking branch

•   A yellow + (LP_MARK_STASH) if there are stashed modifications

•   a red * (LP_MARK_UNTRACKED) if there are untracked files in the repository

LP_RUNTIME
    The runtime of the last command, if it has exceeded a certain threshold. See LP_ENABLE_RUNTIME.

LP_ERR
    The error code of the last command, if it is non-zero. See LP_ENABLE_ERROR.

LP_ERR_MEANING
    A guess on the meaning of the last error. See LP_ENABLE_ERROR_MEANING and LP_ERR.

    New in version 2.2.

    LP_MARK_PREFIX Not actually a part of the default theme, it is used in the default template as the last thing before the prompt mark. See LP_MARK_PREFIX for details.

    LP_COLOR_MARK Bold normally, red if you have sudo rights or for the root user.

    Separate from LP_MARK for historical reasons.

LP_MARK
    A smart mark at the end of the prompt:

•   $ or % (LP_MARK_DEFAULT) for a simple user

•   # for the root user

•   ⌘ (LP_MARK_FOSSIL) for Fossil

•   ± (LP_MARK_GIT) for Git

•   ☿ (LP_MARK_HG) for Mercurial

•   ‡ (LP_MARK_SVN) for Subversion

•   ‡± for Git-Subversion

•   |±| (LP_MARK_VCSH) for VCSH

    LP_PS1_POSTFIX Not actually a part of the default theme, it is used in the default template as the final section. See LP_PS1_POSTFIX for details.

  Development environment sections

Version 2.2 of Liquid Prompt introduced a new way to display all sections related to development environments. All the data below are now items in the LP_DEV_ENV list, joined by LP_MARK_DEV_MID and surrounded by LP_MARK_DEV_OPEN and LP_MARK_DEV_CLOSE.

If you want to change the ordering or have different marks for different items, you can derive your own theme template and use the following sections.

LP_SCLS
    The current Red Hat Software Collections environment. See LP_ENABLE_SCLS.

LP_AWS_PROFILE
    The current active AWS Profile. See LP_ENABLE_AWS_PROFILE.

    New in version 2.1.

LP_CONTAINER
    The container status for the current shell. See LP_ENABLE_CONTAINER.

    New in version 2.1.

LP_VENV
    The current Python (or Conda) virtual environment. See LP_ENABLE_VIRTUALENV.

LP_NODE_VENV
    The current Node.js virtual environment. See LP_ENABLE_NODE_VENV.

    New in version 2.1.

LP_PERL_VENV
    The current Perl virtual environment. See LP_ENABLE_PERL_VENV.

    New in version 2.2.

LP_RUBY_VENV
    The current Ruby virtual environment. See LP_ENABLE_RUBY_VENV.

    New in version 2.1.

LP_TFSPACE
    The current Terraform workspace. See LP_ENABLE_TERRAFORM.

    New in version 2.1.

LP_KUBECONTEXT
    The current Kubernetes context. See LP_ENABLE_KUBECONTEXT.

    New in version 2.1.

LP_CMAKE
    Variables from CMake cache configured in this directory:

•   the base name of the compiler (without the path),

•   the configured generator (without spaces, some of them shortened),

•   the build type.

    See LP_ENABLE_CMAKE.

    New in version 2.2.

INCLUDED THEMES

Liquid Prompt ships with some included themes that will have features added to them as they are added to Liquid Prompt.

  Alternate VCS Details Theme

The included themes/alternate_vcs/alternate_vcs.theme file includes a theme extending the default theme but replacing the VCS details display.

•   Alternate VCS

•   Preview

•   Configuration

•   Liquid Prompt Configuration

•   Theme Configuration

•   Features

•   Markers

  Alternate VCS

The alternate_vcs theme is an extension of the default theme.

This prompt is a fully usable theme, designed to be more flexible than the default theme in terms of what VCS information is shown in the prompt.

It is also an example of how to build a theme extending the default theme while replacing one of the template sections.

New in version 2.0.

  Preview

If there is nothing special about the current context, the appearance of Alternate VCS might be as simple as this: [image: [user:~] $] [image]

If you are running a background command and are also in the "main" branch of a Git repository on a server: [image: 1& [user@server:~/liquidprompt] main ±] [image]

When Liquid Prompt is displaying nearly everything, it may look like this: [image: 🕤 ⌁24% ⌂1.68 θ90° 3d/2&/1z [user@server:~/ … /liquidprompt/docs/theme ⚞3] [pyenv] main(U2 ?1 +10/-5,+3/-1)+ 20s 125 ±] [image]

A demo of what disabling the configuration options might look like: [image: [user@server:~/liquidprompt] main(U1 ?1 +8/-1,+1/-3)+ ±] [image]

  Configuration

  Liquid Prompt Configuration

All Liquid Prompt config options are respected, except for:

•   LP_MARK_UNTRACKED when LP_ENABLE_ALT_VCS_STATUS is enabled.

  Theme Configuration

Alternate VCS adds these config options:

  Features

LP_ALWAYS_ALT_VCS_TAG: bool = 0
    Determine when a matching VCS tag should be displayed:

•   0 - Only when there is no current branch or bookmark

•   1 - Always

LP_ENABLE_ALT_VCS_COMMITS: bool = 1
    Display commits ahead or behind the remote tracking branch.

LP_ENABLE_ALT_VCS_DIFF: bool = 1
    Display the number of changed lines.

LP_ENABLE_ALT_VCS_STATUS: bool = 1
    Display the number(s) of changed files, of type staged (if VCS supports staging), non-staged (or non-committed if no staging), and untracked.

    If disabled, a marker will be added to the end of the display to show if there are untracked files (the behavior of the default theme).

  Markers

LP_MARK_ALT_VCS_TAG: string = 🔖
    The marker string used to indicate the following string is a VCS tag.

  Powerline Theme

Deprecated since version 2.2: Use the spun off project Liquid Prompt Powerline instead.

The included themes/powerline/powerline.theme file includes two themes:

•   Powerline

•   Preview

•   Setup

•   Configuration

•   Liquid Prompt Configuration

•   Theme Configuration

•   Markers

•   Colors

•   Powerline Full

•   Preview

•   Setup

•   Configuration

•   Liquid Prompt Configuration

•   Theme Configuration

•   Markers

•   Colors

  Powerline

The powerline theme is a clone of the Powerline prompt. It copies the default segments of the Powerline prompt for Shell.

This prompt is a proof of (a specific) concept: that Liquid Prompt can do what Powerline does, but faster. That said, this is a fully usable theme.

New in version 2.0.

Deprecated since version 2.2: Use the spun off project Liquid Prompt Powerline instead.

  Preview

If there is nothing special about the current context, the appearance of Powerline might be as simple as this: [image:  user  ~ ] [image]

If you are running a background command and are also in the "main" branch of a Git repository on a server: [image:   server  user  ~  liquidprompt  1   main ] [image]

When Liquid Prompt is displaying nearly everything, it may look like this: [image:   server  user  (e) pyenv  ~   …   liquidprompt   …   theme  3   main  ST 1  125 ] [image]

NOTE: The above "everything" image looks like it is missing some parts because this theme does not implement all data sources of Liquid Prompt. This is by design to clone basic Powerline. For a Powerline theme that does show all data sources, see Powerline Full below.

  Setup

By default, the dividers and markers used are the Powerline private characters. You will either need a compatible font, or to configure the dividers and markers to use other characters.

See the Powerline Fonts installation docs for help.

  Configuration

  Liquid Prompt Configuration

The following Liquid Prompt config options are respected:

•   LP_DISABLED_VCS_PATHS

•   LP_ENABLE_BZR

•   LP_ENABLE_COLOR

•   LP_ENABLE_ERROR

•   LP_ENABLE_FOSSIL

•   LP_ENABLE_FQDN

•   LP_ENABLE_GIT

•   LP_ENABLE_HG

•   LP_ENABLE_JOBS

•   LP_ENABLE_RUNTIME_BELL

•   LP_ENABLE_SCREEN_TITLE

•   LP_ENABLE_SHORTEN_PATH

•   LP_ENABLE_SVN

•   LP_ENABLE_TITLE

•   LP_ENABLE_VCS_ROOT

•   LP_ENABLE_VIRTUALENV

•   LP_HOSTNAME_ALWAYS

•   LP_PATH_CHARACTER_KEEP

•   LP_PATH_KEEP

•   LP_PATH_LENGTH

•   LP_PATH_METHOD

•   LP_PATH_VCS_ROOT

•   LP_RUNTIME_BELL_THRESHOLD

•   LP_USER_ALWAYS

  Theme Configuration

Powerline adds these config options:

  Markers

POWERLINE_HARD_DIVIDER: string =  # U+E0B0
    The divider character between sections, defaults to the private character used in Powerline fonts that looks like a solid right arrow.

POWERLINE_PYTHON_ENV_MARKER: string = (e)
    The marker string used to indicate the following string is a Python environment.

POWERLINE_ROOT_MARKER: string = #
    The marker character used to indicate a root session.

POWERLINE_SECURE_MARKER: string =  # U+E0A2
    The marker character used to indicate a SSH session, defaults to the private character used in Powerline fonts that looks like a lock.

POWERLINE_SOFT_DIVIDER: string =  # U+E0B1
    The divider character between similar sections, defaults to the private character used in Powerline fonts that looks like a thin right arrow.

POWERLINE_SPACER: string =   # U+00A0: non-breaking space
    The marker character used to pad sections, defaults to the non-breaking space character.

    To add more padding, add more spaces to this string.

    A non-breaking space is needed in some fonts to prevent multiple spaces from collapsing to one space, loosing the padding.

POWERLINE_STASH_MARKER: string = ST
    The marker string used to indicate stashes exist in the VCS repository.

POWERLINE_VCS_MARKER: string =  # U+E0A0
    The marker character used to indicate a VCS repository, defaults to the private character used in Powerline fonts that looks like a branching commit history.

  Colors

These color config options take an array of integers, which are arguments to lp_terminal_format().

NOTE: Arrays are set without commas (,). The default values are displayed with commas for clarity.

POWERLINE_ERROR_COLOR: array<int> = (231, 52, 0, 0, 7, 1)
    Color for the error code section.

POWERLINE_HOST_COLOR: array<int> = (220, 166, 0, 0, 3, 2)
    Color for the hostname section.

POWERLINE_JOBS_COLOR: array<int> = (220, 166, 0, 0, 3, 2)
    Color for the shell jobs section.

POWERLINE_PATH_COLOR: array<int> = (250, 240, 0, 0, 7, 0)
    Color for the current working directory section.

POWERLINE_PATH_LAST_COLOR: array<int> = (252, 240, 1, 0, 7, 0)
    Color for the current working directory last subsection.

POWERLINE_PATH_SEPARATOR_COLOR: array<int> = (245, 240, 0, 0, 7, 0)
    Color for the current working directory subsection separator.

POWERLINE_PATH_SHORTENED_COLOR: array<int> = (245, 240, 0, 0, 7, 0)
    Color for any sections in the current working directory that are shortened to make the path fit in LP_PATH_LENGTH.

POWERLINE_PATH_VCS_COLOR: array<int> = (147, 240, 1, 0, 4, 0)
    Color for the current working directory segment corresponding to the current VCS repository root directory.

    LP_PATH_VCS_ROOT must be enabled to have any effect.

POWERLINE_PYTHON_ENV_COLOR: array<int> = (231, 74, 0, 0, 7, 4)
    Color for the Python environment section.

POWERLINE_USER_COLOR: array<int> = (231, 31, 1, 0, 7, 6)
    Color for the username section.

POWERLINE_VCS_CLEAN_COLOR: array<int> = (250, 236, 0, 0, 7, 0)
    Color for the VCS section if the repository is clean.

POWERLINE_VCS_DIRTY_COLOR: array<int> = (220, 236, 0, 0, 3, 0)
    Color for the VCS section if the repository is not clean.

POWERLINE_VCS_STASH_COLOR: array<int> = (220, 236, 0, 0, 3, 0)
    Color for the VCS stash subsection.

  Powerline Full

An extension of the powerline theme, powerline_full includes all data sources that Liquid Prompt provides. The ordering is the same as the default theme.

New in version 2.0.

Deprecated since version 2.2: Use the spun off project Liquid Prompt Powerline instead.

  Preview

If there is nothing special about the current context, the appearance of Powerline might be as simple as this: [image:  user  ~ ] [image]

If you are running a background command and are also in the "main" branch of a Git repository on a server: [image:  1&  user   server  ~  liquidprompt  main ] [image]

When Liquid Prompt is displaying nearly everything, it may look like this: [image:  🕤  ⌁24%  ⌂1.68  θ90°  3d/2&/1z  user   server  ~   …   liquidprompt   …   theme  ⚞3  (e) pyenv  main(+10/-5,+3/-1)+*  20s  125 ] [image]

  Setup

Like the powerline theme, you will need a compatible font. See the Powerline Fonts installation docs for help.

  Configuration

  Liquid Prompt Configuration

All Liquid Prompt config options are respected, except for:

•   LP_COLOR_AWS_PROFILE

•   LP_COLOR_CONTAINER

•   LP_COLOR_DIRSTACK

•   LP_COLOR_ERR

•   LP_COLOR_HOST

•   LP_COLOR_IN_MULTIPLEXER

•   LP_COLOR_JOB_D

•   LP_COLOR_JOB_R

•   LP_COLOR_JOB_Z

•   LP_COLOR_KUBECONTEXT

•   LP_COLOR_MARK_ROOT

•   LP_COLOR_MARK_SUDO

•   LP_COLOR_MARK

•   LP_COLOR_NODE_VENV

•   LP_COLOR_NOWRITE

•   LP_COLOR_PATH_ROOT

•   LP_COLOR_PATH

•   LP_COLOR_PERL_VENV

•   LP_COLOR_PROXY

•   LP_COLOR_RUBY_VENV

•   LP_COLOR_RUNTIME

•   LP_COLOR_SHLVL

•   LP_COLOR_SSH

•   LP_COLOR_SU

•   LP_COLOR_TELNET

•   LP_COLOR_TERRAFORM

•   LP_COLOR_TIME

•   LP_COLOR_USER_ALT

•   LP_COLOR_USER_LOGGED

•   LP_COLOR_USER_ROOT

•   LP_COLOR_VIRTUALENV

•   LP_COLOR_WRITE

•   LP_COLOR_X11_OFF

•   LP_COLOR_X11_ON

•   LP_ENABLE_PERM

•   LP_ENABLE_SSH_COLORS

•   LP_ENABLE_SUDO

•   LP_MARK_BRACKET_CLOSE

•   LP_MARK_BRACKET_OPEN

•   LP_MARK_BZR

•   LP_MARK_DEFAULT

•   LP_MARK_DISABLED

•   LP_MARK_FOSSIL

•   LP_MARK_GIT

•   LP_MARK_HG

•   LP_MARK_PERM

•   LP_MARK_PREFIX

•   LP_MARK_PROXY

•   LP_MARK_SVN

•   LP_MARK_VCSH

  Theme Configuration

Powerline Full uses all the config options of the above Powerline theme, except for:

•   POWERLINE_STASH_MARKER

•   POWERLINE_VCS_DIRTY_COLOR

•   POWERLINE_VCS_MARKER

•   POWERLINE_VCS_STASH_COLOR

    Powerline Full adds these config options:

  Markers

POWERLINE_AWS_PROFILE_MARKER: string = AWS:
    The marker string used to indicate the following string is the name of an AWS profile.

    New in version 2.1.

POWERLINE_CHROOT_MARKER: string = chroot:
    The marker string used to indicate the following string is a chroot.

POWERLINE_KUBECONTEXT_MARKER: string = $LP_MARK_KUBECONTEXT
    The marker string used to indicate the following string is the name of a kubectl context.

    New in version 2.1.

POWERLINE_NODE_ENV_MARKER: string = node:
    The marker string used to indicate the following string is a Node.js environment.

    New in version 2.1.

POWERLINE_PERL_ENV_MARKER: string = perl:
    The marker string used to indicate the following string is a Perl environment.

POWERLINE_PROXY_MARKER: string = proxy:
    The marker string used to indicate the following string is a HTTP proxy.

POWERLINE_RUBY_ENV_MARKER: string = ruby:
    The marker string used to indicate the following string is a Ruby environment.

    New in version 2.1.

POWERLINE_SOFTWARE_COLLECTION_MARKER: string = (sc)
    The marker string used to indicate the following string is a Red Hat Software Collection.

POWERLINE_TERRAFORM_ENV_MARKER: string = (tf)
    The marker string used to indicate the following string is a Terraform workspace.

    New in version 2.1.

  Colors

POWERLINE_AWS_PROFILE_COLOR: array<int> = (190, 236, 0, 0, 3, 0)
    Color for the AWS profile section.

    New in version 2.1.

POWERLINE_BATTERY_COLOR: array<int> = (-1, 238, 0, 0, -1, 0)
    Color for the battery section.

POWERLINE_CHROOT_COLOR: array<int> = (219, 30, 0, 0, 7, 4)
    Color for the chroot section.

POWERLINE_CONTAINER_COLOR: array<int> = $POWERLINE_NEUTRAL_COLOR
    Color for the container indicator section.

    New in version 2.1.

POWERLINE_DIRSTACK_COLOR: array<int> = $POWERLINE_NEUTRAL_COLOR
    Color for the directory stack section.

POWERLINE_KUBECONTEXT_COLOR: array<int> = (231, 74, 0, 0, 7, 4)
    Color for the Kubernetes context section.

    New in version 2.1.

POWERLINE_LOAD_COLOR: array<int> = (-1, 148, 0, 0, -1, 3)
    Color for the CPU load section.

POWERLINE_NEUTRAL_COLOR: array<int> = (252, 234, 0, 0, 7, 0)
    Color for all neutral sections, LP_PS1_PREFIX and LP_PS1_POSTFIX.

POWERLINE_NODE_ENV_COLOR: array<int> = $POWERLINE_PYTHON_ENV_COLOR
    Color for the Node.js environment section.

    New in version 2.1.

POWERLINE_PROXY_COLOR: array<int> = (21, 219, 1, 0, 4, 7)
    Color for the HTTP proxy section.

POWERLINE_RUBY_ENV_COLOR: array<int> = $POWELINE_PYTHON_ENV_COLOR
    Color for the Ruby environment section.

    New in version 2.1.

POWERLINE_RUNTIME_COLOR: array<int> = (226, 17, 0, 0, 3, 4)
    Color for the command runtime section.

POWERLINE_SHLVL_COLOR: array<int> = (231, 58, 0, 0, 7, 2)
    Color for the nested shell level section.

    New in version 2.1.

POWERLINE_SOFTWARE_COLLECTIONS_COLOR: array<int> = (231, 62, 0, 0, 7, 5)
    Color for the Red Hat Software Collections section.

POWERLINE_TEMPERATURE_COLOR: array<int> = (-1, 240, 0, 0, -1, 0)
    Color for the temperature section.

POWERLINE_TERRAFORM_ENV_COLOR: array<int> = (231, 182, 0, 0, 7, 4)
    Color for the Terraform workspace.

    New in version 2.1.

POWERLINE_TIME_COLOR: array<int> = (33, 17, 0, 0, 5, 4)
    Color for the current time section.

POWERLINE_WIFI_STRENGTH_COLOR: array<int> = (-1, 148, 0, 0, -1, 3)
    Color for the wireless signal strength section.

    New in version 2.1.

  Unfold Theme

The included themes/unfold/unfold.theme file includes a theme reformatting the default theme to spread it on two lines, with a part of the first line being right-aligned.

•   Unfold

•   Preview

  Unfold

The unfold theme is an reconfiguration of the default theme's structure.

This prompt is a fully usable theme, designed so that:

•   The prompt location is more stable (on the second line).

•   There is a clearer hierarchy between important data (display on the first line, left side), and less important information (first line, right side).

    It is also an example of how to rearrange the prompt's template sections, without touching anything else.

    As such, all the configuration of the default theme is honored.

    New in version 2.2.

  Preview

If there is nothing special about the current context, the appearance of Alternate VCS might be as simple as this: [image]

If you are running a background command and are also in the "main" branch of a Git repository on a server: [image]

When Liquid Prompt is displaying nearly everything, it may look like this: [image]

CUSTOM THEMES

•   Defining a Theme

•   Prompt Function

•   Directory Function

•   Activate Function

•   Version Check Function

•   Other Functions

•   Getting Data

•   Examples

•   Sharing Your Theme

  Defining a Theme

A theme should be contained in one file with a .theme file suffix. There should be no "top level" code in the file, or in other words, all code should be contained in functions. Sourcing the file should run no code, as a user sourcing the theme file might not want to activate it yet.

  Prompt Function

Every theme must have a prompt function that is called for every prompt to generate the prompt. It must be set to _lp_<theme_id>_theme_prompt().

This function could do anything, but generally it should generate a prompt and store it in PS1.

  Directory Function

Optionally, a theme can have a directory function. It must be set to _lp_<theme_id>_theme_directory().

This function is called every time the user changes directories. This allows the theme to only run generating code that depends on the current directory when it is needed.

  Activate Function

Optionally, a theme can have an activate function. It must be set to _lp_<theme_id>_theme_activate().

This function is called when the theme is first activated, and every time the user runs lp_activate(). Prompt pieces that never change (such as hostname and username) should be generated here. This is also where the theme's default values should be set. This function will always be called after the user config is already loaded.

  Version Check Function

Optionally, a theme can have a Liquid Prompt version check function. It must be set to _lp_<theme_id>_theme_version_check().

This function is called when the theme is first activated. It is used to validate that the version of Liquid Prompt is equal to or greater than what the theme requires. Liquid Prompt handles the checking and error handling. Simply set the array variable lp_version_check with the version your theme requires:

_lp_custom_theme_version_check() {
    lp_version_check=(2 2 0 rc 3)
}

The format of the lp_version_check variable matches the inputs of the _lp_version_greatereq() function.

A theme can support more than one version of Liquid Prompt by only enabling parts of the theme if the Liquid Prompt version is high enough. For example:

if _lp_version_greatereq 2 2 0 ; then
    if _lp_disk ; then
        PS1+="my disk status: $lp_disk"
    fi
fi

  Other Functions

If a theme is moderately complicated, it will need other functions defined to help generate a prompt. These should be named following the Functions guidelines concerning underscore prefixes.

The prefix of a function should always be either _<theme_id>_ or _lp_<theme_id>_ to prevent overwriting functions already defined by the user.

  Getting Data

A theme must call Data Functions to be able to display useful information to the user. A theme might also need to use Utility Functions to process that data.

  Examples

The Alternate VCS Details Theme is a good example of creating a theme based on the default theme.

The Powerline Theme is a good example of creating a detailed theme.

  Sharing Your Theme

First see the Theme sharing wiki page for things you should do to make your theme shareable.

The Themes wiki page is where you can share your theme with other users.

•   Switching Themes

•   In a nutshell

•   More Details

SWITCHING THEMES

  In a nutshell

To use a theme, just source its file in your shell configuration file, after having load the liquidprompt, and then call lp_theme:

source <your_path>/liquidprompt
source <your_path>/themes/unfold/unfold.theme
lp_theme unfold

  More Details

Liquid Prompt can switch between themes on the fly. The shell does not need to be reloaded, and no files need to be sourced after the initial source.

To load (but not activate) a theme, simply source the theme file. For example, to load the included Alternate VCS Details theme, source the theme file:

$ source themes/alternate_vcs/alternate_vcs.theme

Now both the default theme and Alternate VCS are loaded. To show what themes are loaded and available, run lp_theme():

$ lp_theme --list
default
alternate_vcs

To switch to a different theme, call lp_theme() with the name of the theme as the argument:

$ lp_theme alternate_vcs

The prompt will immediately take on the new theme.

To switch back to the default theme, call lp_theme() again with default as the argument instead.

If you add the theme source commands to your shell startup file, you will have your favorite themes ready to be switched to at any time.

COPYRIGHT
2011-2024, Liquid Prompt team