diff options
| author | Dominik Ritter <dritter03@googlemail.com> | 2015-07-09 20:11:03 +0300 |
|---|---|---|
| committer | Dominik Ritter <dritter03@googlemail.com> | 2015-07-09 20:11:03 +0300 |
| commit | 008512cc79bb2f3afcf4c17852e68d1d40d9e580 (patch) | |
| tree | b76e0ad9bdc4d0f85e2b71a51b540a4508ff8552 /README.md | |
| parent | 3dc5084e40b2e10272d072c7d6f05b642016e326 (diff) | |
| parent | 772c9ab85d82a87c0e7cf638ce4032697e217bc7 (diff) | |
Merge branch 'master' into dritter/developers_guide
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 242 |
1 files changed, 205 insertions, 37 deletions
@@ -1,13 +1,56 @@ -## 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 '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) + - [Contributions / Bugs / Contact](#contributions--bugs--contact) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> ### Features @@ -21,7 +64,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,22 +74,92 @@ 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. + +No configuration is necessary post-installation if you like the default +settings, but there is plenty of segment configuration available if you are +interested. + +#### 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: + +##### Option 1: Install for Vanilla ZSH + +If you use just a vanilla ZSH install, simply clone this repository and +reference it in your `~/.zshrc`: + + $ git clone https://github.com/bhilburn/powerlevel9k.git + $ echo 'source powerlevel9k/powerlevel9k.zsh-theme' >> ~/.zshrc + +##### Option 2: Install for Oh-My-ZSH + +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 + +You then need to select this theme in your `~/.zshrc`: + + ZSH_THEME="powerlevel9k/powerlevel9k" + +##### Option 3: Install for Prezto + +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 + $ ln -s powerlevel9k/powerlevel9k.zsh-theme ../functions/prompt_powerlevel9k_setup + +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`: -There are two things you need to make this theme work correctly: Powerline -fonts, and the theme itself. + $ echo 'antigen theme bhilburn/powerlevel9k powerlevel9k' >> ~/.zshrc + $ echo 'antigen apply' >> ~/.zshrc -#### 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). +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. @@ -54,17 +167,51 @@ 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. -#### Install Powerlevel9k +This is the default mode for `Powerlevel9k`, and no further configuration is +necessary. -To install this theme, clone this repository into your Oh-My-Zsh `custom/themes` -directory. +**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! - $ cd ~/.oh-my-zsh/custom - $ git clone https://github.com/bhilburn/powerlevel9k.git themes/powerlevel9k +##### Option 2: Install Awesome Powerline Fonts -You then need to select this theme in your `~/.zshrc`: +Alternatively, you can install [Awesome Powerline +Fonts](https://github.com/gabrielelana/awesome-terminal-fonts), which provide +a number of additional glyphs. - ZSH_THEME="powerlevel9k/powerlevel9k" +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 @@ -80,6 +227,7 @@ currently available are: * **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). @@ -133,26 +281,39 @@ 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 enable an additional branch icon in your prompt by setting +`POWERLEVEL9K_SHOW_BRANCH_ICON` to `true`: + + # Show an icon before the branch name + POWERLEVEL9K_SHOW_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. + +| `Bare Bones` | `Normal` | `Über` | 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 @@ -245,13 +406,20 @@ 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). + +#### 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). |