Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 245 lines (189 sloc) 9.491 kb
36fd1c8 @nojhan color themes for VCS and battery marks
nojhan authored
1 Liquid prompt -- A useful adaptive prompt for Bash & Zsh
2 ========================================================
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
3
c3ba849 @ldidry Update README.md for zsh merge
ldidry authored
4 Liquid prompt is a smart prompt for the "Bourne-Again" Unix shell (bash) and for
5 Zsh.
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
6
7 The basic idea of the liquid prompt is to nicely display useful informations on
8 the shell prompt, only when they are needed. It adds carefuly chosen colors to
9 draw your attention on what differs from the normal context. Thus, you will
10 notice what changes, when it changes, because you do not become accommodated to
11 informations that are always displayed in the same way.
12
c3ba849 @ldidry Update README.md for zsh merge
ldidry authored
13 You can use it with either bash and zsh.
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
14
f1fd9af @nojhan update the readme
nojhan authored
15
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
16 ## FEATURES
17
18 If there is nothing special in the current context, the liquid prompt is close
19 to a default prompt:
20
21 `[user:~] $ `
22
23 If you have ran one command in background that is still running and that you are
e30b5fc @nojhan typofix: add comma between lines changed and pending commits
nojhan authored
24 in a git repository on a server, at branch "myb":
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
25
26 `1r [user@server:~/liquidprompt] myb ± `
27
28 A liquid prompt displaying everything may look like this:
29
991b2b3 @nojhan add configurable untracked changes mark, at a better position
nojhan authored
30 `⌁24% ⌂42% 3d/2&/1z [user@server:~/ … /code/liquidprompt]↥ master(+10/-5,3)* 125 ± `
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
31
32 It displays:
33
508b218 @nojhan Indicate if the battery is (dis)charging
nojhan authored
34 * a green ⌁ if the battery is charging and above a given threshold,
35 a yellow ⌁ if the battery is charging and under threshold,
36 a red ⌁ if the battery is discharging but above threshold;
37 * the average of the batteries remaining power, if it is under the given
38 threshold, with a colormap, going more and more red with decreasing power;
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
39 * the average of the processors load, if it is over a given limit, with a
3b1d492 @nojhan small typo on the source command
nojhan authored
40 colormap that became more and more noticeable with increasing load;
40e2db6 @nojhan use d/&/z instead of s/r/t for jobs markers
nojhan authored
41 * the number of detached sessions (`screen`), if there is any;
3b1d492 @nojhan small typo on the source command
nojhan authored
42 * the number of attached sleeping jobs (when you interrupt a command with Ctrl-Z
43 and bring it back with `fg`), if there is any;
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
44 * the number of attached running jobs (commands started with a `&`), if there is
45 any;
94133ad @nojhan different color if the user is not the login one
nojhan authored
46 * the current user, in bold yellow if it is root, in light white if it is not
47 the same as the login user;
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
48 * the current host, if you are connected via an SSH or telnet connection, with
49 different colors for each case;
c90f313 @nojhan add examples an explanations on how to make themes
nojhan authored
50 * a green colon if the user has write permissions on the current directory,
d95c9f5 @nojhan 80 columns justification
nojhan authored
51 a red one if he has not;
ee14581 @nojhan update the doc
nojhan authored
52 * the current directory in bold, shortened if it takes too much space, while
53 preserving the first two directories;
3ba404d @nojhan display an arrow if http_proxy is in use
nojhan authored
54 * an up arrow if an HTTP proxy is in use;
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
55 * the name of the current branch if you are in a version control repository
56 (git, mercurial or subversion), in green if everything is up to date, in red if
57 there is changes, in yellow if there is pending commits to push;
20d2e90 @nojhan show the number of added/deleted lines, if changes have been made in …
nojhan authored
58 * the number of added/deleted lines, if changes have been made and the number
59 of pending commits, if any;
991b2b3 @nojhan add configurable untracked changes mark, at a better position
nojhan authored
60 * a star if there is some untracked files in the repository;
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
61 * the error code of the last command, if it has failed in some way;
0943eb6 @nojhan Different prompt mark for different VCS (±, ☿, ‡)
nojhan authored
62 * a smart mark: ± for git directories, ☿ for mercurial, ‡ for svn, $ for simple
63 user, a red # for root.
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
64
bf46824 @nojhan You can temporarily deactivate the liquid prompt and come back to you…
nojhan authored
65 You can temporarily deactivate the liquid prompt and come back to your previous
74109a5 @nojhan prompt_OFF command to deactivate any prompt
nojhan authored
66 one by typing `prompt_off`. Use `prompt_on` to bring it back. You can deactivate
67 any prompt and use a single mark sign (`$ ` for user and `# ` for root) with the
68 `prompt_OFF` command.
bf46824 @nojhan You can temporarily deactivate the liquid prompt and come back to you…
nojhan authored
69
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
70
65b9e62 @nojhan update the doc about the configuration
nojhan authored
71 ## INSTALL
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
72
73 Include the file in your bash configuration, for example in your `.bashrc`:
74
c3ba849 @ldidry Update README.md for zsh merge
ldidry authored
75 `source liquidprompt`
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
76
65b9e62 @nojhan update the doc about the configuration
nojhan authored
77 Copy the `liquidpromptrc-dist` file in your home directory as
8f712bb try the XDG Base Directory Specification if the dotfile is not here
Thomas DEBESSE authored
78 `~/.config/liquidpromptrc` or `~/.liquidpromptrc` and edit it according to your
79 preferences. If you skip this step, the default behaviour will be used.
65b9e62 @nojhan update the doc about the configuration
nojhan authored
80
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
81
8fd5c95 @nojhan add dependencies list in the readme
nojhan authored
82 ## DEPENDENCIES
83
f1fd9af @nojhan update the readme
nojhan authored
84 Apart from obvious ones, some features depends on specific commands. If you do
85 not install them, the corresponding feature will not be available, but you will
86 see no error.
8fd5c95 @nojhan add dependencies list in the readme
nojhan authored
87
88 * battery status need `acpi`,
89 * detached sessions is looking for `screen`.
f1fd9af @nojhan update the readme
nojhan authored
90 * VCS support features needs… `git`, `hg` or `svn`, but you knew it.
8fd5c95 @nojhan add dependencies list in the readme
nojhan authored
91
92 For other features, the script uses commands that should be available on a large
93 variety of unixes: `tput`, `grep`, `awk`, `sed`, `ps`, `who`.
94
95
c90f313 @nojhan add examples an explanations on how to make themes
nojhan authored
96 ## FEATURES CONFIGURATION
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
97
65b9e62 @nojhan update the doc about the configuration
nojhan authored
98 You can configure some variables in the `~/.liquidpromptrc` file:
99
100 * `LP_BATTERY_THRESHOLD`, the maximal value under which the battery level is
101 displayed
102 * `LP_LOAD_THRESHOLD`, the minimal value after which the load average is
103 displayed
104 * `LP_PATH_LENGTH`, the maximum percentage of the screen width used to display
105 the path
106 * `LP_PATH_KEEP`, how many directories to keep at the beginning of a shortened
107 path
2c73402 @nojhan config option to always display the hostname
nojhan authored
108 * `LP_HOSTNAME_ALWAYS`, choose between always displaying the hostname or showing
109 it only when connected with a remote shell
39ba4c3 @nojhan Add conditionnal enabling for the battery meter
nojhan authored
110
111 You can also force some features to be disabled, to save some time in the prompt
112 building:
05fcbe9 @ldidry Allow to disable load, battery, etc. in the rc file
ldidry authored
113 * `LP_ENABLE_PERM`, if you want to detect if the directory is writable
114 * `LP_ENABLE_SHORTEN_PATH`, if you to shorten the path display
115 * `LP_ENABLE_PROXY`, if you want to detect if a proxy is used
116 * `LP_ENABLE_JOBS`, if you want to have jobs informations
117 * `LP_ENABLE_LOAD`, if you want to have load informations
118 * `LP_ENABLE_BATT`, if you want to have battery informations
119 * `LP_ENABLE_GIT`, if you want to have git informations
120 * `LP_ENABLE_SVN`, if you want to have subversion informations
121 * `LP_ENABLE_HG`, if you want to have mercurial informations
122
39ba4c3 @nojhan Add conditionnal enabling for the battery meter
nojhan authored
123 Note that if required commands are not installed, enabling the
124 corresponding feature will have no effect.
125 Note also that all the `LP_ENABLE_…` variables override the templates,
126 i.e. if you use `$LP_BATT` in your template and you set `LP_ENABLE_BATT=0`
127 in your config file, you will not have the battery informations.
65b9e62 @nojhan update the doc about the configuration
nojhan authored
128
c90f313 @nojhan add examples an explanations on how to make themes
nojhan authored
129
130 ## PUT THE PROMPT IN A DIFFERENT ORDER
131
132 You can sort what you want to see by sourcing your favorite template file
133 (`*.ps1`), after having sourced the liquid prompt.
134
135 Those scripts basically export the `LP_PS1` variable, by appending features and
136 theme colors.
137
138 Available features:
139 * `LP_BATT` battery
140 * `LP_LOAD` load
141 * `LP_JOBS` screen sessions/running jobs/suspended jobs
142 * `LP_USER` user
143 * `LP_HOST` hostname
144 * `LP_PERM` a colon ":"
145 * `LP_PWD` current working directory
146 * `LP_PROXY` HTTP proxy
147 * `LP_GIT` git
148 * `LP_HG` mercurial
149 * `LP_SVN` subversion
150 * `LP_ERR` last error code
151 * `LP_MARK` prompt mark
152
45bfd4d @nojhan add PS1 forging with liquidprompt function
nojhan authored
153 For example, if you just want to have a liquidprompt displaying the user and the
c90f313 @nojhan add examples an explanations on how to make themes
nojhan authored
154 host, with a normal full path in blue and only the git support:
45bfd4d @nojhan add PS1 forging with liquidprompt function
nojhan authored
155
7b8ba5e @nojhan fix #26 : prefix with _lp_ or LP_ and local variables
nojhan authored
156 export LP_PS1=`echo -ne "[\${LP_USER}\${LP_HOST}:\${BLUE}\$(pwd)\${NO_COL}] \${LP_GIT} \\\$ "`
45bfd4d @nojhan add PS1 forging with liquidprompt function
nojhan authored
157
158 Note that you need to properly escape dollars in a string that wil be
159 interpreted by bash at each prompt.
160
161 To erase your new formatting, just bring the `LP_PS1` to a null string:
162
163 export LP_PS1=""
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
164
165
a3be8d3 @nojhan More consistent special chars variable names
nojhan authored
166 ## THEMES
7b4c68f @nojhan Colors themes for most of the propmt parts
nojhan authored
167
a3be8d3 @nojhan More consistent special chars variable names
nojhan authored
168 You can change the colors and special characters of some part of the liquid
169 prompt by sourcing your favorite theme file (`*.theme`), before having sourced
170 the liquid prompt.
171
172
173 ### COLORS
7b4c68f @nojhan Colors themes for most of the propmt parts
nojhan authored
174
175 Available colors are:
660bc29 @nojhan add configurable colormaps
nojhan authored
176 BOLD, BLACK, BOLD_GRAY, WHITE, BOLD_WHITE,
177 GREEN, BOLD_GREEN, YELLOW, BOLD_YELLOW, BLUE, BOLD_BLUE, PINK, CYAN, BOLD_CYAN
178 RED, BOLD_RED, WARN_RED, CRIT_RED, DANGER_RED,
c90f313 @nojhan add examples an explanations on how to make themes
nojhan authored
179 NO_COL.
7b4c68f @nojhan Colors themes for most of the propmt parts
nojhan authored
180 Set to a null string "" if you do not want color.
181
182 * Current working directory
183 * `LP_COLOR_PATH` as normal user
184 * `LP_COLOR_PATH_ROOT` as root
185 * Color of the proxy mark
186 * `LP_COLOR_PROXY`
187 * Jobs count
188 * `LP_COLOR_JOB_D` Detached (aka screen sessions)
189 * `LP_COLOR_JOB_R` Running (xterm &)
190 * `LP_COLOR_JOB_Z` Sleeping (Ctrl-Z)
191 * Last error code
192 * `LP_COLOR_ERR`
193 * Prompt mark
194 * `LP_COLOR_MARK` as user
195 * `LP_COLOR_MARK_ROOT` as root
196 * Current user
197 * `LP_COLOR_USER_LOGGED` user who logged in
198 * `LP_COLOR_USER_ALT` user but not the one who logged in
199 * `LP_COLOR_USER_ROOT` root
200 * Hostname
201 * `LP_COLOR_HOST` local host
202 * `LP_COLOR_SSH` connected via SSH
203 * `LP_COLOR_TELNET` connected via telnet
204 * Separation mark (aka permiison in the working dir)
205 * `LP_COLOR_WRITE` have write permission
206 * `LP_COLOR_NOWRITE` do not have write permission
36fd1c8 @nojhan color themes for VCS and battery marks
nojhan authored
207 * VCS
208 * `LP_COLOR_UP` repository is up to date / a push have been made
209 * `LP_COLOR_COMMITS` some commits have not been pushed
210 * `LP_COLOR_CHANGES` there is some changes to commit
211 * `LP_COLOR_DIFF` number of lines impacted by current changes
212 * Battery
213 * `LP_COLOR_CHARGING_ABOVE` charging and above threshold
214 * `LP_COLOR_CHARGING_UNDER` charging but under threshold
215 * `LP_COLOR_DISCHARGING_ABOVE` discharging but above threshold
216 * `LP_COLOR_DISCHARGING_UNDER` discharging and under threshold
7b4c68f @nojhan Colors themes for most of the propmt parts
nojhan authored
217
218
a3be8d3 @nojhan More consistent special chars variable names
nojhan authored
219 ### CHARACTERS
220
221 Special characters:
222 * `LP_MARK_BATTERY` (default: "⌁") in front of the battery charge
223 * `LP_MARK_ADAPTER` (default: "⏚") displayed when plugged
224 * `LP_MARK_LOAD` (default: "⌂") in front of the load
225 * `LP_MARK_PROXY` (default: "↥") indicate a proxy in use
226 * `LP_MARK_HG` (default: "☿") prompt mark in hg repositories
227 * `LP_MARK_SVN` (default: "‡") prompt mark in svn repositories
228 * `LP_MARK_GIT` (default: "±") prompt mark in git repositories
229 * `LP_MARK_UNTRACKED` (default: "*") if git has untracked files
230
231
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
232 ## KNOWN LIMITATIONS AND BUGS
233
bfd9e5c @nojhan + license in the readme
nojhan authored
234 Liquid prompt is distributed under the GNU Affero General Public License
235 version 3.
236
40e2db6 @nojhan use d/&/z instead of s/r/t for jobs markers
nojhan authored
237 * detached sessions only looks for `screen`, a `tmux` support would be nice…
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
238 * Does not display the number of commits to be pushed in Mercurial repositories.
f1fd9af @nojhan update the readme
nojhan authored
239 * Browsing into very large subversion repositories may dramatically slow down
240 the display of the liquid prompt.
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
241 * Subversion repository cannot display commits to be pushed, this is a
242 limitation of the Subversion versionning model.
3ba404d @nojhan display an arrow if http_proxy is in use
nojhan authored
243 * The proxy detection only uses the `$http_proxy` environment variable.
c13e6d7 @nojhan explanations about liquidprompt
nojhan authored
244
Something went wrong with that request. Please try again.