diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 315 |
1 files changed, 266 insertions, 49 deletions
@@ -1,13 +1,58 @@ -## powerlevel9k Theme for Oh-My-Zsh +## powerlevel9k Theme for ZSH -This is a theme for [Oh-My-Zsh](https://github.com/robbyrussell/oh-my-zsh). This -theme uses [Powerline Fonts](https://github.com/Lokaltog/powerline-fonts), thus -giving you the most epic terminal styling in the universe. +Powerlevel9k is a theme for ZSH which uses [Powerline +Fonts](https://github.com/Lokaltog/powerline-fonts), thus giving you the most +epic terminal styling in the universe. Look like a bad-ass. Impress everyone in 'Screenshot Your Desktop' threads. Use powerlevel9k. +Powerlevel9k can be used with vanilla ZSH, +[Oh-My-Zsh](https://github.com/robbyrussell/oh-my-zsh), or +[Prezto](https://github.com/sorin-ionescu/prezto), and can also be installed +using [antigen](https://github.com/zsh-users/antigen). + + In addition to looking amazing, this theme actually provides a lot of useful -information in configurable prompt segments. +information in configurable prompt segments. Here is an example of what it looks +like with a normal installation and default settings: + + + +<!-- 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](https://github.com/thlorenz/doctoc)* + +- [Features](#features) +- [Installation](#installation) + - [Step 1: Install Powerlevel9k](#step-1-install-powerlevel9k) + - [Option 1: Install for Vanilla ZSH](#option-1-install-for-vanilla-zsh) + - [Option 2: Install for Oh-My-ZSH](#option-2-install-for-oh-my-zsh) + - [Option 3: Install for Prezto](#option-3-install-for-prezto) + - [Option 4: Install for antigen](#option-4-install-for-antigen) + - [Step 2: Install Powerline Fonts](#step-2-install-powerline-fonts) + - [Option 1: Install Powerline Fonts](#option-1-install-powerline-fonts) + - [Option 2: Install Awesome Powerline Fonts](#option-2-install-awesome-powerline-fonts) + - [Option 3: Compatible Mode](#option-3-compatible-mode) +- [Segment Customization](#segment-customization) + - [The AWS Profile Segment](#the-aws-profile-segment) + - [The 'context' Segment](#the-context-segment) + - [The 'dir' segment](#the-dir-segment) + - [The 'time' segment](#the-time-segment) + - [Unit Test Ratios](#unit-test-ratios) + - [The 'vcs' Segment](#the-vcs-segment) + - [Symbols](#symbols) +- [Styling](#styling) + - [Double-Lined Prompt](#double-lined-prompt) + - [Light Color Theme](#light-color-theme) + - [Further color customizations](#further-color-customizations) +- [Troubleshooting](#troubleshooting) + - [Gaps Between Segments](#gaps-between-segments) +- [Meta](#meta) + - [Kudos](#kudos) + - [Developing](#developing) + - [Contributions / Bugs / Contact](#contributions--bugs--contact) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> ### Features @@ -21,7 +66,7 @@ information in configurable prompt segments. * various working tree statuses (e.g., unstaged, staged, etc.,) * Shows return-code of the last command if it is an error code * Indicates background jobs with a gear icon -* Can conditionally display the `user@host` string when needed +* Can conditionally display the `user@host` string when needed (e.g., SSH) * Provides segment for command history (so you can `$ !<num>` to re-run) * Plenty of additional segments to choose from (e.g., AWS, ruby) * Can be used as a single or double-lined prompt (see screenshots below) @@ -31,35 +76,44 @@ information in configurable prompt segments. doesn't require Powerline fonts, check out the sister font, [hackersaurus](https://github.com/bhilburn/hackersaurus).** -Here are some screenshots of `powerlevel9k` with default settings: +Here is a detailed screenshot showing `powerlevel9k` with default settings and +varying terminal status indicators:  - +### Installation +There are two steps to start using this theme: +1. Install the Powerlevel9k theme. +2. Install Powerline-patched fonts. +3. [Optional] Configuration -### Installation +To get the most out of Powerlevel9k, you need to install both the theme as well +as Powerline-patched fonts, if you don't have them installed already. If you +cannot install Powerline-patched fonts for some reason, follow the instructions +below for a `compatible` install. -There are two things you need to make this theme work correctly: Powerline -fonts, and the theme itself. +No configuration is necessary post-installation if you like the default +settings, but there is plenty of segment configuration available if you are +interested. -#### Install Powerline Fonts -First, you need to install Powerline Fonts. You can find the [installation -instructions -here](https://powerline.readthedocs.org/en/latest/installation/linux.html#fonts-installation). -You can also find the raw font files [in this Github -repository](https://github.com/powerline/fonts) if you want to manually install -them for your OS. +#### Step 1: Install Powerlevel9k +There are four ways to install and use the Powerlevel9k theme: vanilla ZSH, +Oh-My-Zsh, Prezto, and antigen. Do one of the following: -After you have installed Powerline fonts, make the default font in your terminal -emulator the Powerline font you want to use. +##### Option 1: Install for Vanilla ZSH + +If you use just a vanilla ZSH install, simply clone this repository and +reference it in your `~/.zshrc`: -#### Install Powerlevel9k + $ git clone https://github.com/bhilburn/powerlevel9k.git + $ echo 'source powerlevel9k/powerlevel9k.zsh-theme' >> ~/.zshrc -##### Within Oh-my-ZSH +##### Option 2: Install for Oh-My-ZSH -To install this theme, clone this repository into your [Oh-my-Zsh](https://github.com/robbyrussell/oh-my-zsh) `custom/themes` -directory. +To install this theme for +[Oh-My-Zsh](https://github.com/robbyrussell/oh-my-zsh), clone this repository +into your OMZ `custom/themes` directory. $ cd ~/.oh-my-zsh/custom $ git clone https://github.com/bhilburn/powerlevel9k.git themes/powerlevel9k @@ -68,10 +122,10 @@ You then need to select this theme in your `~/.zshrc`: ZSH_THEME="powerlevel9k/powerlevel9k" -##### With Prezto +##### Option 3: Install for Prezto -To install this theme, clone this repository into your [Prezto](https://github.com/sorin-ionescu/prezto) `prompt/external` -directory. +To install this theme for use in Prezto, clone this repository into your +[Prezto](https://github.com/sorin-ionescu/prezto) `prompt/external` directory. $ cd ~.zprezto/modules/prompt/external $ git clone https://github.com/bhilburn/powerlevel9k.git @@ -81,6 +135,86 @@ You then need to select this theme in your `~/.zpreztorc`: zstyle ':prezto:module:prompt' theme 'powerlevel9k' +##### Option 4: Install for antigen + +If you prefer [antigen](https://github.com/zsh-users/antigen), just add this +theme to the antigen config in your `~/.zshrc`: + + $ echo 'antigen theme bhilburn/powerlevel9k powerlevel9k' >> ~/.zshrc + $ echo 'antigen apply' >> ~/.zshrc + +Note that you should define any customizations before calling `antigen theme` +(i.e. setting the `POWERLEVEL9K_*` variables) in your `.zshrc`. + +#### Step 2: Install Powerline Fonts +Technically, you don't *have* to install Powerline fonts. If you are using +a font that has some of the basic glyphs we need, you can use the theme in +`compatible` mode - see the third option, below. + +To get the most out of theme, though, you'll want Powerline-patched fonts. There +are two varieties of these: 'Powerline Fonts' and 'Awesome Powerline +Fonts'. The latter includes additional glyphs that aren't required for a normal +install. + +Do one of the following: + +##### Option 1: Install Powerline Fonts + +You can find the [installation instructions for Powerline Fonts here] +(https://powerline.readthedocs.org/en/latest/installation/linux.html#fonts-installation). +You can also find the raw font files [in this Github +repository](https://github.com/powerline/fonts) if you want to manually install +them for your OS. + +After you have installed Powerline fonts, make the default font in your terminal +emulator the Powerline font you want to use. + +This is the default mode for `Powerlevel9k`, and no further configuration is +necessary. + +**N.B.:** If Powerlevel9k is not working properly, it is almost always the case +that the fonts were not properly installed, or you have not configured your +terminal to use a Powerline-patched font! + +##### Option 2: Install Awesome Powerline Fonts + +Alternatively, you can install [Awesome Powerline +Fonts](https://github.com/gabrielelana/awesome-terminal-fonts), which provide +a number of additional glyphs. + +You then need to indicate that you wish to use the additional glyphs by defining +the following in your `~/.zshrc`: + + POWERLEVEL9K_MODE='awesome-patched' + +If you choose to make use of this, your prompt will look something like this: + + + +Note that if you prefer flat segment transitions, you can use the following with +`Awesome Powerline Fonts` installed: + + POWERLEVEL9K_MODE='flat' + +Which looks like this: + + + +##### Option 3: Compatible Mode + +This option is best if you prefer not to install additional fonts. This option +will work out-of-the-box if your your terminal font supports the segment +separator characters `\uE0B0` (left segment separator) and `\uE0B2` (right +segment separator). + +All you need to do to in this case is install the `Powerlevel9k` theme itself, +as explained above, and then define the following in your `~/.zshrc`: + + POWERLEVEL9K_MODE='compatible' + +Note that depending on your terminal font, this may still not render +appropriately. This configuration should be used as a back-up. + ### Segment Customization Customizing your prompt is easy! Select the segments you want to have displayed, @@ -91,10 +225,12 @@ currently available are: * **context** - Your username and host (more info below) * **dir** - Your current working directory. * **history** - The command number for the current line. +* **node_version** - Show the version number of the installed Node.js. * **rbenv** - Ruby environment information (if one is active). * **rspec_stats** - Show a ratio of test classes vs code classes for RSpec. * **status** - The return code of the previous command, and status of background jobs. * **symfony2_tests** - Show a ratio of test classes vs code classes for Symfony2. +* **symfony2_version** - Show the current Symfony2 version, if you are in a Symfony2-Project dir. * **time** - System time. * **virtualenv** - Your Python [VirtualEnv](https://virtualenv.pypa.io/en/latest/). * **vcs** - Information about this `git` or `hg` repository (if you are in one). @@ -125,13 +261,13 @@ elements (it is by default), and define a `DEFAULT_USER` in your `~/.zshrc`: export DEFAULT_USER=<your username> -#### Test ratio +#### The 'dir' segment + +The `dir` segment shows the current working directory. You can limit the output +to a certain length: -The `symfony2_tests` and `rspec_tests` segments show both a ratio of "real" classes -vs test classes. This is just a very simple ratio, and does not show your code -coverage or any sophisticated stats. All this does is just to count your files -and test files and calculate the ratio between them. Not more, but is may give -a quick overview about the test situation of the project you are dealing with. + # Limit to the last two folders + POWERLEVEL9K_SHORTEN_DIR_LENGTH=2 #### The 'time' segment @@ -141,32 +277,54 @@ just set another format in your `~/.zshrc`: # Reversed time format POWERLEVEL9K_TIME_FORMAT='%D{%S:%M:%H}' +#### Unit Test Ratios + +The `symfony2_tests` and `rspec_tests` segments both show a ratio of "real" +classes vs test classes in your source code. This is just a very simple ratio, +and does not show your code coverage or any sophisticated stats. All this does +is count your source files and test files, and calculate the ratio between them. +Just enough to give you a quick overview about the test situation of the project +you are dealing with. + #### The 'vcs' Segment By default, the `vcs` segment will provide quite a bit of information. If you would also like for it to display the current hash / changeset, simply define `POWERLEVEL9K_SHOW_CHANGESET` in your `~/.zshrc`. If activated, it will show the first 12 characters of the changeset id. To change the amount of characters, -set `POWERLEVEL9K_CHANGESET_HASH_LENTH` to any value you want. -Example: +set `POWERLEVEL9K_CHANGESET_HASH_LENGTH` to any value you want. # enable the vcs segment in general POWERLEVEL9K_SHOW_CHANGESET=true # just show the 6 first characters of changeset POWERLEVEL9K_CHANGESET_HASH_LENGTH=6 -##### Symbols +You can also disable the branch icon in your prompt by setting +`POWERLEVEL9K_HIDE_BRANCH_ICON` to `true`: + + # Hide the branch icon + POWERLEVEL9K_HIDE_BRANCH_ICON=true -The `vcs` segment uses various symbols to tell you the state of your repository: +##### Symbols -* `↑4` - The number of commits your repository is ahead of your remote branch -* `↓5` - The number of commits your repository is behind of your remote branch -* `⍟3` - The number of stashes, here 3. -* `●` - There are unstaged changes in your working copy -* `✚` - There are staged changes in your working copy -* `?` - There are files in your working copy, that are unknown to your repository -* `→` - The name of your branch differs from its tracking branch. -* `☿` - A mercurial bookmark is active. +The `vcs` segment uses various symbols to tell you the state of your repository. +These symbols depend on your installed font and selected `POWERLEVEL9K_MODE` +from the [Installation](#Installation) section above. + +| `Compatible` | `Powerline` | `Awesome Powerline` | Explanation +|--------------|---------------------|-------------------|-------------------------- +| `↑4` | `↑4` | 4 | Number of commits your repository is ahead of your remote branch +| `↓5` | `↓5` | 5 | Number of commits your repository is behind of your remote branch +| `⍟3` | `⍟3` | 3 | Number of stashes, here 3. +| `●` | `●` |  | There are unstaged changes in your working copy +| `✚` | `✚` |  | There are staged changes in your working copy +| `?` | `?` |  | There are files in your working copy, that are unknown to your repository +| `→` | `→` |  | The name of your branch differs from its tracking branch. +| `☿` | `☿` |  | A mercurial bookmark is active. +| `@` |  |  | Branch Icon +| None | None | 2c3705 | The current commit hash. Here "2c3705" +| None | None |  | Repository is a git repository +| None | None |  | Repository is a Mercurial repository ### Styling @@ -197,6 +355,54 @@ Light'](https://github.com/altercation/solarized) users. Check it out:  +#### Further color customizations + +For each segment in your prompt, you can specify a foreground and background +color by setting them in your `~/.zshrc`. For example, to change the appearance +of the `time` segment, you would use: + + POWERLEVEL9K_TIME_FOREGROUND='red' + POWERLEVEL9K_TIME_BACKGROUND='blue' + +Use the segment names from the above section `Segment Customization`. Some of +the Segments have special color variables, as they change the colors according +to some internal rules. These Segments are `vcs`, `rspec_stats`, `symfony2_tests`: + + # General VCS color segments: + POWERLEVEL9K_VCS_FOREGROUND='blue' + POWERLEVEL9K_VCS_DARK_FOREGROUND='black' + POWERLEVEL9K_VCS_BACKGROUND='green' + # If VCS changes are detected: + POWERLEVEL9K_VCS_MODIFIED_FOREGROUND='red' + POWERLEVEL9K_VCS_MODIFIED_BACKGROUND='cyan' + + # rspec_stats for good test coverage + POWERLEVEL9K_RSPEC_STATS_GOOD_FOREGROUND='blue' + POWERLEVEL9K_RSPEC_STATS_GOOD_BACKGROUND='green' + # rspec_stats for average test coverage + POWERLEVEL9K_RSPEC_STATS_AVG_FOREGROUND='black' + POWERLEVEL9K_RSPEC_STATS_AVG_BACKGROUND='cyan' + # rspec_stats for poor test coverage + POWERLEVEL9K_RSPEC_STATS_BAD_FOREGROUND='red' + POWERLEVEL9K_RSPEC_STATS_BAD_BACKGROUND='white' + + # symfony2_tests for good test coverage + POWERLEVEL9K_SYMFONY2_TESTS_GOOD_FOREGROUND='blue' + POWERLEVEL9K_SYMFONY2_TESTS_GOOD_BACKGROUND='green' + # symfony2_tests for average test coverage + POWERLEVEL9K_SYMFONY2_TESTS_AVG_FOREGROUND='black' + POWERLEVEL9K_SYMFONY2_TESTS_AVG_BACKGROUND='cyan' + # symfony2_tests for poor test coverage + POWERLEVEL9K_SYMFONY2_TESTS_BAD_FOREGROUND='red' + POWERLEVEL9K_SYMFONY2_TESTS_BAD_BACKGROUND='white' + +You could also use a colorcode value. Example: + + POWERLEVEL9K_VCS_FOREGROUND='021' # Dark blue + +For a full list of supported colors, run the `spectrum_ls` program in your +terminal. + ### Troubleshooting Here are some fixes to some common problems. @@ -211,14 +417,25 @@ Thankfully, this is easy to fix. This happens if you have successfully installed Powerline fonts, but did not make a Powerline font the default font in your terminal emulator (e.g., 'terminator', 'gnome-terminal', 'konsole', etc.,). -### Contributions / Bugs / Contact +### Meta + +#### Kudos + +This theme wouldn't have happened without inspiration from the original [agnoster](https://gist.github.com/agnoster/3712874) Oh-My-ZSH theme. + +Before creating this theme, I also tried [jeremyFreeAgent's theme](https://github.com/jeremyFreeAgent/oh-my-zsh-powerline-theme) and [maverick2000's theme, ZSH2000](https://github.com/maverick2000/zsh2000). + +#### Developing + +Documentation for developers is kept on the [Powerlevel9k Github +wiki](https://github.com/bhilburn/powerlevel9k/wiki/Developer's-Guide). + +#### Contributions / Bugs / Contact If you have any requests or bug reports, please use the tracker in this Github repository. -I'm happy to accept code contributions from anyone who has an improvement! -Please submit your contribution as a Github pull-request. +I'm happy to accept code contributions from anyone who has a bug fix, new feature, or just a general improvement! Please submit your contribution as a Github pull-request. If you would like to contact me directly, you can find my e-mail address on my [Github profile page](https://github.com/bhilburn). - |