{"id":13484688,"url":"https://github.com/b-ryan/powerline-shell","last_synced_at":"2025-05-13T18:15:07.662Z","repository":{"id":4596451,"uuid":"5739134","full_name":"b-ryan/powerline-shell","owner":"b-ryan","description":"A beautiful and useful prompt for your shell","archived":false,"fork":false,"pushed_at":"2024-03-19T14:08:57.000Z","size":478,"stargazers_count":6266,"open_issues_count":133,"forks_count":740,"subscribers_count":149,"default_branch":"master","last_synced_at":"2025-05-04T09:02:05.013Z","etag":null,"topics":["bash","color-scheme","developer-tools","fish","powerline","python","shell","theme","zsh"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/b-ryan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-09-09T16:12:53.000Z","updated_at":"2025-05-03T05:28:16.000Z","dependencies_parsed_at":"2024-06-17T05:27:13.456Z","dependency_job_id":"8ac06829-b290-46fa-b1f6-d379e55007e4","html_url":"https://github.com/b-ryan/powerline-shell","commit_stats":{"total_commits":440,"total_committers":90,"mean_commits":4.888888888888889,"dds":0.725,"last_synced_commit":"4b19aa47f1a724c6b8d9713982045ceabfd507bc"},"previous_names":["banga/powerline-shell","milkbikis/powerline-shell"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b-ryan%2Fpowerline-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b-ryan%2Fpowerline-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b-ryan%2Fpowerline-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b-ryan%2Fpowerline-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/b-ryan","download_url":"https://codeload.github.com/b-ryan/powerline-shell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253465864,"owners_count":21913057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","color-scheme","developer-tools","fish","powerline","python","shell","theme","zsh"],"created_at":"2024-07-31T17:01:30.031Z","updated_at":"2025-05-13T18:15:07.630Z","avatar_url":"https://github.com/b-ryan.png","language":"Python","readme":"# A Powerline style prompt for your shell\n\nA beautiful and useful prompt generator for Bash, ZSH, Fish, and tcsh:\n\n![MacVim+Solarized+Powerline+CtrlP](https://raw.github.com/b-ryan/powerline-shell/master/bash-powerline-screenshot.png)\n\n- Shows some important details about the git/svn/hg/fossil branch (see below)\n- Changes color if the last command exited with a failure code\n- If you're too deep into a directory tree, shortens the displayed path with an ellipsis\n- Shows the current Python [virtualenv](http://www.virtualenv.org/) environment\n- It's easy to customize and extend. See below for details.\n\nThe generated prompts are designed to resemble\n[powerline](https://github.com/powerline/powerline), but otherwise this project\nhas no relation to powerline.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Version Control](#version-control)\n- [Setup](#setup)\n  - [Bash](#bash)\n  - [ZSH](#zsh)\n  - [Fish](#fish)\n  - [tcsh](#tcsh)\n- [Customization](#customization)\n  - [Config File](#config-file)\n  - [Adding, Removing and Re-arranging segments](#adding-removing-and-re-arranging-segments)\n  - [Generic Segments](#generic-segments)\n  - [Segment Separator](#segment-separator)\n  - [Themes](#themes)\n  - [Segment Configuration](#segment-configuration)\n  - [Contributing new types of segments](#contributing-new-types-of-segments)\n- [Troubleshooting](#troubleshooting)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Version Control\n\nAll of the version control systems supported by powerline shell give you a\nquick look into the state of your repo:\n\n- The current branch is displayed and changes background color when the\n  branch is dirty.\n- When the local branch differs from the remote, the difference in number\n  of commits is shown along with `⇡` or `⇣` indicating whether a git push\n  or pull is pending.\n\nIf files are modified or in conflict, the situation is summarized with the\nfollowing symbols:\n\n- `✎` -- a file has been modified (but not staged for commit, in git)\n- `✔` -- a file is staged for commit (git) or added for tracking\n- `✼` -- a file has conflicts\n- `?` -- a file is untracked\n\nEach of these will have a number next to it if more than one file matches.\n\nThe segment can start with a symbol representing the version control system in\nuse. To show that symbol, the configuration file must have a variable `vcs`\nwith an option `show_symbol` set to `true` (see\n[Segment Configuration](#segment-configuration)).\n\n## Setup\n\nThis script uses ANSI color codes to display colors in a terminal. These are\nnotoriously non-portable, so may not work for you out of the box, but try\nsetting your $TERM to `xterm-256color`.\n\n- Patch the font you use for your terminal: see\n  [powerline-fonts](https://github.com/Lokaltog/powerline-fonts)\n  - If you struggle too much to get working fonts in your terminal, you can use\n    \"compatible\" mode.\n  - If you're using old patched fonts, you have to use the older symbols.\n    Basically reverse [this\n    commit](https://github.com/milkbikis/powerline-shell/commit/2a84ecc) in\n    your copy.\n\n- Install using pip:\n\n```\npip install powerline-shell\n```\n\n(*You can use the\n[`--user`](https://pip.pypa.io/en/stable/user_guide/#user-installs) option to\ninstall for just your user, if you'd like. But you may need to fiddle with your\n`PATH` to get this working properly.*)\n\n- Or, install from the git repository:\n\n```\ngit clone https://github.com/b-ryan/powerline-shell\ncd powerline-shell\npython setup.py install\n```\n\n- Setup your shell prompt using the instructions for your shell below.\n\n### Bash\n\nAdd the following to your `.bashrc` file:\n\n```\nfunction _update_ps1() {\n    PS1=$(powerline-shell $?)\n}\n\nif [[ $TERM != linux \u0026\u0026 ! $PROMPT_COMMAND =~ _update_ps1 ]]; then\n    PROMPT_COMMAND=\"_update_ps1; $PROMPT_COMMAND\"\nfi\n```\n\n**Note:** On macOS, you must add this to one of `.bash_profile`, `.bash_login`,\nor `.profile`. macOS will execute the files in the aforementioned order and\nwill stop execution at the first file it finds. For more information on the\norder of precedence, see the section **INVOCATION** in `man bash`.\n\n### ZSH\n\nAdd the following to your `.zshrc`:\n\n```\nfunction powerline_precmd() {\n    PS1=\"$(powerline-shell --shell zsh $?)\"\n}\n\nfunction install_powerline_precmd() {\n  for s in \"${precmd_functions[@]}\"; do\n    if [ \"$s\" = \"powerline_precmd\" ]; then\n      return\n    fi\n  done\n  precmd_functions+=(powerline_precmd)\n}\n\nif [ \"$TERM\" != \"linux\" -a -x \"$(command -v powerline-shell)\" ]; then\n    install_powerline_precmd\nfi\n```\n\n### Fish\n\nRedefine `fish_prompt` in ~/.config/fish/config.fish:\n\n```\nfunction fish_prompt\n    powerline-shell --shell bare $status\nend\n```\n\n### tcsh\n\nAdd the following to your `.tcshrc`:\n\n```\nalias precmd 'set prompt=\"`powerline-shell --shell tcsh $?`\"'\n```\n\n## Customization\n\n### Config File\n\nPowerline-shell is customizable through the use of a config file. This file is\nexpected to be located at `~/.config/powerline-shell/config.json`. You can\ngenerate the default config at this location using:\n\n```\nmkdir -p ~/.config/powerline-shell \u0026\u0026 \\\npowerline-shell --generate-config \u003e ~/.config/powerline-shell/config.json\n```\n\n(As an example, my config file is located here:\n[here](https://github.com/b-ryan/dotfiles/blob/master/home/config/powerline-shell/config.json))\n\n### Adding, Removing and Re-arranging segments\n\nOnce you have generated your config file, you can now start adding or removing\n\"segments\" - the building blocks of your shell. The list of segments available\ncan be seen\n[here](https://github.com/b-ryan/powerline-shell/tree/master/powerline_shell/segments).\n\nYou can also create custom segments. Start by copying an existing segment like\n[this](https://github.com/b-ryan/powerline-shell/blob/master/powerline_shell/segments/aws_profile.py).\nMake sure to change any relative imports to absolute imports. Ie. change things\nlike:\n\n```python\nfrom ..utils import BasicSegment\n```\n\nto\n\n```python\nfrom powerline_shell.utils import BasicSegment\n```\n\nThen change the `add_to_powerline` function to do what you want. You can then\nuse this segment in your configuration by putting the path to your segment in\nthe segments section, like:\n\n```json\n\"segments\": [\n    \"~/path/to/segment.py\"\n]\n```\n\n### Generic Segments\n\nThere are two special segments available. `stdout` accepts an arbitrary command\nand the output of the command will be put into your prompt. `env` takes an\nenvironment variable and the value of the variable will be set in your prompt.\nFor example, your config could look like this:\n\n```\n{\n  \"segments\": [\n    \"cwd\",\n    \"git\",\n    {\n      \"type\": \"stdout\",\n      \"command\": [\"echo\", \"hi\"],\n      \"fg_color\": 22,\n      \"bg_color\": 161\n    },\n    {\n      \"type\": \"env\",\n      \"var\": \"DOCKER_MACHINE_NAME\"\n    },\n  ]\n}\n```\n\n### Segment Separator\n\nBy default, a unicode character (resembling the \u003e symbol) is used to separate\neach segment. This can be changed by changing the \"mode\" option in the config\nfile. The available modes are:\n\n- `patched` - The default.\n- `compatible` - Attempts to use characters that may already be available using\n  your chosen font.\n- `flat` - No separator is used between segments, giving each segment a\n  rectangular appearance (and also saves space).\n\n### Themes\n\nThe `powerline_shell/themes` directory stores themes for your prompt, which are\nbasically color values used by segments. The `default.py` defines a default\ntheme which can be used standalone, and every other theme falls back to it if\nthey miss colors for any segments.\n\nIf you want to create a custom theme, start by copying one of the existing\nthemes, like the\n[basic](https://github.com/b-ryan/powerline-shell/blob/master/powerline_shell/themes/basic.py).\nand update your `~/.config/powerline-shell/config.json`, setting the `\"theme\"`\nto the path of the file. For example your configuration might have:\n\n```\n  \"theme\": \"~/mythemes/my-great-theme.py\"\n```\n\nYou can then modify the color codes to your liking. Theme colors are specified\nusing [Xterm-256 color codes](https://jonasjacek.github.io/colors/).\n\nA script for testing color combinations is provided at `colortest.py`. Note\nthat the colors you see may vary depending on your terminal. When designing a\ntheme, please test your theme on multiple terminals, especially with default\nsettings.\n\n### Segment Configuration\n\nSome segments support additional configuration. The options for the segment are\nnested under the name of the segment itself. For example, all of the options\nfor the `cwd` segment are set in `~/.config/powerline-shell/config.json` like:\n\n```\n{\n    \"segments\": [...],\n    \"cwd\": {\n        options go here\n    }\n    \"theme\": \"theme-name\",\n    \"vcs\": {\n        options go here\n    }\n}\n```\n\nThe options for the `cwd` segment are:\n\n- `mode`: If `plain`, then simple text will be used to show the cwd. If\n  `dironly`, only the current directory will be shown. Otherwise expands the\n  cwd into individual directories.\n- `max_depth`: Maximum number of directories to show in path.\n- `max_dir_size`: Maximum number of characters displayed for each directory in\n  the path.\n- `full_cwd`: If true, the last directory will not be shortened when\n  `max_dir_size` is used.\n\nThe `hostname` segment provides one option:\n\n- `colorize`: If true, the hostname will be colorized based on a hash of\n  itself.\n\nThe `vcs` segment provides one option:\n\n- `show_symbol`: If `true`, the version control system segment will start with\n  a symbol representing the specific version control system in use in the\n  current directory.\n\nThe options for the `battery` segment are:\n\n- `always_show_percentage`: If true, show percentage when fully charged on AC.\n- `low_threshold`: Threshold percentage for low-battery indicator color.\n\nThe options for the `time` segment are:\n\n- `format`: Format string as used by strftime function, e.g. `%H:%M`.\n\n### Contributing new types of segments\n\nThe `powerline_shell/segments` directory contains python scripts which are\ninjected as is into a single file `powerline_shell_base.py`. Each segment\nscript defines a function that inserts one or more segments into the prompt. If\nyou want to add a new segment, simply create a new file in the segments\ndirectory.\n\nMake sure that your script does not introduce new globals which might conflict\nwith other scripts. Your script should fail silently and run quickly in any\nscenario.\n\nMake sure you introduce new default colors in `themes/default.py` for every new\nsegment you create. Test your segment with this theme first.\n\nYou should add tests for your segment as best you are able. Unit and\nintegration tests are both welcome. Run your tests by running the `test.sh`\nscript. It uses `docker` to manage dependencies and the environment.\nAlternatively, you can run the `nosetests` command after installing the\nrequirements in `requirements-dev.txt`.\n\n## Troubleshooting\n\nSee the [FAQ](https://github.com/b-ryan/powerline-shell/wiki/FAQ). If you\ncontinue to have issues, please open an\n[issue](https://github.com/b-ryan/powerline-shell/issues/new).\n","funding_links":[],"categories":["Python","Themes","Desktop App Development","bash","Packages","Shell"],"sub_categories":["ZSH on Windows","Python Toolkit","Zinit (née zplugin)","Prompts","PCAP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb-ryan%2Fpowerline-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fb-ryan%2Fpowerline-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb-ryan%2Fpowerline-shell/lists"}