Welcome to Liquidprompt’s documentation!

Liquidprompt is an adaptive prompt for Bash & Zsh that gives you a nicely displayed prompt with useful information when you need it. It does this with a powerful theming engine and a large array of data sources.

To get started, view the Installation documentation, which includes instructions for trying Liquidprompt temporarily.

Installation

Packages

Liquidprompt is packaged for many operating systems, though the latest version in those repositories is not always up to date.

Latest Versions

Source: repology.org.

Install commands

Archlinux

pacman -S liquidprompt

Debian

… and Debian derivatives.

apt-get install liquidprompt

A small script, liquidprompt_activate (not to be confused with lp_activate()) is included to ease activation of the prompt, which can be used instead of the Shell Installation instructions.

This will set the required environment:

• The files ~/.bashrc and/or ~/.zshrc are modified to load Liquidprompt at startup.

• If no previous ~/.config/liquidpromptrc file exists, it will be created.

So, to get Liquidprompt working simply run:

liquidprompt_activate
source ~/.bashrc  # or ~/.zshrc

Be aware that multiple invocations of the liquidprompt_activate command may pollute ~/.bashrc and/or ~/.zshrc files.

Homebrew

brew install liquidprompt

Nix

nix-env -i liquidprompt

Download

You can either download the latest release from Github, or using your OS package manager with our Packages.

To download to ~/liquidprompt, run:

git clone --branch stable https://github.com/nojhan/liquidprompt.git ~/liquidprompt

Or, if you want to use the development (non-stable) branch:

git clone https://github.com/nojhan/liquidprompt.git ~/liquidprompt

If you do not have git, you can download and extract the source in zip or gzip format directly from the release page.

Installation via Antigen

To install via Antigen, simply add the following line in your .zshrc after activating Antigen:

antigen bundle nojhan/liquidprompt

Dependencies

Liquidprompt uses commands that should be available on a large variety of Unix systems:

• awk

• grep

• logname

• ps

• sed

• uname

• who

Some features depend on specific commands. If you do not install them, the corresponding feature will not be available, but no error will be displayed. See the Config Options for more information about available features and what tools they require.

• Battery status requires acpi on GNU/Linux.

• Temperature status requires acpi or sensors on GNU/Linux.

• Terminal formatting requires tput.

• Detached session status looks for screen and/or tmux.

• VCS support features require git, hg, svn, bzr or fossil for their respective repositories.

Test Drive

To test the prompt immediately after download, run:

source ~/liquidprompt/liquidprompt

Adjust the path if you installed to a different location that the suggested ~/liquidprompt.

Shell Installation

To use Liquidprompt every time you start a shell, add the following lines to your .bashrc (if you use Bash) or .zshrc (if you use zsh):

# Only load Liquidprompt in interactive shells, not from a script or from scp
[[ $- = *i* ]] && source ~/liquidprompt/liquidprompt

Adjust the path if you installed to a different location that the suggested ~/liquidprompt.

Warning

Check in your .bashrc that the PROMPT_COMMAND variable is not set, or else the prompt will not be available. If you must set it or use a add-on that sets it, make sure to set PROMPT_COMMAND before you source Liquidprompt to avoid history and timing issues. Do not export PROMPT_COMMAND.

Next up are the Config Options.

Config Options

Almost every feature in Liquidprompt can be turned on or off using these config options. They can either be set before sourcing Liquidprompt (in .bashrc or .zshrc), or set in a Liquidprompt config file.

Note

Config variables set in a config file take precedence over variables set in the environment or on the command line. Setting a config option on the command line, then running lp_activate() will overwrite that option with the value from the config file, if it is set there.

The config file is searched for in the following locations:

• ~/.liquidpromptrc

• $XDG_CONFIG_HOME/liquidpromptrc - (if XDG_CONFIG_HOME is not set, ~/.config is used)

• $XDG_CONFIG_DIRS/liquidpromptrc - XDG_CONFIG_DIRS is a : delimited array, each value is searched. (if XDG_CONFIG_DIRS is not set, /etc/xdg is used)

• /etc/liquidpromptrc

The first file found is sourced.

Liquidprompt ships with an example config file, liquidpromptrc-dist. You can start from this file for your config:

cp ~/liquidprompt/liquidpromptrc-dist ~/.config/liquidpromptrc

Note

The example config file does not include every config option, and the comments describing the options are less verbose than the descriptions on this page.

Each config option is documented with its default value. Options of type bool accept values of 1 for true and 0 for false.

General

LP_MARK_PREFIX: string = " "

String added directly before LP_MARK_DEFAULT, after all other parts of the prompt. Can be used to tag the prompt in a way that is less intrusive than LP_PS1_PREFIX.

LP_PATH_CHARACTER_KEEP: int = 3

The number of characters to save at the start and possibly the end of a directory name when shortening the path. See LP_PATH_METHOD for details of the specific methods.

LP_PATH_DEFAULT: string

Deprecated since version 2.0: Use LP_PATH_METHOD set to “truncate_to_last_dir” instead.

Used to define the string used for the path. Could be used to make use of shell path shortening features, like %2~ in Zsh to keep the last two directories of the path.

LP_ENABLE_SHORTEN_PATH must be disabled to have any effect.

LP_PATH_KEEP: int = 2

The number of directories (counting ‘/’) to display at the beginning of a shortened path.

Set to 1, will display only root. Set to 0, will keep nothing from the beginning of the path.

LP_ENABLE_SHORTEN_PATH must be enabled to have any effect.

See also: LP_PATH_LENGTH and LP_PATH_METHOD.

Changed in version 2.0: No longer supports a value of -1.

LP_PATH_LENGTH: int = 35

The maximum percentage of the terminal width used to display the path before removing the center portion of the path and replacing with LP_MARK_SHORTEN_PATH.

LP_ENABLE_SHORTEN_PATH must be enabled to have any effect.

Note

LP_PATH_KEEP and LP_PATH_METHOD have higher precedence over this option. Important path parts, including directories saved by LP_PATH_KEEP, LP_PATH_VCS_ROOT, and the last directory, will always be displayed, even if the path does not fit in the maximum length.

LP_PATH_METHOD: string = "truncate_chars_from_path_left"

Sets the method used for shortening the path display when it exceeds the maximum length set by LP_PATH_LENGTH.

• truncate_chars_from_path_left: Truncates characters from the start of the path, showing consecutive directories as one shortened section. E.g. in a directory named ~/MyProjects/Liquidprompt/tests, it will be shortened to ...prompt/tests. The shortened mark is LP_MARK_SHORTEN_PATH.

• truncate_chars_from_dir_right: Leaves the beginning of a directory name untouched. E.g. directories will be shortened like so: ~/Doc.../Office. How many characters will be untouched is set by LP_PATH_CHARACTER_KEEP. The shortened mark is LP_MARK_SHORTEN_PATH.

• truncate_chars_from_dir_middle: Leaves the beginning and end of a directory name untouched. E.g. in a directory named ~/MyProjects/Office, then it will be shortened to ~/MyS...cts/Office. How many characters will be untouched is set by LP_PATH_CHARACTER_KEEP. The shortened mark is LP_MARK_SHORTEN_PATH.

• truncate_chars_to_unique_dir: Truncate each directory to the shortest unique starting portion of their name. E.g. in a folder ~/dev/liquidprompt, it will be shortened to ~/d/liquidprompt if there is no other directory starting with ‘d’ in the home directory.

• truncate_to_last_dir: Only display the last directory in the path. In other words, the current directory name.

All methods (other than ‘truncate_to_last_dir’) start at the far left of the path (limited by LP_PATH_KEEP). Only the minimum number of directories needed to fit inside LP_PATH_LENGTH will be shortened.

LP_ENABLE_SHORTEN_PATH must be enabled to have any effect.

LP_PATH_VCS_ROOT: bool = 1

Display the root directory of the current VCS repository with special formatting, set by LP_COLOR_PATH_VCS_ROOT. If LP_ENABLE_SHORTEN_PATH is enabled, also prevent the path shortening from shortening or hidding the VCS root directory.

LP_PS1_POSTFIX: string = ""

A string displayed at the very end of the prompt, after even the prompt mark. LP_MARK_PREFIX is an alternative that goes before the prompt mark.

LP_PS1_PREFIX: string = ""

A string displayed at the start of the prompt. Can also be set with prompt_tag().

Features

LP_DISABLED_VCS_PATH: string = ""

Deprecated since version 2.0: Use LP_DISABLED_VCS_PATHS instead.

An colon (:) separated list of absolute directory paths where VCS features will be disabled. See LP_DISABLED_VCS_PATHS for more information.

LP_DISABLED_VCS_PATHS: array<string> = ()

An array of absolute directory paths where VCS features will be disabled. Generally this would be used for repositories that are large and slow, where generating VCS information for the prompt would impact prompt responsiveness.

Any subdirectory under the input directory is also disabled, so setting “/repos” would disable VCS display when the current directory is “/repos/a-repo”. Setting ("/") would disable VCS display completely.

An example value would be:

LP_DISABLED_VCS_PATHS=("/a/svn/repo" "/home/me/my/large/repo")

See also: LP_MARK_DISABLED.

LP_ENABLE_BATT: bool = 1

Display the status of the battery, if there is one, using color and marks. Add battery percentage colored with LP_COLORMAP if LP_PERCENTS_ALWAYS is enabled.

Will be disabled if acpi is not found on Linux, or pmset is not found on MacOS.

See also: LP_BATTERY_THRESHOLD, LP_MARK_BATTERY, LP_MARK_ADAPTER, LP_COLOR_CHARGING_ABOVE, LP_COLOR_CHARGING_UNDER, LP_COLOR_DISCHARGING_ABOVE, and LP_COLOR_DISCHARGING_UNDER.

LP_ENABLE_BZR: bool = 1

Display VCS information inside Bazaar repositories.

Will be disabled if bzr is not found.

See also: LP_MARK_BZR.

LP_ENABLE_COLOR: bool = 1

Use terminal formatting when displaying the prompt.

Note

Not all formatting is correctly disabled if this option is disabled.

Will be disabled if tput is not found.

New in version 2.0.

LP_ENABLE_DETACHED_SESSIONS: bool = 1

Display the number of detached multiplexer sessions.

Will be disabled if neither screen nor tmux are found.

Note

This can be slow on some machines, and prompt speed can be greatly improved by disabling it.

See also: LP_COLOR_JOB_D.

New in version 2.0.

LP_ENABLE_DIRSTACK: bool = 0

Display the size of the directory stack if it is greater than 1.

See also: LP_MARK_DIRSTACK and LP_COLOR_DIRSTACK.

New in version 2.0.

LP_ENABLE_ERROR: bool = 1

Display the last command error code if it is not 0.

See also: LP_COLOR_ERR.

New in version 2.0.

LP_ENABLE_FOSSIL: bool = 1

Display VCS information inside Fossil repositories.

Will be disabled if fossil is not found.

See also: LP_MARK_FOSSIL.

LP_ENABLE_FQDN: bool = 0

Use the fully qualified domain name (FQDN) instead of the short hostname when the hostname is displayed.

See also: LP_HOSTNAME_ALWAYS.

LP_ENABLE_GIT: bool = 1

Display VCS information inside Git repositories.

Will be disabled if git is not found.

See also: LP_MARK_GIT.

LP_ENABLE_HG: bool = 1

Display VCS information inside Mercurial repositories.

Will be disabled if hg is not found.

See also: LP_MARK_HG.

LP_ENABLE_JOBS: bool = 1

Display the number of running and sleeping shell jobs.

See also: LP_COLOR_JOB_R and LP_COLOR_JOB_Z.

LP_ENABLE_LOAD: bool = 1

Display the load average over the past 1 minutes when above the threshold.

See also: LP_LOAD_THRESHOLD, LP_LOAD_CAP, LP_MARK_LOAD, LP_PERCENTS_ALWAYS, and LP_COLORMAP.

LP_ENABLE_PERM: bool = 1

Display a colored LP_MARK_PERM in the prompt to show when the user does not have write permission to the current directory.

See also: LP_COLOR_WRITE and LP_COLOR_NOWRITE.

LP_ENABLE_PROXY: bool = 1

Display a LP_MARK_PROXY mark when an HTTP proxy is detected.

See also: LP_COLOR_PROXY.

LP_ENABLE_RUNTIME: bool = 1

Display runtime of the previous command if over LP_RUNTIME_THRESHOLD.

See also: LP_COLOR_RUNTIME.

LP_ENABLE_RUNTIME_BELL: bool = 0

Ring the terminal bell if the previous command ran longer than LP_RUNTIME_BELL_THRESHOLD.

New in version 1.12.

LP_ENABLE_SCLS: bool = 1

Display the currently activated Red Hat Software Collection.

See also: LP_COLOR_VIRTUALENV.

LP_ENABLE_SCREEN_TITLE: bool = 0

Set the terminal title while in a terminal multiplexer.

LP_ENABLE_TITLE must be enabled to have any effect.

LP_ENABLE_SHORTEN_PATH: bool = 1

Use the shorten path feature if the path is too long to fit in the prompt line.

See also: LP_PATH_METHOD, LP_PATH_LENGTH, LP_PATH_KEEP, LP_PATH_CHARACTER_KEEP, and LP_MARK_SHORTEN_PATH.

LP_ENABLE_SSH_COLORS: bool = 0

Replace LP_COLOR_SSH with a color based on the hash of the hostname. This can give each host a “color feel” to help distinguish them.

See also: LP_HOSTNAME_ALWAYS.

LP_ENABLE_SUDO: bool = 0

Check if the user has valid sudo credentials, and display an indicating mark or color.

Will be disabled if sudo is not found.

Warning

Each evocation of sudo by default writes to the syslog, and this will run sudo once each prompt. This is likely to make your sysadmin hate you.

See also: LP_COLOR_MARK_SUDO.

LP_ENABLE_SVN: bool = 1

Display VCS information inside Subversion repositories.

Will be disabled if svn is not found.

See also: LP_MARK_SVN.

LP_ENABLE_TEMP: bool = 1

Display the highest system temperature if above the threshold.

Will be disabled if neither sensors nor acpi are found.

See also: LP_TEMP_THRESHOLD, LP_MARK_TEMP, and LP_COLORMAP.

LP_ENABLE_TIME: bool = 0

Displays the time at which the prompt was shown.

See also: LP_TIME_ANALOG and LP_COLOR_TIME.

LP_ENABLE_TITLE: bool = 0

Set the terminal title to part or all of the prompt string, depending on the theme.

Must be enabled to be able to set the manual title with lp_title().

Warning

This may not work properly on exotic terminals. Please report any issues.

LP_ENABLE_VCS_ROOT: bool = 0

Enable VCS features when running as root. This is disabled by default for security.

LP_ENABLE_VIRTUALENV: bool = 1

Display the currently activated Python or Conda virtual environment.

See also: LP_COLOR_VIRTUALENV.

LP_HOSTNAME_ALWAYS: int = 0

Determine when the hostname should be displayed. Valid values are:

• 0 - show the hostname, except when locally connected

• 1 - always show the hostname

• -1 - never show the hostname

See also: LP_COLOR_HOST and LP_ENABLE_SSH_COLORS.

LP_PERCENTS_ALWAYS: bool = 1

Display the actual values of load and batteries along with their corresponding marks. Disable to only print the colored marks.

LP_TIME_ANALOG: bool = 0

Shows the time using an analog clock instead of numeric values. The analog clock is “accurate” to the nearest half hour. You must have a unicode-capable terminal and a font with the “CLOCK” characters (U+1F550 - U+1F567).

Will only have an effect if LP_ENABLE_TIME is enabled.

LP_USER_ALWAYS: int = 1

Determine when the username should be displayed. Valid values are:

• 0 - show the username, except when the user is the login user

• 1 - always show the username

• -1 - never show the username

See also: LP_COLOR_USER_LOGGED, LP_COLOR_USER_ALT, and LP_COLOR_USER_ROOT.

Changed in version 2.0: The -1 option was added.

Thresholds

LP_BATTERY_THRESHOLD: int = 75

The percentage threshold that the battery level needs to fall below before it will be displayed in LP_COLOR_CHARGING_UNDER or LP_COLOR_DISCHARGING_UNDER color. Otherwise, it will be displayed in LP_COLOR_CHARGING_ABOVE or LP_COLOR_DISCHARGING_ABOVE color.

LP_ENABLE_BATT must be enabled to have any effect.

LP_LOAD_CAP: float = 2.0

The value for load average per CPU to display with the max color scaling. Values above this number will still be displayed, but the colors will not increase in intensity.

LP_ENABLE_LOAD must be enabled to have any effect.

See also: LP_COLORMAP.

New in version 2.0.

LP_LOAD_THRESHOLD: float = 0.60

Display the load average per CPU when above this threshold. For historical reasons, this number must have a decimal point (‘.’), or it will be treated as a percentage.

LP_ENABLE_LOAD must be enabled to have any effect.

Changed in version 2.0: Accepts float values of actual load averages. Integer values of centiload are still accepted, but deprecated.

LP_RUNTIME_THRESHOLD: int = 2

Time in seconds that a command must run longer than for its runtime to be displayed.

LP_ENABLE_RUNTIME must be enabled to have any effect.

LP_RUNTIME_BELL_THRESHOLD: int = 10

Time in seconds that a command must run longer than for the terminal bell to be rung.

LP_ENABLE_RUNTIME_BELL must be enabled to have any effect.

New in version 1.12.

LP_TEMP_THRESHOLD: int = 60

Display the highest system temperature when the temperature is above this threshold (in degrees Celsius).

LP_ENABLE_TEMP must be enabled to have any effect.

Marks

LP_MARK_ADAPTER: string = "⏚"

Mark used for battery display when charging.

See also: LP_ENABLE_BATT.

LP_MARK_BATTERY: string = "⌁"

Mark used for battery display when on battery power.

See also: LP_ENABLE_BATT.

LP_MARK_BRACKET_CLOSE: string = "]"

Mark used for closing core prompt brackets. Used by the default theme for enclosing user, host, and current working directory sections.

See also: LP_MARK_BRACKET_OPEN.

LP_MARK_BRACKET_OPEN: string = "["

Mark used for opening core prompt brackets. Used by the default theme for enclosing user, host, and current working directory sections.

See also: LP_MARK_BRACKET_CLOSE.

LP_MARK_BZR: string = "⚯"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a Bazaar repository.

See also: LP_ENABLE_BZR.

LP_MARK_DEFAULT: string = "$" (Bash) or "%" (Zsh)

Mark used to indicate that the prompt is ready for user input, unless some other context overrides it, like a VCS repository.

LP_MARK_DIRSTACK: string = "⚞"

Mark used to indicate the size of the directory stack. Here are some alternative marks you might like: ⚟ = ≡ ≣

See also: LP_ENABLE_DIRSTACK and LP_COLOR_DIRSTACK.

New in version 2.0.

LP_MARK_DISABLED: string = "⌀"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is disabled for VCS display through LP_DISABLED_VCS_PATHS.

LP_MARK_FOSSIL: string = "⌘"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a Fossil repository.

See also: LP_ENABLE_FOSSIL.

LP_MARK_GIT: string = "±"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a Git repository.

See also: LP_ENABLE_GIT.

LP_MARK_HG: string = "☿"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a Mercurial repository.

See also: LP_ENABLE_HG.

LP_MARK_LOAD: string = "⌂"

Mark used before displaying load average.

See also: LP_ENABLE_LOAD.

LP_MARK_PERM: string = ":"

Mark used by default separate hostname and current working directory, and is colored to indicate user permissions on the current directory.

Is still used (without colors) if LP_ENABLE_PERM is disabled.

New in version 1.12.

LP_MARK_PROXY: string = "↥"

Mark used to indicate a proxy is active.

See also: LP_ENABLE_PROXY.

LP_MARK_SHORTEN_PATH: string = " … "

Mark used to indicate a portion of the path was hidden to save space. Not all shortening methods use this mark, some only use LP_COLOR_PATH_SHORTENED.

See also: LP_ENABLE_SHORTEN_PATH, LP_PATH_METHOD.

LP_MARK_STASH: string = "+"

Mark used to indicate at least one stash or shelve exists in the current repository.

LP_MARK_SVN: string = "‡"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a Subversion repository.

See also: LP_ENABLE_SVN.

LP_MARK_TEMP: string = "θ"

Mark used before displaying temperature.

See also: LP_ENABLE_TEMP.

LP_MARK_UNTRACKED: string = "*"

Mark used to indicate untracked or extra files exist in the current repository.

LP_MARK_VCSH: string = "|"

Mark used instead of LP_MARK_DEFAULT to indicate that the current directory is inside of a VCSH repository.

Since VCSH repositories are Git repositories under the hood, LP_MARK_GIT is surrounded in this mark.

Colors

These color strings will be used without modification, so they need to be valid terminal escape sequences, either generated with lp_terminal_format() or using the $COLOR variables.

Valid preset color variables are:

• BOLD - bold formatting only.

• BLACK

• BOLD_GRAY - actually bold black

• RED

• BOLD_RED

• GREEN

• BOLD_GREEN

• YELLOW

• BOLD_YELLOW

• BLUE

• BOLD_BLUE

• PURPLE or MAGENTA

• BOLD_PURPLE, BOLD_MAGENTA or PINK

• CYAN

• BOLD_CYAN

• WHITE

• BOLD_WHITE

• WARN_RED - black foreground, red background

• CRIT_RED - white foreground, red background

• DANGER_RED - yellow foreground, red background

LP_COLORMAP: array<string>

An array of colors that is used by the battery, load, and temperature features to indicate the severity level of their status. A normal or low status will use the first index, while the last index is the most severe.

The default array is:

(
    ""
    $GREEN
    $BOLD_GREEN
    $YELLOW
    $BOLD_YELLOW
    $RED
    $BOLD_RED
    $WARN_RED
    $CRIT_RED
    $DANGER_RED
)

See also: LP_ENABLE_BATT, LP_ENABLE_LOAD, and LP_ENABLE_TEMP.

LP_COLOR_CHANGES: string = $RED

Color used to indicate that the current repository is not clean, or in other words, has changes that have not been committed.

LP_COLOR_CHARGING_ABOVE: string = $GREEN

Color used to indicate that the battery is charging and above the LP_BATTERY_THRESHOLD.

See also: LP_ENABLE_BATT.

LP_COLOR_CHARGING_UNDER: string = $YELLOW

Color used to indicate that the battery is charging and under the LP_BATTERY_THRESHOLD.

See also: LP_ENABLE_BATT.

LP_COLOR_COMMITS_BEHIND: string = $BOLD_RED

Color used to indicate that the current repository has a remote tracking branch that has commits that the local branch does not.

LP_COLOR_COMMITS: string = $YELLOW

Color used to indicate that the current repository has commits on the local branch that the remote tracking branch does not.

Also used to color LP_MARK_STASH.

LP_COLOR_DIFF: string = $PURPLE

Color used to indicate that the current repository has lines that have been changed since the last commit.

LP_COLOR_DIRSTACK: string = $BOLD_YELLOW

Color used to indicate the size of the directory stack.

See also: LP_ENABLE_DIRSTACK and LP_MARK_DIRSTACK.

New in version 2.0.

LP_COLOR_DISCHARGING_ABOVE: string = $YELLOW

Color used to indicate that the battery is discharging and above the LP_BATTERY_THRESHOLD.

See also: LP_ENABLE_BATT.

LP_COLOR_DISCHARGING_UNDER: string = $RED

Color used to indicate that the battery is discharging and above the LP_BATTERY_THRESHOLD.

See also: LP_ENABLE_BATT.

LP_COLOR_ERR: string = $PURPLE

Color used to indicate the last command exited with a non-zero return code.

See also: LP_ENABLE_ERROR.

LP_COLOR_HOST: string = ""

Color used for the hostname when connected locally.

See also: LP_HOSTNAME_ALWAYS.

LP_COLOR_IN_MULTIPLEXER: string = $BOLD_BLUE

Color used for LP_MARK_BRACKET_OPEN and LP_MARK_BRACKET_CLOSE if the terminal is in a multiplexer.

LP_COLOR_JOB_D: string = $YELLOW

Color used for detached multiplexer sessions.

See also: LP_ENABLE_DETACHED_SESSIONS.

LP_COLOR_JOB_R: string = $BOLD_YELLOW

Color used for running shell jobs.

See also: LP_ENABLE_JOBS.

LP_COLOR_JOB_Z: string = $BOLD_YELLOW

Color used for sleeping shell jobs.

See also: LP_ENABLE_JOBS.

LP_COLOR_MARK: string = $BOLD

Color used for LP_MARK_DEFAULT.

LP_COLOR_MARK_ROOT: string = $BOLD_RED

Color used for LP_MARK_DEFAULT when the current user is root, shown instead of LP_COLOR_MARK.

LP_COLOR_MARK_SUDO: string = $LP_COLOR_MARK_ROOT

Color used for LP_MARK_DEFAULT when sudo is active, shown instead of LP_COLOR_MARK.

See also: LP_ENABLE_SUDO.

LP_COLOR_NOWRITE: string = $RED

Color used for LP_MARK_PERM when the user does not have write permissions to the current working directory.

See also: LP_ENABLE_PERM and LP_COLOR_WRITE.

LP_COLOR_PATH: string = lp_terminal_format 255 0 0 0 7 # Bright white

Color used for the current working directory.

If LP_COLOR_PATH_LAST_DIR, LP_COLOR_PATH_VCS_ROOT, LP_COLOR_PATH_SEPARATOR, or LP_COLOR_PATH_SHORTENED are set, their respective sections will be colored with them instead.

Changed in version 2.0: Default value changed from $BOLD.

LP_COLOR_PATH_LAST_DIR: string = lp_terminal_format 255 0 1 0 7 # Bright bold white

Color used for the last path segment, which corresponds to the current directory basename.

LP_COLOR_PATH_ROOT: string = $BOLD_YELLOW

Color used in place of LP_COLOR_PATH when the current user is root.

LP_COLOR_PATH_SEPARATOR: string = lp_terminal_format 245 0 0 0 7 # Light grey

Color used for the separator (‘/’) between path segments. If set to the empty string, the separator will take the format of the path segment before it.

LP_COLOR_PATH_SHORTENED: string = lp_terminal_format 245 0 0 0 7 # Light grey

Color used for path segments that have been shortened.

LP_ENABLE_SHORTEN_PATH must be enabled to have any effect.

LP_COLOR_PATH_VCS_ROOT: string = lp_terminal_format 255 0 1 0 7 # Bright bold white

Color used for the path segment corresponding to the current VCS repository root directory.

LP_PATH_VCS_ROOT must be enabled to have any effect.

LP_COLOR_PROXY: string = $BOLD_BLUE

Color used for LP_MARK_PROXY.

See also: LP_ENABLE_PROXY.

LP_COLOR_RUNTIME: string = $YELLOW

Color used for displaying the last command runtime.

See also: LP_ENABLE_RUNTIME.

LP_COLOR_SSH: string = $BLUE

Color used for displaying the hostname when connected with SSH.

Has no effect if LP_ENABLE_SSH_COLORS is enabled.

See also: LP_HOSTNAME_ALWAYS.

LP_COLOR_SU: string = $BOLD_YELLOW

Color used for displaying the hostname when running under su or sudo.

See also: LP_HOSTNAME_ALWAYS.

LP_COLOR_TELNET: string = $WARN_RED

Color used for displaying the hostname when connected with Telnet.

See also: LP_HOSTNAME_ALWAYS.

LP_COLOR_TIME: string = $BLUE

Color used for displaying the current time.

See also: LP_ENABLE_TIME.

LP_COLOR_UP: string = $GREEN

Color used to indicate that the current repository is up-to-date and no commits differ from the remote tracking branch.

LP_COLOR_USER_ALT: string = $BOLD

Color used for displaying the username when running as a different user than the login user.

LP_COLOR_USER_LOGGED: string = ""

Color used for displaying the username when running as the login user.

See also: LP_USER_ALWAYS.

LP_COLOR_USER_ROOT: string = $BOLD_YELLOW

Color used for displaying the username when running as root.

LP_COLOR_VIRTUALENV: string = $CYAN

Color used for displaying a Python virtual env or Red Hat Software Collection.

See also: LP_ENABLE_VIRTUALENV and LP_ENABLE_SCLS.

LP_COLOR_WRITE: string = $GREEN

Color used for LP_MARK_PERM when the user has write permissions to the current working directory.

See also: LP_ENABLE_PERM and LP_COLOR_NOWRITE.

LP_COLOR_X11_OFF: string = $YELLOW

Color used for indicating that a display is not connected.

LP_COLOR_X11_ON: string = $GREEN

Color used for indicating that a display is connected.

Theming

Liquidprompt 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 Liquidprompt version 1), that allows for custom prompt ordering in the default theme.

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

See the Liquidprompt Theme List on the wiki for user created themes.

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

Default Theme

Preview

If there is nothing special about the current context, the appearance of Liquidprompt is similar to that of a default prompt:

If you are running a background command and are also in the “main” branch of a Git repository on a server:

When Liquidprompt is displaying nearly everything (a rare event!), it may look like this:

See Templates for what each section will look like.

Configuation

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 Liquidprompt 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: liquid.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.

Note

Omitting a template section from your template will not disable that feature. While it will not be displayed in the prompt, Liquidprompt 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_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.

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_SCLS

The current Red Hat Software Collections environment. See LP_ENABLE_SCLS.

LP_VENV

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

LP_PROXY

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

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

Included Themes

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

Alternate VCS Details Theme

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

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:

If you are running a background command and are also in the “main” branch of a Git repository on a server:

When Liquidprompt is displaying nearly everything, it may look like this:

A demo of what disabling the configuration options might look like:

Configuration

Liquidprompt Configuration

All Liquidprompt 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

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

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 Liquidprompt can do what Powerline does, but faster. That said, this is a fully usable theme.

New in version 2.0.

Preview

If there is nothing special about the current context, the appearance of Powerline might be as simple as this:

If you are running a background command and are also in the “main” branch of a Git repository on a server:

When Liquidprompt is displaying nearly everything, it may look like this:

Note

The above “everything” image looks like it is missing some parts because this theme does not implement all data sources of Liquidprompt. 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.

Configuation

Liquidprompt Configuration

The following Liquidprompt 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_DEFAULT

• LP_PATH_KEEP

• LP_PATH_LENGTH

• 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 Liquidprompt provides. The ordering is the same as the default theme.

New in version 2.0.

Preview

If there is nothing special about the current context, the appearance of Powerline might be as simple as this:

If you are running a background command and are also in the “main” branch of a Git repository on a server:

When Liquidprompt is displaying nearly everything, it may look like this:

Setup

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

Configuation

Liquidprompt Configuration

All Liquidprompt config options are respected, except for:

• 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_MARK

• LP_COLOR_MARK_ROOT

• LP_COLOR_MARK_SUDO

• LP_COLOR_NOWRITE

• LP_COLOR_PATH

• LP_COLOR_PATH_ROOT

• LP_COLOR_PROXY

• LP_COLOR_RUNTIME

• LP_COLOR_SSH

• LP_COLOR_SU

• LP_COLOR_TELNET

• 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_OPEN

• LP_MARK_BRACKET_CLOSE

• 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_CHROOT_MARKER: string = "chroot: "

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

POWERLINE_PROXY_MARKER: string = "proxy: "

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

POWERLINE_SOFTWARE_COLLECTION_MARKER: string = "(sc) "

The marker string used to indicate the following string is a Red Hat Software Collection.

Colors

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_DIRSTACK_COLOR: array<int> = $POWERLINE_NEUTRAL_COLOR

Color for the directory stack section.

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_PROXY_COLOR: array<int> = (21, 219, 1, 0, 4, 7)

Color for the HTTP proxy section.

POWERLINE_RUNTIME_COLOR: array<int> = (226, 17, 0, 0, 3, 4)

Color for the command runtime section.

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_TIME_COLOR: array<int> = (33, 17, 0, 0, 5, 4)

Color for the current time section.

Custom Themes

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.

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

Liquidprompt 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 Powerline theme, source the theme file:

$ source themes/powerline/powerline.theme

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

$ lp_theme --list
default
powerline_full
powerline

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

$ lp_theme powerline

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.

Functions

Functions starting with lp or any other alphanumeric character are public functions designed to be used by users on the command line or in their config.

Functions starting with _lp are theme level functions, designed to be used by themes. These include data, theme, and utility functions.

Functions starting with __lp are internal functions, designed to be used only by Liquidprompt internals. These functions should not be used by users or themes, as they are not guaranteed to not change between versions.

Public Functions

These functions are designed to be used by users on the command line or in their config.

lp_activate()

Reload the user config.

This function is called when sourcing liquidprompt, unless the flag --no-activate is passed.

The config is sourced, and the environment scanned again for programs needed for specific features.

Lastly, prompt_on() is called to enabled the prompt.

New in version 2.0.

lp_title([title_string])

Set title_string as the terminal title. This overrides any title set by the current theme.

Note

The input string is not escaped in any way; if it contains characters that the shell will interpret, the user must escape them if that behavior is not desired.

To unset the manual title, call lp_title() with no arguments.

To set a blank title, call lp_title() with an empty string argument ('').

This function will do nothing and return 2 if LP_ENABLE_TITLE is 0.

New in version 2.0.

lp_theme(theme_id | --list)

Load and activate the theme named theme_id. The theme functions must be loaded into memory before lp_theme() can be called, normally by sourcing the theme file.

The optional flag --list will instead list all currently loaded themes.

This function supports shell autocompletion.

New in version 2.0.

lp_terminal_format(foreground_color[, background_color][, bold][, underline][, fallback_foreground_color][, fallback_background_color]) → var:lp_terminal_format

Generate a shell escaped terminal formatting string for use in PS1.

The start of the formatting string always resets back to terminal defaults.

foreground_color and background_color accept an ANSI escape color code integer to set the color of the foreground and background, respectively. The behavior depends on the integer:

• >= 0 && < max_color - The color is used directly.

• >= max_color - If the terminal reports that the number of colors it supports is less than the input color code, the fallback_foreground_color or fallback_background_color is used instead.

• -1 - No color is set. This does not mean that the previous color will continue over, as all formatting is reset to default at the start of the sequence. This means the default coloring is effectively set.

• -2 - The previous color of the field is set. If no color was previously set, no color will be set. Note that the output is a static formatting string; the string will not keep the same color as the terminal previously had, but the color that was last selected when lp_terminal_format() was last run.

• -3 - Same as -2, except the opposite field color is copied. In other words, if foreground_color is set to -3, it will copy the color of background_color the last time lp_terminal_format() was run.

bold and underline enable their respective formats when set to 1. If omitted or set to 0, they are not enabled. To use fallback colors, they will need to be set to be able to set the other options.

fallback_foreground_color and fallback_background_color are used when the normal colors are higher than the terminal supported colors. The special negative inputs do not work for these options, and they are not checked for compatibility before being used, so it is recommended that they are in the range 0-7. When setting foreground_color or background_color to negative inputs, these options are never checked.

New in version 2.0:

prompt_on()

Enable the prompt generation and setting.

This function is called when sourcing liquidprompt, unless the flag --no-activate is passed.

prompt_off()

Disable the prompt generation and setting, and restore the old PS1.

If the shell is Bash, also restore the old PROMPT_COMMAND.

If the shell is Zsh, also restore the old prompt theme.

prompt_OFF()

Same as prompt_off(), except instead of restoring the previous PS1, it is set to “$ ” on Bash, “% ” on Zsh.

prompt_tag([prefix_string])

Sets a prefix that will be displayed before every prompt. Postpends a space to the input string.

Internally, this function sets LP_PS1_PREFIX to prefix_string. If a trailing space is not wanted, set LP_PS1_PREFIX manually.

To unset the prefix, call prompt_tag() with no arguments.

Data Functions

Version Control Data Functions

These functions are designed to be used by themes.

Generic

The generic interface functions are designed to provide a level of abstraction over the type of VCS that a user might be using. By using the generic interface, a theme can provide a common look for all VCS types. See the default theme function _lp_vcs_details_color() for an example of this.

_lp_find_vcs() → var:lp_vcs_type, var:lp_vcs_root

Returns true if the current directory is part of a version control repository. If not, returns 1. Returns the VCS type ID and the repository root directory.

If the current directory is disabled for version control using LP_DISABLED_VCS_PATHS (checked using _lp_are_vcs_enabled()), returns 2, and the returned type is set to “disabled”.

_lp_find_vcs() will only search for VCS types that are not disabled. If all VCS types are disabled in the config, _lp_find_vcs() will return 1, as no repository will be found.

This function does a lightweight check for the existence of a version control repository, only looking for the existence of a database. It does not check if the database is valid or healthy. Use _lp_vcs_active() to test for that.

New in version 2.0.

_lp_are_vcs_enabled()

Returns true if the current directory is not excluded by the config option LP_DISABLED_VCS_PATHS.

Note

All following generic functions need _lp_find_vcs() to be run first, as they need lp_vcs_type to be set.

_lp_vcs_active()

Returns true if the detected VCS is enabled in Liquidprompt and the current directory is a valid repository of that type. This check should be done before running any other _lp_vcs_* data functions, but can be omitted for speed reasons if the checks done by _lp_find_vcs() are good enough.

New in version 2.0.

Note

All following generic functions can exit with return codes higher than their normal disabled exit code. If the active VCS does not support a feature, the data function will not be defined, and therefore the shell will return an error code much higher than 2. Compare using greater-or-equal if checking for not supported error codes.

Unless otherwise documented, the following functions return 0 for good data, 1 for no data, and 2 or higher for unsupported function.

_lp_vcs_bookmark() → var:lp_vcs_bookmark

Returns true if a bookmark is active in the repository. Returns the bookmark name.

Most VCS providers do not support bookmarks.

New in version 2.0.

_lp_vcs_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

For some VCS providers, a branch is always active.

New in version 2.0.

_lp_vcs_commit_id() → var:lp_vcs_commit_id

Returns the full commit ID of the current commit. The return code is not defined.

Some VCS providers use hashes, while others use incrementing revision numbers. All VCS providers support some form of ID. The returned string should be unique enough that a user can identify the commit.

New in version 2.0.

_lp_vcs_commits_off_remote() → var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind

Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch. Returns 3 or higher if the VCS provider does not support remote tracking branches.

Returns the number of commits behind and ahead.

Most VCS providers do not support remote tracking branches.

New in version 2.0.

_lp_vcs_head_status() → var:lp_vcs_head_status, var:lp_vcs_head_details

Return true if the repo is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

Many VCS providers do not have such information. This info is unlikely to be similar across VCSs, and should probably be displayed to a user without manipulation.

Note

The details are optional, and might not be set. Protect it with "${lp_vcs_head_details-}".

New in version 2.0.

_lp_vcs_staged_files() → var:lp_vcs_staged_files

Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_staged_lines() → var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines

Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

Some VCS providers refer to stashes as “shelves”.

Some VCS providers do not support stashes.

New in version 2.0.

_lp_vcs_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

A tag will only be returned if it is a unique ID that points only to the current commit.

If multiple tags match, only one is returned. Which tag is selected is not defined.

Some VCS providers do not support unique tags.

New in version 2.0.

_lp_vcs_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

Some VCS providers refer to uncommitted files as “modified” files.

New in version 2.0.

_lp_vcs_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

Some VCS providers refer to uncommitted lines as “modified” or “changed” lines.

New in version 2.0.

_lp_vcs_unstaged_files() → var:lp_vcs_unstaged_files

Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_unstaged_lines() → var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines

Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

Some VCS providers refer to untracked files as “extra” files.

New in version 2.0.

Bazaar

Warning

Bazaar is no longer being actively developed, and depends on Python 2, which is no longer supported. Breezy is a fork that can work with Bazaar repositories. To use Breezy in place of Bazaar, set a wrapper function:

bzr() { brz "$@"; }

Note

Bazaar does not support bookmarks. A nick is somewhat like a bookmark, but there is no command to view a naked branch name, so the nick command is used for branches.

Note

Bazaar does not support a staging area.

Note

Bazaar does not support getting details of remote tracking branches. Bazaar does not keep a local copy of the remote state, so checking this would be impossible anyway.

Note

Bazaar does not have extra head statuses. A Bazaar merge can be partially complete, but there is no command to test for it.

_lp_bzr_active()

Returns true if Bazaar is enabled in Liquidprompt and the current directory is a valid Bazaar repository. This check should be done before running any other _lp_bzr_* data functions if accessing the Bazaar data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_BZR.

New in version 2.0.

_lp_bzr_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_bzr_commit_id() → var:lp_vcs_commit_id

Returns the revision number of the current commit. The return code is not defined.

New in version 2.0.

_lp_bzr_stash_count() → var:lp_vcs_stash_count

Returns true if there are shelves the repository. Returns the number of shelves.

New in version 2.0.

_lp_bzr_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_bzr_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_bzr_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_bzr_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Fossil

Note

Fossil does not support bookmarks.

Note

Fossil does not support a staging area.

Note

Fossil does not support unique tags. Fossil tags can refer to multiple checkin IDs, so a matching tag is not a useful unique ID.

Note

Fossil does not support remote tracking branches. Fossil by default keeps the local repository in sync with the remote. Even if a user disables that, it is not possible to have a local and remote branch named the same not in sync.

_lp_fossil_active()

Returns true if Fossil is enabled in Liquidprompt and the current directory is a valid Fossil repository. This check should be done before running any other _lp_fossil_* data functions if accessing the Fossil data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_FOSSIL.

New in version 2.0.

_lp_fossil_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of “no-branch”.

_lp_fossil_commit_id() → var:lp_vcs_commit_id

Returns the full commit hash of the current commit. The return code is not defined.

New in version 2.0.

_lp_fossil_head_status() → var:lp_vcs_head_status

Return true if the repository is in a special or unusual state. Return the special status.

Does not return any extra details.

New in version 2.0.

_lp_fossil_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

New in version 2.0.

_lp_fossil_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_fossil_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_fossil_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Git

Note

Git does not support bookmarks.

_lp_git_active()

Returns true if Git is enabled in Liquidprompt and the current directory is a valid Git repository. This check should be done before running any other _lp_git_* data functions if accessing the Git data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_GIT.

New in version 2.0.

_lp_git_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of commit ID.

_lp_git_commit_id() → var:lp_vcs_commit_id

Returns the full commit hash of the current commit. The return code is not defined.

New in version 2.0.

_lp_git_commits_off_remote() → var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind

Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch.

Returns the number of commits behind and ahead.

New in version 2.0.

_lp_git_head_status() → var:lp_vcs_head_status, var:lp_vcs_head_details

Return true if the repository is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

New in version 2.0.

_lp_git_staged_files() → var:lp_vcs_staged_files

Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

New in version 2.0.

_lp_git_staged_lines() → var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines

Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

New in version 2.0.

_lp_git_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

New in version 2.0.

_lp_git_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_git_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_git_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_git_unstaged_files() → var:lp_vcs_unstaged_files

Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

New in version 2.0.

_lp_git_unstaged_lines() → var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines

Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

New in version 2.0.

_lp_git_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Mercurial

Note

Mercurial does not support a staging area.

Note

Mercurial remote tracking branches are disabled (see _lp_hg_commits_off_remote()).

_lp_hg_active()

Returns true if Mercurial is enabled in Liquidprompt and the current directory is a valid Mercurial repository. This check should be done before running any other _lp_hg_* data functions if accessing the Mercurial data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_HG.

New in version 2.0.

_lp_hg_bookmark() → var:lp_vcs_bookmark

Returns true if a bookmark is active in the repository. Returns the bookmark name.

Mercurial bookmarks work more like Git branches.

New in version 2.0.

_lp_hg_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

All Mercurial commits have a branch, so this function should always return true. A closer analog to Git branches are Mercurial bookmarks (see _lp_hg_bookmark()).

Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_hg_commit_id() → var:lp_vcs_commit_id

Returns the full global revision ID of the current commit. The return code is not defined.

New in version 2.0.

_lp_hg_commits_off_remote()

Returns 3 (disabled).

Mercurial does not keep a local copy of the remote state, so checking this will require a connection to the remote server. This means it is often prohibitively time expensive, and therefore should not be used in a prompt. See issue #217.

New in version 2.0.

_lp_hg_head_status() → var:lp_vcs_head_status

Return true if the repository is in a special or unusual state. Return the special status.

Does not return any extra details.

This function depends on _lp_find_vcs() being run first to set lp_vcs_root.

New in version 2.0.

_lp_hg_stash_count() → var:lp_vcs_stash_count

Returns true if there are shelves the repository. Returns the number of shelves.

New in version 2.0.

_lp_hg_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_hg_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_hg_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_hg_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Subversion

Note

Subversion does not support bookmarks.

Note

Subversion does not support a staging area.

Note

Subversion does not support stashes.

Note

Subversion does not have extra head statuses. A Subversion merge is no different than a manual file change, so the repository has no extra state to track.

Note

Subversion does not support remote tracking branches (as it is not a distributed version control system).

Note

Subversion does not support tags. What are generally agreed upon as being tags are internally branches. These are returned by _lp_svn_branch().

_lp_svn_active()

Returns true if Subversion is enabled in Liquidprompt and the current directory is a valid Subversion repository. This check should be done before running any other _lp_svn_* data functions if accessing the Subversion data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_SVN.

New in version 2.0.

_lp_svn_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Subversion “tags” are really branches under a “tag” directory. Tags are returned as their directory name, prefixed with “tag/”.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of the current directory.

_lp_svn_commit_id() → var:lp_vcs_commit_id

Returns the revision number of the current commit. The return code is not defined.

New in version 2.0.

_lp_svn_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_svn_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_svn_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

These functions are designed to be used by themes.

All data functions will return true (meaning return code 0) when they are both enabled and have data. They will return false (meaning return code 1) when they do not have data. Most will return 2 when they are disabled, either through the config or because the tool they depend on is not installed. Such disable config options will be documented. Exceptions to this rule are explicitly documented.

When a function returns false, any return variables are not guaranteed to be set. If running with set -u (or when building a theme to be distributed), guard any return variable accesses with a check of the return code, or use ${var-} syntax.

Battery

_lp_battery() → var:lp_battery

Returns a return code depending on the status of the battery:

• 5 if the battery feature is disabled or not available

• 4 if no battery level is found

• 3 if charging and the level is above the threshold

• 2 if charging and the level is under the threshold

• 1 if discharging and the level is above the threshold

• 0 if discharging and the level is under the threshold

Returns an integer percentage of the current battery level.

If the threshold is not surpassed, the battery level is still returned.

The threshold is configured with LP_BATTERY_THRESHOLD.

Can be disabled by LP_ENABLE_BATT.

Development Environment

_lp_python_env() → var:lp_python_env

Retuns true if a Python or Conda environment is detected. Returns the virtual environment name.

If the environment name contains a forward slash (/), only the substring after the last forward slash is returned.

Can be disabled by LP_ENABLE_VIRTUALENV.

New in version 2.0.

_lp_software_collections() → var:lp_software_collections

Returns true if a Red Hat Software Collection is enabled. Returns the software collection name.

If the software collection name has trailing whitespace, it is removed.

Can be disabled by LP_ENABLE_SCLS.

New in version 2.0.

Environment

_lp_connected_display()

Returns true if there is a connected X11 display.

New in version 2.0.

_lp_connection() → var:lp_connection

Returns a string matching the connection context of the shell. Valid values:

• ssh - connected over OpenSSH

• lcl - running in a local terminal

• su - running in a su or sudo shell

• tel - connected over Telnet

It is not possible for more than one context to be returned. The contexts are checked in the order listed above, and the first one found will be returned.

It is not possible for no context to be returned.

Changed in version 2.0: Return method changed from stdout.

_lp_dirstack() → var:lp_dirstack

Returns true if directory stack support is enabled and the directory stack contains more than one directory. In that case, the return variable is set to the number of directories on the stack.

Can be enabled by LP_ENABLE_DIRSTACK.

New in version 2.0.

_lp_error() → var:lp_error

Returns true if the last user shell command returned a non-zero exit code. Returns (in the return variable) the exit code of that command.

Can be disabled by LP_ENABLE_ERROR.

Note

The return variable lp_error will always be set with the last command return code, as it must be the first thing done by the prompt. This function should still be used, as it checks for the feature being disabled by the user.

New in version 2.0.

_lp_http_proxy() → var:lp_http_proxy

Returns true if an HTTP or HTTPS proxy is enabled through environment variables in the shell. Returns the first found proxy string.

Can be disabled by LP_ENABLE_PROXY.

New in version 2.0.

_lp_multiplexer() → var:lp_mulitplexer

Returns true if the current shell context is inside a terminal multiplexer. Returns a string matching the multiplexer:

• tmux

• screen

New in version 2.0.

_lp_terminal_device() → var:lp_terminal_device

Returns the basename of the terminal device connected to the shell’s standard input.

Note

This value should never change during the life of the shell.

Note

This data source is unlikely to be wanted by the user, and should not be included in themes by default.

New in version 2.0.

Jobs

_lp_detached_sessions() → var:lp_detached_sessions

Returns true if any detached multiplexer sessions are found. Returns an integer count of how many sessions were found.

Can be disabled by LP_ENABLE_DETACHED_SESSIONS.

New in version 2.0.

_lp_jobcount() → var:lp_running_jobs, var:lp_stopped_jobs

Returns true if any shell background jobs are found. Returns an integer count of how many jobs are running and how many are stopped.

Stopped jobs are jobs suspended with Ctrl-Z.

Running jobs are jobs started with the command & syntax, or stopped jobs started again with the bg command.

Can be disabled by LP_ENABLE_JOBS.

New in version 2.0.

Load

_lp_cpu_load() → var:lp_cpu_load

Returns a string of the system load average smallest increment, usually 1 minute. The return code is not defined.

_lp_load() → var:lp_load, var:lp_load_adjusted

Returns true if the system load average scaled by CPU count is greater than the threshold. Returns the system load average in lp_load, and the average scaled by CPU count, multiplied by 100 in lp_load_adjusted. In other words, the load average is multiplied by 100, then divided by the number of CPU cores.

lp_load should be displayed to the user, while lp_load_adjusted should be used to compare values between machines using LP_LOAD_CAP. The default theme uses this to generate a color scale.

Note

LP_LOAD_CAP is a raw floating point configuration value that is difficult to do math on. _LP_LOAD_CAP contains the same value, but multiplied by 100 to make comparisons to lp_load_adjusted simple. Use it along with lp_load_adjusted as arguments to _lp_color_map().

If the threshold is not surpassed, the load average is still returned.

The threshold is configured with LP_LOAD_THRESHOLD.

Can be disabled by LP_ENABLE_LOAD.

New in version 2.0.

OS

_lp_chroot() → var:lp_chroot

Returns true if a chroot environment is detected. Returns a string matching the chroot string if one is found.

New in version 2.0.

_lp_hostname() → var:lp_hostname

Returns true if a hostname should be displayed. Returns 1 if the connection type is local and LP_HOSTNAME_ALWAYS is not 1.

Returns the hostname string.

Note

The returned string is not the real hostname, instead it is the shell escape code for hostname, so the shell will substitute the real user ID when it evaluates PS1.

Deprecated since version 2.0: Also sets LP_HOST_SYMBOL to the same return string.

Can be disabled by LP_HOSTNAME_ALWAYS set to -1.

New in version 2.0.

_lp_sudo_active()

Returns true if sudo is currently activated with valid credentials. If sudo is configured to always allow a user to run commands with no password, this will always return true.

Can be disabled by LP_ENABLE_SUDO.

New in version 2.0.

_lp_user()

Returns a return code depending on the logged in user:

• 2 - the user is root

• 1 - the user is a user other than the original login user

• 0 - the user is the login user

New in version 2.0.

_lp_username() → var:lp_username

Returns true if a username should be displayed. Returns 1 if the user is the login user and LP_USER_ALWAYS is not 1.

Returns the current user ID.

Note

The returned string is not a real user ID, instead it is the shell escape code for user, so the shell will substitute the real user ID when it evaluates PS1.

Can be disabled by LP_USER_ALWAYS set to -1.

New in version 2.0.

Path

_lp_path_format(path_format=$LP_COLOR_PATH, last_directory_format=$path_format, vcs_root_format=$last_directory_format, shortened_directory_format=$path_format, separator="/"[, separator_format]) → var:lp_path, var:lp_path_format

Returns a shortened and formatted string indicating the current working directory path. lp_path contains the path without any formatting or custom separators, intended for use in the terminal title. lp_path_format contains the complete formatted path, to be inserted into the prompt.

The behavior of the shortening is controlled by LP_ENABLE_SHORTEN_PATH, LP_PATH_METHOD, LP_PATH_LENGTH, LP_PATH_KEEP, LP_PATH_CHARACTER_KEEP, and LP_PATH_VCS_ROOT. See their descriptions for details on how they change the output of this function.

The last directory in the displayed path will be shown with the last_directory_format.

If a VCS repository is detected with _lp_find_vcs(), the root of the VCS repository is formatted with vcs_root_format. The detection method is the same as for all other VCS display, so if a VCS type or directory is disabled, it will not be detected.

If the path shortening shortens a directory (or multiple consecutive directories), they will be formatted with shortened_directory_format.

A custom separator will only be substituted in the lp_path_format output. Note that this will cut into maximum path length if the separator is longer than one character.

With no specified separator_format, each separator will take the format of the directory section preceding it. Otherwise every separator will be formatted with separator_format. Note that the root directory is treated as a directory, and is formatted as such.

New in version 2.0.

Runtime

_lp_runtime_format() → var:lp_runtime_format

Returns true if the last command runtime was greater than the threshold. Returns a formatted string of the total runtime, split into days, hours, minutes, and seconds. Ex: 3h27m6s.

The threshold is configured with LP_RUNTIME_THRESHOLD.

Can be disabled by LP_ENABLE_RUNTIME.

New in version 2.0.

Temperature

_lp_temperature() → var:lp_temperature

Returns true if the highest system temperature is greater than the threshold. Returns the highest temperature integer.

If the threshold is not surpassed, the highest temperature is still returned.

The threshold is configured with LP_TEMP_THRESHOLD.

Can be disabled by LP_ENABLE_TEMP.

New in version 2.0: Note that a function by this name was renamed to _lp_temperature_color.

Time

_lp_time() → var:lp_time

Returns true if digital time is enabled. Returns the current digital time string.

Note

The returned string is not the real time, instead it is the shell escape code for time, so the shell will substitute the real current time when it evaluates PS1.

Can be disabled by LP_ENABLE_TIME or LP_TIME_ANALOG set to 1.

New in version 2.0.

_lp_analog_time() → var:lp_analog_time

Returns true if analog time is enabled. Returns the current analog time as a single Unicode character, accurate to the closest 30 minutes.

Can be disabled by LP_ENABLE_TIME or LP_TIME_ANALOG set to 0.

New in version 2.0.

Default Theme Functions

These functions are designed to be used by the default theme, but are documented here so that other themes can use these functions to reduce duplication if sections from the default theme are wanted.

Theme Functions

_lp_default_theme_activate()

Setup the defaults and static pieces of the default theme.

Uses colors:

• LP_COLOR_IN_MULTIPLEXER

• LP_COLOR_MARK

• LP_COLOR_MARK_ROOT

• LP_COLOR_PATH_ROOT

• LP_COLOR_USER_ALT

• LP_COLOR_USER_LOGGED

• LP_COLOR_USER_ROOT

And marks:

• LP_MARK_BRACKET_OPEN

• LP_MARK_BRACKET_CLOSE

• LP_MARK_DEFAULT

New in version 2.0.

_lp_default_theme_directory()

Setup the colors for the directory when the current working directory changes.

Uses colors:

• LP_COLOR_NOWRITE

• LP_COLOR_PATH

• LP_COLOR_WRITE

And mark LP_MARK_PERM.

New in version 2.0.

_lp_default_theme_prompt()

Runs _lp_default_theme_prompt_data() then _lp_default_theme_prompt_template().

New in version 2.0.

_lp_default_theme_prompt_data()

Runs all of the below theme data functions, and writes values to the Default Theme variables. Can be used to generate all the default theme sections, then modify them before running a user template.

New in version 2.0.

_lp_default_theme_prompt_template()

If LP_PS1_FILE is set, sources it.

Then, if LP_PS1 is set, uses it as PS1. Otherwise, uses the default theme layout to construct PS1. Can be used to set different template sections than the default theme, but still use the same template engine.

New in version 2.0.

Theme Data Functions

These functions wrap Data Functions with color and/or other formatting. Their return codes are the same as the data functions they wrap unless otherwise documented.

The interface of the functions will not change between minor versions, but the specific text and formatting may change.

_lp_analog_time_color() → var:lp_analog_time_color

Returns _lp_analog_time() with color from LP_COLOR_TIME.

New in version 2.0.

_lp_battery_color() → var:lp_battery_color

Returns data from _lp_battery(), colored with:

• LP_COLOR_CHARGING_ABOVE

• LP_COLOR_CHARGING_UNDER

• LP_COLOR_DISCHARGING_ABOVE

• LP_COLOR_DISCHARGING_UNDER

• LP_COLORMAP

And using marks:

• LP_MARK_ADAPTER

• LP_MARK_BATTERY

Adds battery value if LP_PERCENTS_ALWAYS is 1.

Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_dirstack_color() → var:lp_dirstack_color

Returns _lp_dirstack(), prefixed with LP_MARK_DIRSTACK, all colored with LP_COLOR_DIRSTACK.

New in version 2.0.

_lp_error_color() → var:lp_error_color

Returns _lp_error() with color from LP_COLOR_ERR.

New in version 2.0.

_lp_hostname_color() → var:lp_hostname_color

Returns _lp_hostname(), with added data from _lp_chroot(). Color from LP_COLOR_HOST, LP_COLOR_SSH, LP_COLOR_HOST_HASH, and LP_COLOR_TELNET, depending on the output of _lp_connection().

Added color from _lp_connected_display(): either LP_COLOR_X11_ON or LP_COLOR_X11_OFF.

Return code is _lp_hostname() ORed with _lp_chroot(): both must return no data for _lp_hostname_color() to return no data.

New in version 2.0.

_lp_http_proxy_color() → var:lp_http_proxy_color

Returns _lp_http_proxy() with color from LP_COLOR_PROXY.

New in version 2.0.

_lp_jobcount_color() → var:lp_jobcount_color

Returns _lp_detached_sessions() with color from LP_COLOR_JOB_D and _lp_jobcount() with colors from LP_COLOR_JOB_R and LP_COLOR_JOB_Z.

Return code is _lp_detached_sessions() ORed with _lp_jobcount(): both must return no data for _lp_jobcount_color() to return no data.

Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_load_color() → var:lp_load_color

Returns _lp_load() with color from LP_COLORMAP and mark from LP_MARK_LOAD.

Adds load value if LP_PERCENTS_ALWAYS is 1.

Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_python_env_color() → var:lp_python_env_color

Returns _lp_python_env() with color from LP_COLOR_VIRTUALENV.

New in version 2.0.

_lp_runtime_color() → var:lp_runtime_color

Returns _lp_runtime_format() with color from LP_COLOR_RUNTIME.

Changed in version 2.0: Renamed from _lp_runtime. Return code matches data function. Return method changed from stdout.

_lp_software_collections_color() → var:lp_software_collections_color

Returns _lp_software_collections() with color from LP_COLOR_VIRTUALENV.

New in version 2.0.

_lp_sudo_active_color() → var:lp_sudo_active_color

Returns _lp_sudo_active() with color and marks from LP_COLOR_MARK_SUDO if sudo is active, or LP_COLOR_MARK_NO_SUDO if not.

Does not return 1 if sudo is not active, as the return string is still needed.

Changed in version 2.0: Renamed from _lp_sudo_check. Always defined instead of only when LP_ENABLE_SUDO is enabled. Return variable changed from LP_COLOR_MARK.

_lp_temperature_color() → var:lp_temperature_color

Returns _lp_temperature() with color from LP_COLORMAP and mark from LP_MARK_TEMP.

Changed in version 2.0: Renamed from _lp_temperature. Return code matches data function. Return method changed from stdout.

_lp_time_color() → var:lp_time_color

Returns _lp_time() with color from LP_COLOR_TIME.

New in version 2.0.

_lp_vcs_details_color() → var:lp_vcs_details_color

Returns data from all generic Version Control Data Functions, colored with:

• LP_COLOR_CHANGES

• LP_COLOR_COMMITS

• LP_COLOR_COMMITS_BEHIND

• LP_COLOR_DIFF

• LP_COLOR_UP

And using marks:

• LP_MARK_STASH

• LP_MARK_UNTRACKED

This function should only be called when in a VCS repository; use _lp_find_vcs() or _lp_vcs_active() before.

The return code is undefined; a string should always be returned.

New in version 2.0.

Utility Functions

These functions are designed to be used by themes.

_lp_as_text(string) → stdout

Return string with all shell escaped substrings removed.

_lp_bool(variable[, code])

Deprecated since version 2.0.

Stores the code in a variable named variable. If code is not set, uses the last return code instead.

_lp_color_map(value, scale=100) → var:ret

Returns a color from the configured or default color map based on value and optional scale.

Values below 0 or above scale will be capped.

The returned string is a fully escaped terminal formatting sequence.

_lp_sb(string) → stdout

Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the right and the left.

_lp_sl(string) → stdout

Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the left.

_lp_sr(string) → stdout

Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the right.

_lp_smart_mark([vcs_type]) → var:lp_smart_mark

Returns a string set to the configured mark matching vcs_type. If vcs_type is not set, uses the value of lp_vcs_type instead.

If the type is “git”, extra checks are done to see if the repository is of type VCSH or git-svn instead, and return their marks if so.

_lp_title(title) → stdout

Deprecated since version 2.0: Use _lp_formatted_title instead.

Formats title with title escape codes. The input is escaped using _lp_as_text() to strip terminal formatting from being added to the title. The output should be added to PS1 to be printed as a title.

This function will do nothing if LP_ENABLE_TITLE is disabled.

_lp_formatted_title(title)

Sets the theme generated title to title. The input is escaped using _lp_as_text() to strip terminal formatting from being added to the title.

This function will do nothing and return 2 if LP_ENABLE_TITLE is disabled.

New in version 2.0.

_lp_raw_title(title)

Sets the theme generated title to title. The input is not escaped in any way: if the input contains terminal formatting, use _lp_title() instead.

This function will do nothing and return 2 if LP_ENABLE_TITLE is disabled.

New in version 2.0.

Internal Functions

These functions are designed to be used only by Liquidprompt internals and data functions. These functions should not be used by users or themes, as they are not guaranteed to be stable between versions. There are documented here for information for those developing Liquidprompt.

Config

__lp_source_config([--no-config])

Load the user config and default config values. This function is called by lp_activate().

Also setup color variables that can be used by the user for their color config. Those variables are local to this function.

If the --no-config flag is passed, defaults are set, but no config file is sourced.

Changed in version 2.0: Renamed from _lp_source_config. Added --no-config flag.

Formatting

__lp_background_color(color) → var:ab_color

Returns the terminal escape code to set the background color to the ANSI escape color code integer color. No checking is done for invalid color codes.

New in version 1.12.

Changed in version 2.0: Renamed from background_color.

__lp_foreground_color(color) → var:af_color

Returns the terminal escape code to set the foreground color to the ANSI escape color code integer color. No checking is done for invalid color codes.

New in version 1.12.

Changed in version 2.0: Renamed from foreground_color.

Git

__lp_git_diff_shortstat_files(diff_shortstat) → var:lp_git_diff_shortstat_files

Processes the input diff_shortstat as the output of a git diff --shortstat command, returning the number of changed files. This allows for the comparison of any two states, as __lp_git_diff_shortstat_files() does not run any specific git diff command.

New in version 2.0.

__lp_git_diff_shortstat_lines(diff_shortstat) → var:lp_git_diff_shortstat_lines

Processes the input diff_shortstat as the output of a git diff --shortstat command, returning the number of changed lines. This allows for the comparison of any two states, as __lp_git_diff_shortstat_files() does not run any specific git diff command.

New in version 2.0.

__lp_git_diff_shortstat_staged() → var:_lp_git_diff_shortstat_staged

Returns the output of a git diff --shortstat command, comparing the staging area to the HEAD commit.

The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

New in version 2.0.

__lp_git_diff_shortstat_uncommitted() → var:_lp_git_diff_shortstat_uncommitted

Returns the output of a git diff --shortstat command, comparing the working directory to the HEAD commit.

The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

New in version 2.0.

__lp_git_diff_shortstat_unstaged() → var:_lp_git_diff_shortstat_unstaged

Returns the output of a git diff --shortstat command, comparing the working directory to the staging area.

The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

New in version 2.0.

Load

__lp_cpu_count() → var:_lp_CPUNUM

Returns the number of CPUs on the machine. The implementation depends on the operating system.

New in version 2.0.

OS

__lp_hostname_hash() → var:lp_hostname_hash

Returns the hash of the hostname as computed by cksum.

New in version 2.0.

Path

__lp_end_path_left_shortening()

Terminate a multi-directory shortening, checking if the shortening actually made a shorter path, and if so, adding the shortened mark. If not, adds the real path to the output. Only used internally by _lp_path_format().

New in version 2.0.

__lp_get_unique_directory(path) → var:lp_unique_directory

Returns the shortest unique directory prefix matching the real directory input. Only used internally by _lp_path_format().

New in version 2.0.

__lp_pwd_tilde([path]) → var:lp_pwd_tilde

Returns path, or PWD if path is not set, with the user’s home directory replaced with a tilde (“~”).

Changed in version 2.0: Renamed from _lp_get_home_tilde_collapsed. Return method changed from stdout. Optional parameter path added.

Prompt

__lp_set_prompt()

Setup features that need to be handled outside of the themes, like _lp_error() (since last return code must be recorded first), non printing features like LP_ENABLE_RUNTIME_BELL and LP_ENABLE_TITLE, track current directory changes, and initialize data source cache variables. This function also calls the current theme functions.

Changed in version 2.0: Renamed from _lp_set_prompt.

Runtime

__lp_runtime_before()

Hooks into the shell to run directly after the user hits return on a command, to record the current time before the command runs.

Changed in version 2.0: Renamed from _lp_runtime_before.

__lp_runtime_after()

Hooks into the shell to run directly after the user command returns, to record the current time, and calculate how long the command ran for.

Changed in version 2.0: Renamed from _lp_runtime_after.

Theme

__lp_theme_list() → var:lp_theme_list

Returns an array of Liquidprompt themes currently loaded in memory. Looks for functions matching _lp_*_theme_prompt.

New in version 2.0.

__lp_theme_bash_complete() → var:COMPREPLY

Uses __lp_theme_list() to provide Bash autocompletion for lp_theme().

New in version 2.0.

__lp_theme_zsh_complete()

Uses __lp_theme_list() to provide Zsh autocompletion for lp_theme().

New in version 2.0.

Temperature

__lp_temp_detect() → var:_LP_TEMP_FUNCTION

Attempts to run the possible temperature backend functions below to find one that works correctly. When one correctly returns a value, it is saved to _LP_TEMP_FUNCTION for use by _lp_temperature().

Changed in version 2.0: Renamed from _lp_temp_detect.

__lp_temp_acpi() → var:lp_temperature

A temperature backend using acpi.

Changed in version 2.0: Renamed from _lp_temp_acpi. Return variable changed from temperature.

__lp_temp_sensors() → var:lp_temperature

A temperature backend using lm-sensors provided sensors.

Changed in version 2.0: Renamed from _lp_temp_sensors. Return variable changed from temperature.

Utility

__lp_escape(string) → var:ret

Escape shell escape characters so they print correctly in PS1.

In Bash, backslashes (\) are used to escape codes, so backslashes are replaced by two backslashes.

In Zsh, percents (%) are used to escape codes, so percents are replaced by two percents.

Changed in version 2.0: Renamed from _lp_escape. Return method changed from stdout.

__lp_floating_scale(number, scale) → var:ret

Returns the input floating point number multiplied by the input scale. The input scale must be a power of 10.

Shells do not support floating point math, so this is used to scale up floating point numbers to integers with the needed precision.

New in version 2.0.

__lp_is_function(function)

Returns true if function is the name of a function.

New in version 2.0.

__lp_line_count(string) → var:count

Count the number of newline characters (\n) in string. A faster drop-in replacement for wc -l.

New in version 2.0.

Release Notes

The release documents here are a brief overview of the most important changes in a release. See the Changelog for a full description of what has changed.

For a full description of what a user needs to do to upgrade, see Upgrading Liquidprompt.

Version 2.0 Release Notes

Version 2.0 had to break a few eggs, but got a lot of reward out of it. This release is full of new features and improvements.

Speed Improvements

By removing subshells, exec, and other fork ing calls, the whole project has seen incredible speed improvements, anywhere from 1.5 to 10 times as fast.

Theme Engine

Thanks to the new data source functions (see below), themes are able to change everything about how the prompt is displayed, instead of only color and element order. See Theming.

Example Themes

Liquidprompt now ships with some example themes showcasing how the new theme engine works. They are also fulling working themes that you can use as your daily drivers. See Included Themes.

Data Sources

To power the themes, all of the data sources in Liquidprompt have been broken out into individual data functions that can be called by themes. They are also documented in detail in Data Functions.

Path Advanced Formatting

The current directory path has had an overhaul, now supporting formatting for different path sections, highlighting the last directory and the VCS repository root directory. Any shortened directories are lowlighted instead. Multiple path shortening methods are now supported as well.

See LP_PATH_METHOD and LP_COLOR_PATH for more information.

Version Control Interface

Before, each version control provider had its own function for displaying repository information. Now there is a unifying interface over all VCS providers that themes can use to display any VCS provider the same as all the others. See Version Control Data Functions.

The default theme now uses this interface to display all VCS providers in the same way (similar to how Git was displayed before). See Default Theme Functions.

Version Control Tracking updates without directory change

Before, if git init or similar was run in a directory, Liquidprompt would not display any repository information until the current directory was changed. Thanks to the speed improvements, Liquidprompt now checks for a repository at each prompt, while still being faster than version 1.12.

Activate Function

Before, when changing the user config file, a user needed to source liquidprompt again to load their config changes (or exec bash or exec zsh). Now that all of the initialization code has been refactored into lp_activate, running lp_activate after modifying the config file or installing a new feature dependent program like git is all that is needed!

Documentation

The often lacking README documentation has been re-written with Sphinx to make this much improved documentation source.

Unit Tests

A whole suite of unit tests has been added to test the data and untility functions. A handful of bugs were caught using the tests, so the investment has already paid off!

Dirstack Feature

Shell directory stack display is now in the prompt! If there are directories on the stack (from pushd), the number of directories in the stack is shown next to the current path. See LP_ENABLE_DIRSTACK for more information.

Version 1.12 Release Notes

Most of the changes in 1.12 are accumulated bug fixes, but a few features made it in as well.

Runtime Bell

A new feature, similar to the displayed last command runtime, is to ring the terminal bell when the running command exits, if the runtime was over a threshold. This can be used to notify when a long running command has finished.

See the LP_RUNTIME_BELL and LP_RUNTIME_BELL_THRESHOLD config options.

Permissions Mark

The : mark between the hostname and the current directory was a constant string, but now it has a config option: LP_MARK_PERM.

Preset Color Aliases

The 5 value of the basic colors is often named “magenta”, but in Liquidprompt it has always been “purple”, and the bold version is “pink”.

To make the options more standard, an alias for PURPLE is MAGENTA, and PINK now has aliases of BOLD_PURPLE and BOLD_MAGENTA.

Speed Improvements

Improvements to the startup process have cut startup times by at least 30% in all cases.

Upgrading Liquidprompt

We try our best to make new versions of Liquidprompt backwards compatible with previous versions, but sometimes things need to change to make forward progress. If a version introduces breaking changes or deprecation notices, a detailed document describing what changes a user needs to make will be linked below.

Version 2.0 Upgrade Notes

Most of the changes in 2.0 are in private functions and variables. There are a few public API changes that could impact users: $lp_err, $LP_DISABLED_VCS_PATH, $LP_PATH_DEFAULT, $PROMPT_DIRTRIM, $LP_PATH_KEEP=-1, and _lp_title(). The rest are private API changes, but are still documented here.

Breaking Changes

Public Breaking Changes

$lp_err

Renamed to $lp_error. Instead of referencing it directly, use _lp_error().

Private Breaking Changes

$_LP_SHELL_bash

Now returns 1 or 0 instead of true or false

Replace test statements like:

if $_LP_SHELL_bash; then

with:

if (( $_LP_SHELL_bash )); then

$_LP_SHELL_zsh

Now returns 1 or 0 instead of true or false

Replace test statements like:

if $_LP_SHELL_zsh; then

with:

if (( $_LP_SHELL_zsh )); then

_lp_battery()

Return changed from stdout to $lp_battery

Replace assignment statements like:

battery="$(_lp_battery)"

with:

local lp_battery
_lp_battery
battery=$lp_battery

See also: _lp_battery().

_lp_battery_color()

Return changed from stdout to $lp_battery_color

Replace assignment statements like:

battery_color="$(_lp_battery_color)"

with:

local lp_battery_color
_lp_battery_color
battery_color=$lp_battery_color

See also: _lp_battery_color().

_lp_bzr_branch()

Return changed from stdout to $lp_vcs_branch

Recommended that _lp_vcs_branch() is used instead.

Replace assignment statements like:

branch="$(_lp_bzr_branch)"

with:

local lp_vcs_branch
if _lp_bzr_branch; then
    branch=$lp_vcs_branch
fi

_lp_bzr_branch_color()

Removed, replace by _lp_vcs_details_color().

If the exact previous output is needed, you can implement a theme function using Version Control Data Functions.

Replace assignment statements like:

LP_VCS="$(_lp_bzr_branch_color)"

with:

if _lp_find_vcs;
    local lp_vcs_details_color
    _lp_vcs_details_color
    LP_VCS=$lp_vcs_details_color
fi

_lp_color_map()

Return changed from stdout to $ret

Replace assignment statements like:

output="$(_lp_color_map "$input")"

with:

local ret
_lp_color_map "$input"
output=$ret

See also: _lp_color_map().

_lp_connection()

Return changed from stdout to $lp_connection

Replace assignment statements like:

connection="$(_lp_connection)"

with:

local lp_connection
_lp_connection
connection=$lp_connection

See also: _lp_connection().

_lp_escape()

Renamed to __lp_escape. Return changed from stdout to $ret

Replace assignment statements like:

output="$(_lp_escape "$input")"

with:

local ret
__lp_escape "$input"
output=$ret

_lp_fossil_branch()

Return changed from stdout to $lp_vcs_branch

Recommended that _lp_vcs_branch() is used instead.

No longer returns “no-branch” if branch not found.

Replace assignment statements like:

branch="$(_lp_fossil_branch)"

with:

local lp_vcs_branch
if _lp_fossil_branch; then
    branch=$lp_vcs_branch
else
    branch="no-branch"
fi

_lp_fossil_branch_color()

Removed, replace by _lp_vcs_details_color().

If the exact previous output is needed, you can implement a theme function using Version Control Data Functions.

Replace assignment statements like:

LP_VCS="$(_lp_fossil_branch_color)"

with:

if _lp_find_vcs;
    local lp_vcs_details_color
    _lp_vcs_details_color
    LP_VCS=$lp_vcs_details_color
fi

_lp_get_home_tilde_collapsed()

Renamed to __lp_pwd_tilde().

Return changed from stdout to $lp_pwd_tilde

Recommended that lp_path is used instead.

Replace assignment statements like:

working_dir="$(_lp_get_home_tilde_collapsed)"

with:

local lp_pwd_tilde
__lp_pwd_tilde
working_dir=$lp_pwd_tilde

_lp_git_branch()

Return changed from stdout to $lp_vcs_branch

Recommended that _lp_vcs_branch() is used instead.

No longer returns commit hash if branch not found.

Replace assignment statements like:

branch="$(_lp_git_branch)"

with:

local lp_vcs_branch
if _lp_git_branch; then
    branch=$lp_vcs_branch
else
    local lp_vcs_commit_id
    _lp_git_commit_id
    branch=$lp_vcs_commit_id
fi

_lp_git_branch_color()

Removed, replace by _lp_vcs_details_color().

Replace assignment statements like:

LP_VCS="$(_lp_git_branch_color)"

with:

if _lp_find_vcs;
    local lp_vcs_details_color
    _lp_vcs_details_color
    LP_VCS=$lp_vcs_details_color
fi

_lp_git_head_status()

Return changed from stdout to $lp_vcs_head_status

Recommended that _lp_vcs_head_status() is used instead.

Replace assignment statements like:

head_status="$(_lp_git_head_status)"

with:

local lp_vcs_head_status
_lp_git_head_status
head_status=$lp_vcs_head_status

See also: _lp_git_head_status().

_lp_hg_branch()

Return changed from stdout to $lp_vcs_branch

Recommended that _lp_vcs_branch() is used instead.

Replace assignment statements like:

branch="$(_lp_hg_branch)"

with:

local lp_vcs_branch
if _lp_hg_branch; then
    branch=$lp_vcs_branch
fi

_lp_hg_branch_color()

Removed, replace by _lp_vcs_details_color().

If the exact previous output is needed, you can implement a theme function using Version Control Data Functions.

Replace assignment statements like:

LP_VCS="$(_lp_hg_branch_color)"

with:

if _lp_find_vcs;
    local lp_vcs_details_color
    _lp_vcs_details_color
    LP_VCS=$lp_vcs_details_color
fi

_lp_jobcount_color()

Return changed from stdout to $lp_jobcount_color

Replace assignment statements like:

jobcount_color="$(_lp_jobcount_color)"

with:

local lp_jobcount_color
_lp_jobcount_color
jobcount_color=$lp_jobcount_color

See also: _lp_jobcount_color().

_lp_load_color()

Return changed from stdout to $lp_load_color

Replace assignment statements like:

load_color="$(_lp_load_color)"

with:

local lp_load_color
_lp_load_color
load_color=$lp_load_color

See also: _lp_load_color().

_lp_runtime()

Renamed to _lp_runtime_color().

Return changed from stdout to $lp_runtime_color

Replace assignment statements like:

runtime_color="$(_lp_runtime)"

with:

local lp_runtime_color
_lp_runtime_color
runtime_color=$lp_runtime_color

_lp_runtime_after()

Renamed to __lp_runtime_after().

Recommended to not use this internal function.

_lp_runtime_before()

Renamed to __lp_runtime_before().

Recommended to not use this internal function.

_lp_set_dirtrim()

Renamed to __lp_set_dirtrim().

Recommended that lp_path is used instead.

_lp_set_prompt()

Renamed to __lp_set_prompt.

Recommended to not use this internal function.

_lp_shorten_path()

Removed and replaced by _lp_path_format().

Replace assignment statements like:

cwd="$(_lp_shorten_path)"

with:

local lp_path_format
_lp_path_format "$LP_COLOR_PATH" "$LP_COLOR_PATH_LAST_DIR" "$LP_COLOR_PATH_VCS_ROOT" "$LP_COLOR_PATH_SHORTENED" "/" "$LP_COLOR_PATH_SEPARATOR"
cwd=$lp_path_format

_lp_smart_mark()

Return changed from stdout to $lp_smart_mark

Replace assignment statements like:

mark="$(_lp_smart_mark)"

with:

local lp_smart_mark
_lp_smart_mark
mark=$lp_smart_mark

See also: _lp_smart_mark().

_lp_source_config()

Renamed to __lp_source_config.

Recommended to not use this internal function.

_lp_svn_branch()

Return changed from stdout to $lp_vcs_branch

Recommended that _lp_vcs_branch() is used instead.

No longer returns directory name if branch not found.

Replace assignment statements like:

branch="$(_lp_svn_branch)"

with:

local lp_vcs_branch
if _lp_svn_branch; then
    branch=$lp_vcs_branch
else
    local lp_vcs_commit_id
    _lp_svn_commit_id
    branch=$lp_vcs_commit_id
fi

_lp_svn_branch_color()

Removed, replace by _lp_vcs_details_color().

If the exact previous output is needed, you can implement a theme function using Version Control Data Functions.

Replace assignment statements like:

LP_VCS="$(_lp_svn_branch_color)"

with:

if _lp_find_vcs;
    local lp_vcs_details_color
    _lp_vcs_details_color
    LP_VCS=$lp_vcs_details_color
fi

_lp_temp_acpi()

Renamed to __lp_temp_acpi().

Recommended that _lp_temperature() is used instead.

Return changed from $temperature to $lp_temperature.

Replace statements like:

_lp_temp_acpi
# use $temperature

with:

__lp_temp_acpi
# use $lp_temperature

_lp_temp_detect()

Renamed to __lp_temp_detect().

Recommended to not use this internal function.

_lp_temp_sensors()

Renamed to __lp_temp_sensors().

Recommended that _lp_temperature() is used instead.

Return changed from $temperature to $lp_temperature.

Replace statements like:

_lp_temp_sensors
# use $temperature

with:

__lp_temp_sensors
# use $lp_temperature

_lp_temperature()

Renamed to _lp_temperature_color().

Return changed from stdout to $lp_temperature_color

Replace assignment statements like:

temp_color="$(_lp_temperature)"

with:

local lp_temperature_color
_lp_temperature_color
temp_color=$lp_temperature_color

Not to be confused with the new _lp_temperature().

_lp_time()

Split into _lp_time(), _lp_time_color(), _lp_analog_time(), and _lp_analog_time_color().

The return value is no longer stored in LP_TIME.

Replace statements like:

_lp_time

with:

local lp_time_color lp_analog_time_color
if _lp_time_color; then
    LP_TIME="${lp_time_color} "
elif _lp_analog_time_color; then
    LP_TIME="${lp_analog_time_color} "
else
    LP_TIME=
fi

_lp_upwards_find()

Replaced by _lp_find_vcs().

Replace statements like:

_lp_upwards_find .hg || return

with:

local lp_vcs_type lp_vcs_root
_lp_find_vcs && [[ $lp_vcs_type == hg ]] || return

Deprecations

Public Deprecations

$LP_DISABLED_VCS_PATH

Replaced by LP_DISABLED_VCS_PATHS array variable.

Replace a set statement like:

LP_DISABLED_VCS_PATH="/my/one/path:/my/other/path"

with:

LP_DISABLED_VCS_PATHS=("/my/one/path" "/my/other/path")

$LP_PATH_DEFAULT

Replaced by LP_PATH_METHOD.

If one of the many new shortening methods does not effectively replace your use case, please open an enhancement request.

$PROMPT_DIRTRIM

$PROMPT_DIRTRIM calculation is no longer supported. Replaced by LP_PATH_METHOD set to truncate_chars_from_path_left.

$LP_PATH_KEEP=-1

LP_PATH_KEEP set to -1 is replaced by LP_PATH_METHOD set to truncate_to_last_dir.

_lp_title()

Replaced by _lp_formatted_title().

Most likely would have been used in a template or .ps1 file.

Replace a call like:

LP_TITLE="$(_lp_title "$PS1")"
PS1="${LP_TITLE}${PS1}"

with:

_lp_formatted_title "$PS1"

Private Deprecations

_lp_bool()

Replaced by manually storing return codes.

Most often, the return code can be used in an if block, and never needs to be stored:

if _lp_http_proxy; then
...

If the function returns a more complicated return code, you can store it like this:

_lp_user
local -i code="$?"

or like this if the code only matters if it is not zero:

_lp_user || local -i code="$?"

_lp_sb()

Replaced by data functions indicating if they returned data or not. For example:

if _lp_http_proxy; then
    my_data="${lp_http_proxy} "
else
    my_data=""
fi

If the string source is not a data function, you can replace this function with a structure like:

[[ -n $my_data ]] && my_data=" ${my_data} "

With spaces before or after as needed.

_lp_sl()

See _lp_sb() above.

_lp_sr()

See _lp_sb() above.

Indices and tables

• Index

• Search Page