Data Functions
- Version Control Data Functions
- Generic
_lp_find_vcs()
_lp_are_vcs_enabled()
_lp_vcs_active()
_lp_vcs_bookmark()
_lp_vcs_branch()
_lp_vcs_commit_id()
_lp_vcs_commits_off_remote()
_lp_vcs_head_status()
_lp_vcs_remote()
_lp_vcs_staged_files()
_lp_vcs_staged_lines()
_lp_vcs_stash_count()
_lp_vcs_tag()
_lp_vcs_uncommitted_files()
_lp_vcs_uncommitted_lines()
_lp_vcs_unstaged_files()
_lp_vcs_unstaged_lines()
_lp_vcs_untracked_files()
- Bazaar
- Fossil
- Git
_lp_git_active()
_lp_git_branch()
_lp_git_commit_id()
_lp_git_commits_off_remote()
_lp_git_head_status()
_lp_git_staged_files()
_lp_git_staged_lines()
_lp_git_stash_count()
_lp_git_tag()
_lp_git_uncommitted_files()
_lp_git_uncommitted_lines()
_lp_git_unstaged_files()
_lp_git_unstaged_lines()
_lp_git_untracked_files()
- Mercurial
- Subversion
- Generic
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 available4
if no battery level is found3
if charging and the level is above the threshold2
if charging and the level is under the threshold1
if discharging and the level is above the threshold0
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
.Changed in version 2.1: Implemented sysfs method as the default way of getting battery status.
Development Environment
- _lp_cmake() var:lp_cmake_compiler, var:lp_cmake_generator, var:lp_cmake_buildtype
Returns
true
if a CMake context is found. Parse the data in CMakeCache.txt and returns the basename of the configured compiler, generator (e.g. “Unix Makefiles”), and build type (“Debug”, “Release”, etc.). Some generator names are shorten: “Makefiles” becomes “Make” and “Visual Studio” becomes “VS”.Can be disabled by
LP_ENABLE_CMAKE
.New in version 2.2.
- _lp_kubernetes_context() var:lp_kubernetes_context, var:lp_kubernetes_namespace
Returns
true
if a Kubernetes context is found. Returns the Kubernetes context name or the first name component.Splitting long context names into components is defined by
LP_DELIMITER_KUBECONTEXT_SUFFIX
andLP_DELIMITER_KUBECONTEXT_PREFIX
. Both use greedy matches - see Config Options for examples.If enabled by
LP_ENABLE_KUBE_NAMESPACE
, will also return the default namespace for the current context, if one is set.Can be disabled by
LP_ENABLE_KUBECONTEXT
.New in version 2.1.
- _lp_node_env() var:lp_node_env
Returns
true
if a Node.js environment is detected. Returns the virtual environment name.Can be enabled by
LP_ENABLE_NODE_VENV
.New in version 2.1.
- _lp_perl_env() var:lp_perl_env
Returns
true
if a Perlbrew or PLENV Perl environment is detected. Returns the virtual environment name.Can be disabled by
LP_ENABLE_PERL_VENV
.New in version 2.2.
- _lp_python_env() var:lp_python_env
Returns
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.
Changed in version 2.1: Displays the “prompt string” first (the
--prompt
argument when setting up the virtualenv).
- _lp_ruby_env() var:lp_ruby_env
Returns
true
if a RVM or RBENV ruby environment is detected. Returns the virtual environment name.In the case of a RVM environment, the label displayed can be customized with the
LP_RUBY_RVM_PROMPT_OPTIONS
.Can be disabled by
LP_ENABLE_RUBY_VENV
.New in version 2.1.
- _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.
- _lp_terraform_env() var:lp_terraform_env
Returns
true
if a Terraform workspace is detected. Returns the workspace name.Can be enabled by
LP_ENABLE_TERRAFORM
.New in version 2.1.
Disks and Memory
- _lp_disk -> var:lp_disk, var:lp_disk_human, var:lp_disk_perc
Gather information about the current state of the hard drive hosting the current directory:
available space in kibi-bytes (
lp_disk
, that is, 1024 bytes),available space in human-readable form, using binary unit prefixes (
lp_disk_human
, see also__lp_bytes_to_human()
).available space as a percentage of total (
lp_disk_perc
).
Returns
true
if the used space is below at least one of the user-defined thresholds:Can be disabled by
LP_ENABLE_DISK
.New in version 2.2.
- _lp_ram -> var:lp_ram, var:lp_ram_human, var:lp_ram_perc
Gather information about the current state of the RAM:
available space in kibi-bytes (
lp_ram
, that is, 1024 bytes),available space in human-readable form, using binary unit prefixes (
lp_ram_human
, see also__lp_bytes_to_human()
).available space as a percentage of total (
lp_ram_perc
).
Returns
true
if the used space is below at least one of the user-defined thresholds:Can be disabled by
LP_ENABLE_RAM
.New in version 2.2.
Environment
- _lp_aws_profile() var:lp_aws_profile
Returns
true
if theAWS_PROFILE
,AWS_DEFAULT_PROFILE
, orAWS_VAULT
variables are found in the environment (in that order of preference). Returns the contents of the variable.Can be disabled by
LP_ENABLE_AWS_PROFILE
.New in version 2.1.
- _lp_connected_display()
Returns
true
if there is a connected X11 display.New in version 2.0.
Changed in version 2.2: Can be disabled by
LP_ENABLE_DISPLAY
.
- _lp_connection() var:lp_connection
Returns a string matching the connection context of the shell. Valid values:
ssh
- connected over OpenSSHtel
- connected over Telnetsu
- running in asu
orsudo
shelllcl
- running in a local terminal
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_container() var:lp_container
Returns
true
if the shell is running in a container. In that case, the return variable is set to a string matching the container type. Possible values include (but are not limited to):Singlrty
- running in a Singularity containerToolbox
- running in a Toolbox containerPodman
- running in a Podman containerDocker
- running in a Docker containerLXC
- running in an LXC containernspawn
- running in a systemd-nspawn container
It is not possible to detect more than one containerization type to be returned. The containers are checked in the order listed above, and the first one found will be returned.
Can be enabled by
LP_ENABLE_CONTAINER
.New in version 2.1.
- _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_env_vars([color_if_set[, color_if_unset[, end_color]]]) var:lp_env_vars
Gather the states of the environment variables indicated in the
LP_ENV_VARS
array, and put them in thelp_env_vars
array.LP_ENV_VARS
should be a list of environment variable names to look for, along with the string to be displayed if the variable is set, and an optional string to be displayed if the variable is not set. The string to be displayed may contain a%s
marker, which will be replaced by the variable’s content.If
color_if_set
is passed, it will be used to color the set variables string. Ifcolor_if_unset
is passed, it will be used to color the unset variables string.end_color
is added at the end of each variable string. It defaults to “$NO_COL” (color reset).Returns
true
if at least one variable representation is added to the result array. Returns1
if the no variable representation is set. Returns2
if the user disabled the feature withLP_ENABLE_ENV_VARS
.New in version 2.2.
- _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_error_meaning() var:lp_error_meaning
Returns
true
if the last user shell command returned a non-zero exit code. Returns (in the return variable) a guess of the meaning of that error.Can be disabled by
LP_ENABLE_ERROR_MEANING
.New in version 2.2.
- _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_multiplexer
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.
Changed in version 2.2: Can be disabled by
LP_ENABLE_MULTIPLEXER
, except if--internal
is passed (i.e. for internal use only).
- _lp_shell_level() var:lp_shell_level
Returns
true
if the shell is a nested shell inside another shell.Can be disabled by
LP_ENABLE_SHLVL
.New in version 2.1.
- _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 thebg
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.
Changed in version 2.2: Can be disabled by
LP_ENABLE_CHROOT
.
- _lp_hostname() var:lp_hostname
Returns
true
if a hostname should be displayed. Returns1
if the connection type is local andLP_HOSTNAME_ALWAYS
is not1
.Returns the hostname string in lp_hostname.
Can be disabled by
LP_HOSTNAME_ALWAYS
set to-1
.New in version 2.0.
Changed in version 2.1: Returns the actual hostname instead of a shell prompt escape code. No longer sets
LP_HOST_SYMBOL
to the same return string. AddedLP_HOSTNAME_METHOD
to configure display method.
- _lp_os() var:lp_os_arch, var:lp_os_family, var:lp_os_kernel, var:lp_os_distrib, var:lp_os_version
Gather data about the current Operating System.
Returns
true
if it was able to gather all possible data. Returns1
if some expected information was missing. Returns2
if the user disabled the feature withLP_ENABLE_OS
.Returns data in
lp_os_*
variables:processor architecture (e.g. x86_64, i686, etc.),
OS family (BSD, UNIX, GNU or Windows),
OS kernel (Linux, Darwin, Cygwin, etc.),
Linux distribution (e.g. ubuntu, arch, mandrake, etc.),
Linux distribution version codename (e.g. focal, ada, buzz, etc.)
Each data source can be disabled via its corresponding configuration variable:
New in version 2.2.
- _lp_sudo_active()
Returns
true
ifsudo
is currently activated with valid credentials. Ifsudo
is configured to always allow a user to run commands with no password, this will always returntrue
.Can be disabled by
LP_ENABLE_SUDO
.New in version 2.0.
Changed in version 2.1: If the user has NOPASSWD powers, that is cached on startup to prevent multiple
sudo
calls.
- _lp_user()
Returns a return code depending on the logged in user:
2
- the user is root1
- the user is a user other than the original login user0
- the user is the login user
New in version 2.0.
- _lp_username() var:lp_username
Returns
true
if a username should be displayed. Returns1
if the user is the login user andLP_USER_ALWAYS
is not1
.Returns the current user ID in lp_username.
Can be disabled by
LP_USER_ALWAYS
set to-1
.New in version 2.0.
Changed in version 2.1: Returns the actual username instead of a shell prompt escape code.
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, custom separators, or shell escapes, 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
, andLP_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.
Changed in version 2.1: Changed lp_path to no longer contain shell escapes.
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.
If no temperature data is found, returns
false
and lp_temperature will not be set.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, formatting set byLP_TIME_FORMAT
.Can be disabled by
LP_ENABLE_TIME
, orLP_TIME_ANALOG
set to1
.New in version 2.0.
Changed in version 2.1: Returns the actual time instead of a shell prompt escape code.
- _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
, orLP_TIME_ANALOG
set to0
.New in version 2.0.
Wireless
- _lp_wifi_signal_strength() var:lp_wifi_signal_strength
Returns
true
if the lowest wireless signal strength is lower than the threshold. Returns the lowest strength percentage.If the threshold is not surpassed, the lowest signal strength is still returned.
If no wireless signal data is found, returns
false
and lp_wifi_signal_strength will not be set.The threshold is configured with
LP_WIFI_STRENGTH_THRESHOLD
.Can be disabled by
LP_ENABLE_WIFI_STRENGTH
.New in version 2.1.