content/blog/2010/02/my-extravagant-zsh-prompt.markdown @ 3bd8a34568c3
Fix
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Fri, 07 Jun 2024 09:49:58 -0400 |
| parents | c499267711c3 |
| children | (none) |
( :title "My Extravagant Zsh Prompt" :snip "It’s big, but my monitor isn’t running out of ink." :date "2010-02-01T01:05:00Z" :draft nil ) I spend a lot of time in a Terminal window at a command line. Up until about a month ago I was using [bash][] for my shell. I decided to try switching to [Zsh][] after hearing a lot of good things about it and I'm very happy with the change. A few days ago I [tweeted][] my current Zsh prompt and the general response was: "Cool, but how did you do it?" I promised to write more about it when I got some free time, and it looks like that time is now. **One quick note:** This entry is about the prompt that *I* find useful. You are not me, so you'll almost certainly have different needs. That's great! Take this prompt and hack it to make whatever works for you. If you're feeling generous you should find me on [Twitter][twsl] and show me what you changed -- I might want to steal/appropriate your changes. **Another quick note:** I've customized the colors of my Terminal. They're based on the [Monokai][] TextMate theme, and I think they look very nice. The colors will be different for you. If you want colors like mine you should take a look at the [entry][candy] I wrote about it. [bash]: http://en.wikipedia.org/wiki/Bash [Zsh]: http://www.zsh.org/ [tweeted]: http://twitter.com/stevelosh/status/8259755151 [Monokai]: http://www.monokai.nl/blog/2006/07/15/textmate-color-theme/ [candy]: /blog/2009/03/candy-colored-terminal/ [twsl]: http://twitter.com/stevelosh/ <div id="toc"></div> Why Should You Care? -------------------- Many people use the command line every day and never bother to customize their prompts. It's just a bit of text that's printed before every command — why should you waste time learning how to customize it? I feel that the *most* important aspect of my command line work is the prompt. Your prompt is something you'll see *literally* thousands of times a day. Why not take 30 minutes and customize it into something that's much more useful? I firmly believe I'm right in thinking this way. 30 minutes (or even 3 hours) of customization to make your work easier for the **rest of your life** (or at least however long you stay with your current shell) *is* worth it. This Entry is About Zsh Prompts ------------------------------- As I mentioned earlier I now use Zsh as my command line shell. If you use bash (the default on most modern systems) the syntax to create the shell will be different. Really, though, you should give Zsh a try. Screenshots ----------- I can write all day, but in the end I think a screenshot will be more helpful than anything I write. Here's a sample of my current Zsh prompt:  And here's a version of that screenshot with some comments added to explain things:  If you want to know *how* I created that prompt, read on! Oh My Zsh! ---------- The first thing I'd do when starting out with Zsh is to install [robbyrussell's][robr] [oh-my-zsh][omz]. It's a great collection of very useful Zsh configurations and aliases which set some sane defaults and make working with Zsh much nicer. The instructions for installing it are on the project page. [robr]: http://github.com/robbyrussell [omz]: http://github.com/robbyrussell/oh-my-zsh Define a "Theme" ---------------- oh-my-zsh uses [theme files][themes] to specify how your prompt looks. An oh-my-zsh theme file is just a Zsh script which sets a few variables that the oh-my-zsh scripts use to render your prompt. Go ahead and create a new theme file for your prompt. Call it whatever you like. I called my theme "prose" because it's more verbose than the others. Copy the contents of one of the other themes to get started. The `PROMPT` variable is what you'll be modifying to change how your prompt looks. That's the `PROMPT=whatever` line of the theme file. Once you're done making your awesome prompt you should fork oh-my-zsh on GitHub and commit/push your new theme so other people can see and use your prompt. [themes]: http://github.com/robbyrussell/oh-my-zsh/tree/master/themes/ Username and Hostname --------------------- The first two pieces of my prompt are the simplest: username and hostname. I SSH between machines pretty frequently so I find it nice to have these in my prompt to remind me of where I am. These are things that you'll find in many, many Zsh prompts. For more information about this kind of stuff check out [this page][zshpr]. After adding in the colors this piece of my `PROMPT` variable looks like this: ```text %{$fg[magenta]%}%n%{$reset_color%} at %{$fg[yellow]%}%m%{$reset_color%} ``` [zshpr]: http://www.acm.uiuc.edu/workshops/zsh/prompt/escapes.html Current Directory ----------------- I like to have the current working directory displayed in my prompt. Zsh has two built-in ways to show the current directory: * **%d** shows the *entire* path. * **%~** shows the path with any variables replaced. Unfortunately neither of these work for me. If I'm in a directory that's under my home directory I want to see `~` instead of the full path. This would seem to mean that I should use `%~`, but there's a catch. The `%~` sequence also replaces any directories that happen to be environment variables. That means if I'm in something under my `virtualenvs` directory I'll see `~WORKON_HOME/venv_name` which is extremely ugly. To get around this I defined a simple function that implements the behavior I want. To add this to your prompt you'll first need to add the following function to your theme: ```bash function collapse_pwd { echo $(pwd | sed -e "s,^$HOME,~,") } ``` Then add `$(collapse_pwd)` to your `PROMPT` variable wherever you'd like the directory to show up. After adding in the colors this piece of my `PROMPT` variable looks like this: ```text in %{$fg_bold[green]%}$(collapse_pwd)%{$reset_color%} ``` **UPDATE:** In a comment Juliano pointed out a better way to do this. I've gotten rid of the `collapse_pwd` function and put this into my `PROMPT` variable instead: ```bash ${PWD/#$HOME/~} ``` My Right-Prompt: Battery Capacity --------------------------------- The next piece of my prompt I'll talk about is the most stand-alone one: the battery charge. I work exclusively on laptops. I don't own a desktop machine — I have a Macbook, Macbook Pro and Asus EEE PC and my work machine is a Macbook Pro. I work from coffeeshops and client meetings pretty often, so it's nice to have a reminder of my remaining battery power to know when I need to plug in. On the right-hand side of the prompt in the screenshot you can see a series of green triangles. These represent my current battery charge and they turn to empty triangles as the battery becomes depleted. Once the battery reaches 60% they turn yellow and once it reaches 40% they turn red. To do this I wrote a *very* simple Python script to output my current battery capacity. The entire script is shown below. ```python #!/usr/bin/env python # coding=UTF-8 import math, subprocess p = subprocess.Popen(["ioreg", "-rc", "AppleSmartBattery"], stdout=subprocess.PIPE) output = p.communicate()[0] o_max = [l for l in output.splitlines() if 'MaxCapacity' in l][0] o_cur = [l for l in output.splitlines() if 'CurrentCapacity' in l][0] b_max = float(o_max.rpartition('=')[-1].strip()) b_cur = float(o_cur.rpartition('=')[-1].strip()) charge = b_cur / b_max charge_threshold = int(math.ceil(10 * charge)) # Output total_slots, slots = 10, [] filled = int(math.ceil(charge_threshold * (total_slots / 10.0))) * u'▸' empty = (total_slots - len(filled)) * u'▹' out = (filled + empty).encode('utf-8') import sys color_green = '%{[32m%}' color_yellow = '%{[1;33m%}' color_red = '%{[31m%}' color_reset = '%{[00m%}' color_out = ( color_green if len(filled) > 6 else color_yellow if len(filled) > 4 else color_red ) out = color_out + out + color_reset sys.stdout.write(out) ``` **Note:** The `color_*` variables contain UTF-8 characters which don't show up in a normal web browser. They *should* be preserved when copying and pasting from a decent browser. If the colors don't work find me on [Twitter][twsl] and I'll put the raw script up somewhere so you can download it. **UPDATE:** [ehamberg][] [sent me][ehbtweet] the beginnings of a Linux-compatible battery capacity script. If you flesh it out and make it into a complete script please let me know and I'll add it here. [ehamberg]: http://twitter.com/ehamberg/ [ehbtweet]: http://twitter.com/ehamberg/status/8503213690 I've put this script in a file named `batcharge.py` in my `~/bin/` directory. You can of course name it and place it anything/anywhere you like. No, it's not perfect. No, I don't care. It gets the job done and any brainpower I could spend on making it more efficient could be better spent on writing or working on something else. If you want to improve it, feel free and *please* send me the link to your work on [Twitter][twsl] so I can use it! Now that you've got the script, it's time to add it to your prompt. If you want this to appear on the right-hand side of your screen (like mine does) you'll need to add two things to your theme file. The first is a function that calls the script: ```bash function battery_charge { echo `$BAT_CHARGE` 2>/dev/null } ``` After that you'll need to define the Zsh `RPROMPT` variable: ```bash RPROMPT='$(battery_charge)' ``` Once those are in your theme file any new Terminal windows you open should show the battery capacity to the right of your prompt! Repository Types ---------------- In my personal work and my full-time job I work with both [Mercurial][mercurial] and [git][] repositories. I find it helpful to have a visual reminder of what kind of repository I'm working in. To do this I've replaced the standard `$` character in my prompt with different Unicode characters depending on what kind of repository I'm currently in: * `○` means "I'm not in any repository." * `☿` means "I'm in a Mercurial repository." * `±` means "I'm in a git repository." Those particular characters are meant to reflect the logos of the various projects. You can of course change them to anything that makes sense to you. [mercurial]: http://mercurial-scm.org/ [git]: http://git-scm.com/ To add this feature to your prompt you'll need to do two things in your theme file. First, add the following function: ```bash function prompt_char { git branch >/dev/null 2>/dev/null && echo '±' && return hg root >/dev/null 2>/dev/null && echo '☿' && return echo '○' } ``` Then add `$(prompt_char)` somewhere inside your `PROMPT` variable — wherever you want the character to be displayed (probably at the end). Mercurial Repository Information -------------------------------- I use Mercurial at work and for my own personal projects and I find it very handy to have some information about the current repository right in my prompt. It keeps me "oriented," especially when I'm using [MQ][] and manipulating the state of a repo. [MQ]: http://mercurial.selenic.com/wiki/MqExtension In the past I toyed around with some shell scripts to do this but eventually I got fed up with the poor performance and horrible readability of that solution. To fix this I wrote a small Mercurial extension called [hg-prompt][]. It adds an `hg prompt` command to Mercurial that will let you output information about the current repository. It's designed especially for use in shell prompts (hence the name). I open sourced the code a while ago and since then a few people have made feature requests and/or contributed patches. It's grown into a nice, flexible little tool. You can check out the [documentation][hgpdoc] to see all the things it can do. [hg-prompt]: /projects/hg-prompt/ [hgpdoc]: https://sjl.bitbucket.io/hg-prompt/ I only use a few of the features myself: * The current repository branch. * The "dirty" state of the repo (whether there are untracked/uncommitted files). * Any tags pointing at the current revision. * An "update" character to show whether running `hg update` would do anything. * A list of MQ patches (if any are present). To put this into my prompt I've added a function to my theme: ```bash function hg_prompt_info { hg prompt --angle-brackets "\ < on <branch>>\ < at <tags|, >>\ <status|modified|unknown><update>< patches: <patches|join( → )>>" 2>/dev/null } ``` Inside my `PROMPT` variable I use `$(hg_prompt_info)` to show the information. The `2>/dev/null` makes sure no output is shown if I don't happen to be in a Mercurial repository. Of course this isn't nearly as pretty or readable without color. Unfortunately adding color codes makes the actual code almost unreadable: ```bash function hg_prompt_info { hg prompt --angle-brackets "\ < on %{$fg[magenta]%}<branch>%{$reset_color%}>\ < at %{$fg[yellow]%}<tags|%{$reset_color%}, %{$fg[yellow]%}>%{$reset_color%}>\ %{$fg[green]%}<status|modified|unknown><update>%{$reset_color%}< patches: <patches|join( → )|pre_applied(%{$fg[yellow]%})|post_applied(%{$reset_color%})|pre_unapplied(%{$fg_bold[black]%})|post_unapplied(%{$reset_color%})>>" 2>/dev/null } ``` **Small note:** My favorite part of this prompt is that applied MQ patches are orange while unapplied patches are grey. It makes it very obvious what's going on. Showing all the MQ patches isn't something that will work for everyone. If you work on repositories that ever have more than 5 or 6 patches at a time the output is going to be too overwhelming. There are some other MQ-related hg-prompt keywords that you might find useful though. Git Repository Information -------------------------- Unfortunately I can't *always* use Mercurial. Many projects that I contribute to use git. I could try to use the [hg-git][] extension to let me use Mercurial to work with them, but the extension just isn't fast or mature enough for my taste. I've ended up buckling down and jumping down the rabbit hole that is git's CLI. [hg-git]: http://hg-git.github.com/ Git doesn't seem to have any equivalent to hg-prompt, but I still wanted to have some information in my prompt so I don't get disoriented. oh-my-zsh has a bit of support for this, but it wasn't quite enough for me so I [hacked something together][omzgitcommit] to add the last bit of functionality I wanted. [omzgitcommit]: http://github.com/sjl/oh-my-zsh/commit/3d22ee248c6bce357c018a93d31f8d292d2cb4cd When I'm in a git repository my prompt now shows: * The current git branch. * Whether there are any changes in the index. * Whether there are any changes *not* in the index. Adding this to your prompt is very simple because oh-my-zsh has built-in support for it. All you need to do is define a few variables in your theme: ```bash ZSH_THEME_GIT_PROMPT_PREFIX=" on %{$fg[magenta]%}" ZSH_THEME_GIT_PROMPT_SUFFIX="%{$reset_color%}" ZSH_THEME_GIT_PROMPT_DIRTY="%{$fg[green]%}!" ZSH_THEME_GIT_PROMPT_UNTRACKED="%{$fg[green]%}?" ZSH_THEME_GIT_PROMPT_CLEAN="" ``` Once you do that you can put `$(git_prompt_info)` into your `PROMPT` variable to make it show up. **Note:** The `ZSH_THEME_GIT_PROMPT_UNTRACKED` variable is the part I added. If your want to use that one (to be able to see indexed and unindexed changes separately) you'll need to use [my fork of oh-my-zsh][omzfork]. [omzfork]: http://github.com/sjl/oh-my-zsh/ The Whole Thing --------------- Here's what my new "prose" theme file currently looks like in its entirety: ```bash function collapse_pwd { echo $(pwd | sed -e "s,^$HOME,~,") } function prompt_char { git branch >/dev/null 2>/dev/null && echo '±' && return hg root >/dev/null 2>/dev/null && echo '☿' && return echo '○' } function battery_charge { echo `$BAT_CHARGE` 2>/dev/null } function virtualenv_info { [ $VIRTUAL_ENV ] && echo '('`basename $VIRTUAL_ENV`') ' } function hg_prompt_info { hg prompt --angle-brackets "\ < on %{$fg[magenta]%}<branch>%{$reset_color%}>\ < at %{$fg[yellow]%}<tags|%{$reset_color%}, %{$fg[yellow]%}>%{$reset_color%}>\ %{$fg[green]%}<status|modified|unknown><update>%{$reset_color%}< patches: <patches|join( → )|pre_applied(%{$fg[yellow]%})|post_applied(%{$reset_color%})|pre_unapplied(%{$fg_bold[black]%})|post_unapplied(%{$reset_color%})>>" 2>/dev/null } PROMPT=' %{$fg[magenta]%}%n%{$reset_color%} at %{$fg[yellow]%}%m%{$reset_color%} in %{$fg_bold[green]%}$(collapse_pwd)%{$reset_color%}$(hg_prompt_info)$(git_prompt_info) $(virtualenv_info)$(prompt_char) ' RPROMPT='$(battery_charge)' ZSH_THEME_GIT_PROMPT_PREFIX=" on %{$fg[magenta]%}" ZSH_THEME_GIT_PROMPT_SUFFIX="%{$reset_color%}" ZSH_THEME_GIT_PROMPT_DIRTY="%{$fg[green]%}!" ZSH_THEME_GIT_PROMPT_UNTRACKED="%{$fg[green]%}?" ZSH_THEME_GIT_PROMPT_CLEAN="" ``` The file is also [on GitHub][prosetheme]. Remember, you'll need [my fork of oh-my-zsh][omzfork] to use the `ZSH_THEME_GIT_PROMPT_UNTRACKED` feature. [prosetheme]: http://github.com/sjl/oh-my-zsh/blob/master/themes/prose.zsh-theme A shell prompt is something that we'll each see thousands of times a day, so it's something that you should take the time to customize into a useful tool. Feel free to use my prompt as a starting point or just as a source of ideas. If you have any questions, suggestions, or examples of your own please fine me on [Twitter][twsl] — I'd love to hear them!