Home

Awesome

A Powerline style prompt for your shell

A beautiful and useful prompt generator for Bash, ZSH, Fish, and tcsh:

MacVim+Solarized+Powerline+CtrlP

The generated prompts are designed to resemble powerline, but otherwise this project has no relation to powerline.

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents generated with DocToc

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Version Control

All of the version control systems supported by powerline shell give you a quick look into the state of your repo:

If files are modified or in conflict, the situation is summarized with the following symbols:

Each of these will have a number next to it if more than one file matches.

The segment can start with a symbol representing the version control system in use. To show that symbol, the configuration file must have a variable vcs with an option show_symbol set to true (see Segment Configuration).

Setup

This script uses ANSI color codes to display colors in a terminal. These are notoriously non-portable, so may not work for you out of the box, but try setting your $TERM to xterm-256color.

pip install powerline-shell

(You can use the --user option to install for just your user, if you'd like. But you may need to fiddle with your PATH to get this working properly.)

git clone https://github.com/b-ryan/powerline-shell
cd powerline-shell
python setup.py install

Bash

Add the following to your .bashrc file:

function _update_ps1() {
    PS1=$(powerline-shell $?)
}

if [[ $TERM != linux && ! $PROMPT_COMMAND =~ _update_ps1 ]]; then
    PROMPT_COMMAND="_update_ps1; $PROMPT_COMMAND"
fi

Note: On macOS, you must add this to one of .bash_profile, .bash_login, or .profile. macOS will execute the files in the aforementioned order and will stop execution at the first file it finds. For more information on the order of precedence, see the section INVOCATION in man bash.

ZSH

Add the following to your .zshrc:

function powerline_precmd() {
    PS1="$(powerline-shell --shell zsh $?)"
}

function install_powerline_precmd() {
  for s in "${precmd_functions[@]}"; do
    if [ "$s" = "powerline_precmd" ]; then
      return
    fi
  done
  precmd_functions+=(powerline_precmd)
}

if [ "$TERM" != "linux" -a -x "$(command -v powerline-shell)" ]; then
    install_powerline_precmd
fi

Fish

Redefine fish_prompt in ~/.config/fish/config.fish:

function fish_prompt
    powerline-shell --shell bare $status
end

tcsh

Add the following to your .tcshrc:

alias precmd 'set prompt="`powerline-shell --shell tcsh $?`"'

Customization

Config File

Powerline-shell is customizable through the use of a config file. This file is expected to be located at ~/.config/powerline-shell/config.json. You can generate the default config at this location using:

mkdir -p ~/.config/powerline-shell && \
powerline-shell --generate-config > ~/.config/powerline-shell/config.json

(As an example, my config file is located here: here)

Adding, Removing and Re-arranging segments

Once you have generated your config file, you can now start adding or removing "segments" - the building blocks of your shell. The list of segments available can be seen here.

You can also create custom segments. Start by copying an existing segment like this. Make sure to change any relative imports to absolute imports. Ie. change things like:

from ..utils import BasicSegment

to

from powerline_shell.utils import BasicSegment

Then change the add_to_powerline function to do what you want. You can then use this segment in your configuration by putting the path to your segment in the segments section, like:

"segments": [
    "~/path/to/segment.py"
]

Generic Segments

There are two special segments available. stdout accepts an arbitrary command and the output of the command will be put into your prompt. env takes an environment variable and the value of the variable will be set in your prompt. For example, your config could look like this:

{
  "segments": [
    "cwd",
    "git",
    {
      "type": "stdout",
      "command": ["echo", "hi"],
      "fg_color": 22,
      "bg_color": 161
    },
    {
      "type": "env",
      "var": "DOCKER_MACHINE_NAME"
    },
  ]
}

Segment Separator

By default, a unicode character (resembling the > symbol) is used to separate each segment. This can be changed by changing the "mode" option in the config file. The available modes are:

Themes

The powerline_shell/themes directory stores themes for your prompt, which are basically color values used by segments. The default.py defines a default theme which can be used standalone, and every other theme falls back to it if they miss colors for any segments.

If you want to create a custom theme, start by copying one of the existing themes, like the basic. and update your ~/.config/powerline-shell/config.json, setting the "theme" to the path of the file. For example your configuration might have:

  "theme": "~/mythemes/my-great-theme.py"

You can then modify the color codes to your liking. Theme colors are specified using Xterm-256 color codes.

A script for testing color combinations is provided at colortest.py. Note that the colors you see may vary depending on your terminal. When designing a theme, please test your theme on multiple terminals, especially with default settings.

Segment Configuration

Some segments support additional configuration. The options for the segment are nested under the name of the segment itself. For example, all of the options for the cwd segment are set in ~/.config/powerline-shell/config.json like:

{
    "segments": [...],
    "cwd": {
        options go here
    }
    "theme": "theme-name",
    "vcs": {
        options go here
    }
}

The options for the cwd segment are:

The hostname segment provides one option:

The vcs segment provides one option:

The options for the battery segment are:

The options for the time segment are:

Contributing new types of segments

The powerline_shell/segments directory contains python scripts which are injected as is into a single file powerline_shell_base.py. Each segment script defines a function that inserts one or more segments into the prompt. If you want to add a new segment, simply create a new file in the segments directory.

Make sure that your script does not introduce new globals which might conflict with other scripts. Your script should fail silently and run quickly in any scenario.

Make sure you introduce new default colors in themes/default.py for every new segment you create. Test your segment with this theme first.

You should add tests for your segment as best you are able. Unit and integration tests are both welcome. Run your tests by running the test.sh script. It uses docker to manage dependencies and the environment. Alternatively, you can run the nosetests command after installing the requirements in requirements-dev.txt.

Troubleshooting

See the FAQ. If you continue to have issues, please open an issue.