Repository files navigation

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

• Shows some important details about the git/svn/hg/fossil branch (see below)
• Changes color if the last command exited with a failure code
• If you're too deep into a directory tree, shortens the displayed path with an ellipsis
• Shows the current Pythonvirtualenv environment
• It's easy to customize and extend. See below for details.

The generated prompts are designed to resemblepowerline, but otherwise this projecthas no relation to powerline.

Table of Contentsgenerated withDocToc

• Version Control
• Setup
  • Bash
  • ZSH
  • Fish
  • tcsh
• Customization
  • Config File
  • Adding, Removing and Re-arranging segments
  • Generic Segments
  • Segment Separator
  • Themes
  • Segment Configuration
  • Contributing new types of segments
• Troubleshooting

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

• The current branch is displayed and changes background color when thebranch is dirty.
• When the local branch differs from the remote, the difference in numberof commits is shown along with⇡ or⇣ indicating whether a git pushor pull is pending.

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

• ✎ -- a file has been modified (but not staged for commit, in git)
• ✔ -- a file is staged for commit (git) or added for tracking
• ✼ -- a file has conflicts
• ? -- a file is untracked

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 inuse. To show that symbol, the configuration file must have a variablevcswith an optionshow_symbol set totrue (seeSegment Configuration).

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

• Patch the font you use for your terminal: seepowerline-fonts

  • If you struggle too much to get working fonts in your terminal, you can use"compatible" mode.
  • If you're using old patched fonts, you have to use the older symbols.Basically reversethiscommit inyour copy.

• Install using pip:

pip install powerline-shell

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

• Or, install from the git repository:

git clone https://github.com/b-ryan/powerline-shellcd powerline-shellpython setup.py install

• Setup your shell prompt using the instructions for your shell below.

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 andwill stop execution at the first file it finds. For more information on theorder of precedence, see the sectionINVOCATION inman bash.

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_precmdfi

Redefinefish_prompt in ~/.config/fish/config.fish:

function fish_prompt    powerline-shell --shell bare $statusend

Add the following to your.tcshrc:

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

Powerline-shell is customizable through the use of a config file. This file isexpected to be located at~/.config/powerline-shell/config.json. You cangenerate 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)

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 availablecan be seenhere.

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

from ..utilsimportBasicSegment

to

frompowerline_shell.utilsimportBasicSegment

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

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

There are two special segments available.stdout accepts an arbitrary commandand the output of the command will be put into your prompt.env takes anenvironment 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"    },  ]}

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

• patched - The default.
• compatible - Attempts to use characters that may already be available usingyour chosen font.
• flat - No separator is used between segments, giving each segment arectangular appearance (and also saves space).

Thepowerline_shell/themes directory stores themes for your prompt, which arebasically color values used by segments. Thedefault.py defines a defaulttheme which can be used standalone, and every other theme falls back to it ifthey miss colors for any segments.

If you want to create a custom theme, start by copying one of the existingthemes, like thebasic.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 specifiedusingXterm-256 color codes.

A script for testing color combinations is provided atcolortest.py. Notethat the colors you see may vary depending on your terminal. When designing atheme, please test your theme on multiple terminals, especially with defaultsettings.

Some segments support additional configuration. The options for the segment arenested under the name of the segment itself. For example, all of the optionsfor thecwd 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 thecwd segment are:

• mode: Ifplain, then simple text will be used to show the cwd. Ifdironly, only the current directory will be shown. Otherwise expands thecwd into individual directories.
• max_depth: Maximum number of directories to show in path.
• max_dir_size: Maximum number of characters displayed for each directory inthe path.
• full_cwd: If true, the last directory will not be shortened whenmax_dir_size is used.

Thehostname segment provides one option:

• colorize: If true, the hostname will be colorized based on a hash ofitself.

Thevcs segment provides one option:

• show_symbol: Iftrue, the version control system segment will start witha symbol representing the specific version control system in use in thecurrent directory.

The options for thebattery segment are:

• always_show_percentage: If true, show percentage when fully charged on AC.
• low_threshold: Threshold percentage for low-battery indicator color.

The options for thetime segment are:

• format: Format string as used by strftime function, e.g.%H:%M.

Thepowerline_shell/segments directory contains python scripts which areinjected as is into a single filepowerline_shell_base.py. Each segmentscript defines a function that inserts one or more segments into the prompt. Ifyou want to add a new segment, simply create a new file in the segmentsdirectory.

Make sure that your script does not introduce new globals which might conflictwith other scripts. Your script should fail silently and run quickly in anyscenario.

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

You should add tests for your segment as best you are able. Unit andintegration tests are both welcome. Run your tests by running thetest.shscript. It usesdocker to manage dependencies and the environment.Alternatively, you can run thenosetests command after installing therequirements inrequirements-dev.txt.

See theFAQ. If youcontinue to have issues, please open anissue.