aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md199
1 files changed, 171 insertions, 28 deletions
diff --git a/README.md b/README.md
index d2f7be39..e486a84e 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,37 @@ giving you the most epic terminal styling in the universe.
Look like a bad-ass. Impress everyone in 'Screenshot Your Desktop' threads. Use powerlevel9k.
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:
+
+![](http://bhilburn.org/content/images/2015/01/pl9k-improved.png)
+
+<!-- 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)
+ - [Install Powerlevel9k](#install-powerlevel9k)
+ - [Install Powerline Fonts for Normal Configuration](#install-powerline-fonts-for-normal-configuration)
+ - [Alternative Configuration: Über](#alternative-configuration-%C3%BCber)
+ - [Alternative Configuration: Bare Bones](#alternative-configuration-bare-bones)
+- [Segment Customization](#segment-customization)
+ - [The AWS Profile Segment](#the-aws-profile-segment)
+ - [The 'context' Segment](#the-context-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)
+- [Contributions / Bugs / Contact](#contributions--bugs--contact)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
### Features
@@ -31,22 +61,36 @@ 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:
![](http://bhilburn.org/content/images/2014/12/powerlevel9k.png)
-![](http://bhilburn.org/content/images/2015/01/pl9k-improved.png)
+### Installation
+There are three different forms of installation that you can use to make use of
+this theme:
+* Normal - Theme + Powerline Fonts
+* Über - Theme + Awesome Powerline Fonts
+* Bare Bones - Theme Only
+
+#### Install Powerlevel9k
+
+To install this theme, clone this repository into your Oh-My-Zsh `custom/themes`
+directory.
+
+ $ cd ~/.oh-my-zsh/custom
+ $ git clone https://github.com/bhilburn/powerlevel9k.git themes/powerlevel9k
+
+You then need to select this theme in your `~/.zshrc`:
+
+ ZSH_THEME="powerlevel9k/powerlevel9k"
-### Installation
-There are two things you need to make this theme work correctly: Powerline
-fonts, and the theme itself.
+#### Install Powerline Fonts for Normal Configuration
-#### 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 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.
@@ -54,6 +98,9 @@ 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.
+
#### Install Powerlevel9k
##### Within Oh-my-ZSH
@@ -81,6 +128,45 @@ You then need to select this theme in your `~/.zpreztorc`:
zstyle ':prezto:module:prompt' theme 'powerlevel9k'
+#### Alternative Configuration: Über
+
+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:
+
+![](https://cloud.githubusercontent.com/assets/1544760/7959660/67612918-09fb-11e5-9ef2-2308363c3c51.png)
+
+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:
+
+![](https://cloud.githubusercontent.com/assets/1544760/7981324/76d0eb5a-0aae-11e5-9608-d662123d0b0a.png)
+
+#### Alternative Configuration: Bare Bones
+
+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,
@@ -125,14 +211,6 @@ elements (it is by default), and define a `DEFAULT_USER` in your `~/.zshrc`:
export DEFAULT_USER=<your username>
-#### Test ratio
-
-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.
-
#### The 'time' segment
By default the time is show in 'H:M:S' format. If you want to change it,
@@ -141,6 +219,15 @@ 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
@@ -157,16 +244,24 @@ Example:
##### Symbols
-The `vcs` segment uses various symbols to tell you the state of your repository:
-
-* `↑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.
+
+| `Bare Bones` | `Normal` | `Über` | explanation
+|--------------|---------------------|-------------------|--------------------------
+| `↑4` | `↑4` | ![icon_outgoing](https://cloud.githubusercontent.com/assets/1544760/7976089/b5904d6e-0a76-11e5-8147-5e873ac52d79.gif)4 | Number of commits your repository is ahead of your remote branch
+| `↓5` | `↓5` | ![icon_incoming](https://cloud.githubusercontent.com/assets/1544760/7976091/b5909c9c-0a76-11e5-9cad-9bf0a28a897c.gif)5 | Number of commits your repository is behind of your remote branch
+| `⍟3` | `⍟3` | ![icon_stash](https://cloud.githubusercontent.com/assets/1544760/7976094/b5ae9346-0a76-11e5-8cc7-e98b81824118.gif)3 | Number of stashes, here 3.
+| `●` | `●` | ![icon_unstaged](https://cloud.githubusercontent.com/assets/1544760/7976096/b5aefa98-0a76-11e5-9408-985440471215.gif) | There are unstaged changes in your working copy
+| `✚` | `✚` | ![icon_staged](https://cloud.githubusercontent.com/assets/1544760/7976095/b5aecc8a-0a76-11e5-8988-221afc6e8982.gif) | There are staged changes in your working copy
+| `?` | `?` | ![icon_untracked](https://cloud.githubusercontent.com/assets/1544760/7976098/b5c7a2e6-0a76-11e5-8c5b-315b595b2bc4.gif) | There are files in your working copy, that are unknown to your repository
+| `→` | `→` | ![icon_remote_tracking_branch](https://cloud.githubusercontent.com/assets/1544760/7976093/b5ad2c0e-0a76-11e5-9cd3-62a077b1b0c7.gif) | The name of your branch differs from its tracking branch.
+| `☿` | `☿` | ![icon_bookmark](https://cloud.githubusercontent.com/assets/1544760/7976197/546cfac6-0a78-11e5-88a6-ce3a1e0a174e.gif) | A mercurial bookmark is active.
+| `@` | ![icon_branch_powerline](https://cloud.githubusercontent.com/assets/1544760/8000852/e7e8d8a0-0b5f-11e5-9834-de9b25c92284.gif) | ![](https://cloud.githubusercontent.com/assets/1544760/7976087/b58bbe3e-0a76-11e5-8d0d-7a5c1bc7f730.gif) | Branch Icon
+| None | None | ![icon_commit](https://cloud.githubusercontent.com/assets/1544760/7976088/b58f4e50-0a76-11e5-9e70-86450d937030.gif)2c3705 | The current commit hash. Here "2c3705"
+| None | None | ![icon_git](https://cloud.githubusercontent.com/assets/1544760/7976092/b5909f80-0a76-11e5-9950-1438b9d72465.gif) | Repository is a git repository
+| None | None | ![icon_mercurial](https://cloud.githubusercontent.com/assets/1544760/7976090/b5908da6-0a76-11e5-8c91-452b6e73f631.gif) | Repository is a Mercurial repository
### Styling
@@ -197,6 +292,54 @@ Light'](https://github.com/altercation/solarized) users. Check it out:
![](http://bhilburn.org/content/images/2015/03/solarized-light.png)
+#### 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.