Liquid prompt -- A useful adaptive prompt for Bash & Zsh
Liquid prompt is a smart prompt for the "Bourne-Again" Unix shell (bash) and for Zsh.
The basic idea of the liquid prompt is to nicely display useful informations on the shell prompt, only when they are needed. It adds carefuly chosen colors to draw your attention on what differs from the normal context. Thus, you will notice what changes, when it changes, because you do not become accommodated to informations that are always displayed in the same way.
You can use it with either bash and zsh.
FEATURES
If there is nothing special in the current context, the liquid prompt is close to a default prompt:
[user:~] $
If you have ran one command in background that is still running and that you are in a git repository on a server, at branch "myb":
1r [user@server:~/liquidprompt] myb ±
A liquid prompt displaying everything may look like this:
⌁24% ⌂42% 3d/2&/1z [user@server:~/ … /code/liquidprompt]↥ master(+10/-5,3)* 125 ±
It displays:
- a green ⌁ if the battery is charging and above a given threshold, a yellow ⌁ if the battery is charging and under threshold, a red ⌁ if the battery is discharging but above threshold;
- the average of the batteries remaining power, if it is under the given threshold, with a colormap, going more and more red with decreasing power;
- the average of the processors load, if it is over a given limit, with a colormap that became more and more noticeable with increasing load;
- the number of detached sessions (
screen
), if there is any; - the number of attached sleeping jobs (when you interrupt a command with Ctrl-Z
and bring it back with
fg
), if there is any; - the number of attached running jobs (commands started with a
&
), if there is any; - a pair of square brackets, in blue if your current shell is running in a terminal multiplexer (screen or tmux);
- the current user, in bold yellow if it is root, in light white if it is not the same as the login user;
- a blue @ if the connection has X11 support;
- the current host, if you are connected via an SSH or telnet connection, with different colors for each case;
- a green colon if the user has write permissions on the current directory, a red one if he has not;
- the current directory in bold, shortened if it takes too much space, while preserving the first two directories;
- the current Python virtual environment, if any;
- an up arrow if an HTTP proxy is in use;
- the name of the current branch if you are in a version control repository (git, mercurial, subversion or fossil), in green if everything is up to date, in red if there is changes, in yellow if there is pending commits to push;
- the number of added/deleted lines (git) or files (fossil), if changes have been made and the number of pending commits, if any;
- a yellow plus if there is stashed modifications;
- a red star if there is some untracked files in the repository;
- the error code of the last command, if it has failed in some way;
- a smart mark: ± for git directories, ☿ for mercurial, ‡ for svn, ⌘ for fossil, $ for simple user, a red # for root;
- if you ask for, the liquidprompt will be replicated in your terminal window's title (without the colors);
- you can easily add a prefix tag to your prompt, by invoking
prompt_tag MYTAG
.
You can temporarily deactivate the liquid prompt and come back to your previous
one by typing prompt_off
. Use prompt_on
to bring it back. You can deactivate
any prompt and use a single mark sign ($
for user and #
for root) with the
prompt_OFF
command.
INSTALL
Include the file in your bash configuration, for example in your .bashrc
:
source liquidprompt
Copy the liquidpromptrc-dist
file in your home directory as
~/.config/liquidpromptrc
or ~/.liquidpromptrc
and edit it according to your
preferences. If you skip this step, the default behaviour will be used.
Note that you should not overwrite the PROMPT_COMMAND
variable, or else the
prompt will not be available.
DEPENDENCIES
Apart from obvious ones, some features depends on specific commands. If you do not install them, the corresponding feature will not be available, but you will see no error.
- battery status need
acpi
, - detached sessions is looking for
screen
. - VCS support features needs…
git
,hg
orsvn
, but you knew it.
For other features, the script uses commands that should be available on a large
variety of unixes: tput
, grep
, awk
, sed
, ps
, who
.
FEATURES CONFIGURATION
You can configure some variables in the ~/.liquidpromptrc
file:
LP_BATTERY_THRESHOLD
, the maximal value under which the battery level is displayedLP_LOAD_THRESHOLD
, the minimal value after which the load average is displayedLP_PATH_LENGTH
, the maximum percentage of the screen width used to display the pathLP_PATH_KEEP
, how many directories to keep at the beginning of a shortened pathLP_HOSTNAME_ALWAYS
, choose between always displaying the hostname or showing it only when connected with a remote shellLP_USER_ALWAYS
, choose between always displaying the user or showing it only when he is different from the logged one
You can also force some features to be disabled, to save some time in the prompt building:
LP_ENABLE_PERM
, if you want to detect if the directory is writableLP_ENABLE_SHORTEN_PATH
, if you to shorten the path displayLP_ENABLE_PROXY
, if you want to detect if a proxy is usedLP_ENABLE_JOBS
, if you want to have jobs informationsLP_ENABLE_LOAD
, if you want to have load informationsLP_ENABLE_BATT
, if you want to have battery informationsLP_ENABLE_GIT
, if you want to have git informationsLP_ENABLE_SVN
, if you want to have subversion informationsLP_ENABLE_HG
, if you want to have mercurial informationsLP_ENABLE_FOSSIL
, if you want to have fossil informationsLP_ENABLE_VCS_ROOT
, if you want to show VCS informations with root accountLP_ENABLE_TITLE
, if you want to use the prompt as your terminal window's titleLP_ENABLE_SCREEN_TITLE
, if you want to use the prompt as your screen window's title
Note that if required commands are not installed, enabling the
corresponding feature will have no effect.
Note also that all the LP_ENABLE_…
variables override the templates,
i.e. if you use $LP_BATT
in your template and you set LP_ENABLE_BATT=0
in your config file, you will not have the battery informations.
If you are using bash and want to use the PROMPT_DIRTRIM
built-in
functionality to shorten but still have liquidprompt calculating the number of
directories to keep in the path, precise a value for PROMPT_DIRTRIM
before
sourcing liquidprompt and liquidprompt will override this value with one
fitting the width of your terminal.
CUSTOMIZING THE PROMPT
ADD A PS1 PREFIX
You can prefix the LP_PS1
variable with anything you want using the
LP_PS1_PREFIX
. The following example activate a custom window's title:
LP_PS1_PREFIX="\[\e]0;\u@\h: \w\a\]"
Note: the prompt_tag
function is convenient way to add a prefix. You can thus add
a keyword to your different terminals:
[:~/code/liquidprompt] develop ± prompt_tag mycode
mycode [:~/code/liquidprompt] develop ±
PUT THE PROMPT IN A DIFFERENT ORDER
You can sort what you want to see by sourcing your favorite template file
(*.ps1
) in the configuration file.
Those scripts basically export the LP_PS1
variable, by appending features and
theme colors.
Available features:
LP_BATT
batteryLP_LOAD
loadLP_JOBS
screen sessions/running jobs/suspended jobsLP_USER
userLP_HOST
hostnameLP_PERM
a colon ":"LP_PWD
current working directoryLP_PROXY
HTTP proxyLP_VCS
informations concerning the current working repositoryLP_ERR
last error codeLP_MARK
prompt markLP_TITLE
the prompt as a window's title escaped sequence
For example, if you just want to have a liquidprompt displaying the user and the host, with a normal full path in blue and only the git support:
export LP_PS1=`echo -ne "[\${LP_USER}\${LP_HOST}:\${BLUE}\$(pwd)\${NO_COL}] \${LP_GIT} \\\$ "`
Note that you need to properly escape dollars in a string that wil be interpreted by bash at each prompt.
To erase your new formatting, just bring the LP_PS1
to a null string:
export LP_PS1=""
THEMES
You can change the colors and special characters of some part of the liquid
prompt by sourcing your favorite theme file (*.theme
) in the configuration file.
COLORS
Available colors are: BOLD, BLACK, BOLD_GRAY, WHITE, BOLD_WHITE, GREEN, BOLD_GREEN, YELLOW, BOLD_YELLOW, BLUE, BOLD_BLUE, PINK, CYAN, BOLD_CYAN RED, BOLD_RED, WARN_RED, CRIT_RED, DANGER_RED, NO_COL. Set to a null string "" if you do not want color.
- Current working directory
LP_COLOR_PATH
as normal userLP_COLOR_PATH_ROOT
as root
- Color of the proxy mark
LP_COLOR_PROXY
- Jobs count
LP_COLOR_JOB_D
Detached (aka screen sessions)LP_COLOR_JOB_R
Running (xterm &)LP_COLOR_JOB_Z
Sleeping (Ctrl-Z)LP_COLOR_IN_MULTIPLEXER
currently running in a terminal multiplexer
- Last error code
LP_COLOR_ERR
- Prompt mark
LP_COLOR_MARK
as userLP_COLOR_MARK_ROOT
as root
- Current user
LP_COLOR_USER_LOGGED
user who logged inLP_COLOR_USER_ALT
user but not the one who logged inLP_COLOR_USER_ROOT
root
- Hostname
LP_COLOR_HOST
local hostLP_COLOR_SSH
connected via SSHLP_COLOR_TELNET
connected via telnetLP_COLOR_X11_ON
connected with X11 supportLP_COLOR_X11_OFF
connected without X11 support
- Separation mark (aka permiison in the working dir)
LP_COLOR_WRITE
have write permissionLP_COLOR_NOWRITE
do not have write permission
- VCS
LP_COLOR_UP
repository is up to date / a push have been madeLP_COLOR_COMMITS
some commits have not been pushedLP_COLOR_CHANGES
there is some changes to commitLP_COLOR_DIFF
number of lines or files impacted by current changes
- Battery
LP_COLOR_CHARGING_ABOVE
charging and above thresholdLP_COLOR_CHARGING_UNDER
charging but under thresholdLP_COLOR_DISCHARGING_ABOVE
discharging but above thresholdLP_COLOR_DISCHARGING_UNDER
discharging and under threshold
CHARACTERS
Special characters:
LP_MARK_BATTERY
(default: "⌁") in front of the battery chargeLP_MARK_ADAPTER
(default: "⏚") displayed when pluggedLP_MARK_LOAD
(default: "⌂") in front of the loadLP_MARK_PROXY
(default: "↥") indicate a proxy in useLP_MARK_HG
(default: "☿") prompt mark in hg repositoriesLP_MARK_SVN
(default: "‡") prompt mark in svn repositoriesLP_MARK_GIT
(default: "±") prompt mark in git repositoriesLP_MARK_FOSSIL
(default: "⌘") prompt mark in fossil repositoriesLP_MARK_UNTRACKED
(default: "*") if git has untracked filesLP_MARK_STASH
(default: "+") if git has stashed modificationsLP_MARK_BRACKET_OPEN
(default: "[") marks around the main part of the promptLP_MARK_BRACKET_CLOSE
(default: "]") marks around the main part of the promptLP_TITLE_OPEN
(default: "\e]0;") escape character opening a window's titleLP_TITLE_CLOSE
(default: "\a") escape character closing a window's titleLP_SCREEN_TITLE_OPEN
(default: "\033k") escape character opening screen window's titleLP_SCREEN_TITLE_CLOSE
(default: "\033\134") escape character closing screen window's title
KNOWN LIMITATIONS AND BUGS
Liquid prompt is distributed under the GNU Affero General Public License version 3.
- detached sessions only looks for
screen
, atmux
support would be nice… - Does not display the number of commits to be pushed in Mercurial repositories.
- Browsing into very large subversion repositories may dramatically slow down the display of the liquid prompt.
- Subversion repository cannot display commits to be pushed, this is a limitation of the Subversion versionning model.
- The proxy detection only uses the
$http_proxy
environment variable. - The window's title escape sequence may not work properly on some terminals (like xterm-256)