diff options
| author | Ben Hilburn <ben.hilburn@ettus.com> | 2015-10-13 00:17:47 +0300 |
|---|---|---|
| committer | Ben Hilburn <ben.hilburn@ettus.com> | 2015-10-13 00:17:47 +0300 |
| commit | 2a1718d927c2805e68ed3bb5d92ccd0113a464a4 (patch) | |
| tree | 8a0bb486eb624bf1ea008152cf45de598f37f567 /README.md | |
| parent | 3e7caf5ca6abf53fd139480baaab83359c9fd0ce (diff) | |
README: moving lots of information to the Wiki
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 315 |
1 files changed, 71 insertions, 244 deletions
@@ -92,149 +92,30 @@ varying terminal status indicators:  ### Installation -There are two steps to start using this theme: +There are two installation steps to go from a lame terminal to a "Power Level +9000" terminal. Once you are done, you can optionally customize your prompt. -1. Install the Powerlevel9k theme. -2. Install Powerline-patched fonts. -3. [Optional] Configuration - -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. +[Installation Instructions](https://github.com/bhilburn/powerlevel9k/wiki/Install-Instructions) +1. [Install the Powerlevel9k Theme](https://github.com/bhilburn/powerlevel9k/wiki/Install-Instructions#step-1-install-powerlevel9k) +2. [Install Powerline-Patched Fonts](https://github.com/bhilburn/powerlevel9k/wiki/Install-Instructions#step-2-install-powerline-fonts) 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`: - - $ 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-fontconfig' - -If you chose to use already patched fonts, use instead : - - POWERLEVEL9K_MODE='awesome-patched' - +settings, but there are plenty of segment customization options available if you +are interested. -If you choose to make use of this, your prompt will look something like this: +### Customization - - -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. +#### Customizing Prompt Segments +Customizing your prompt is easy! Select the segments you want to have displayed, +and then assign them to either the left or right prompt by adding the following +variables to your `~/.zshrc`. If you don't customize this, the below +configuration is the default: -### Segment Customization + POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(context dir rbenv vcs) + POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(status history time) -Customizing your prompt is easy! Select the segments you want to have displayed, -and then assign them to either the left or right prompt. The segments that are -currently available are: +#### Available Prompt Segments +The segments that are currently available are: * **aws** - The current AWS profile, if active (more info below) * **context** - Your username and host (more info below) @@ -255,13 +136,8 @@ currently available are: * **virtualenv** - Your Python [VirtualEnv](https://virtualenv.pypa.io/en/latest/). * **vcs** - Information about this `git` or `hg` repository (if you are in one). -To specify which segments you want, just add the following variables to your -`~/.zshrc`. If you don't customize this, the below configuration is the default: - POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(context dir rbenv vcs) - POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(status history time) - -#### The AWS Profile Segment +##### aws If you would like to display the [current AWS profile](http://docs.aws.amazon.com/cli/latest/userguide/installing.html), add @@ -270,7 +146,7 @@ your `~/.zshrc`: export AWS_DEFAULT_PROFILE=<profile_name> -#### The 'context' Segment +##### context The `context` segment (user@host string) is conditional. This lets you enable it, but only display it if you are not your normal user or on a remote host (basically, only print it @@ -281,7 +157,7 @@ elements (it is by default), and define a `DEFAULT_USER` in your `~/.zshrc`: export DEFAULT_USER=<your username> -#### The 'dir' segment +##### dir The `dir` segment shows the current working directory. You can limit the output to a certain length: @@ -301,7 +177,7 @@ In each case you have to specify the length you want to shorten the directory to. So in some cases `POWERLEVEL9K_SHORTEN_DIR_LENGTH` means characters, in others whole directories. -#### The 'ip' segment +##### ip This segment shows you your current internal IP address. It tries to examine all currently used network interfaces and prints the first address it finds. @@ -310,7 +186,24 @@ network interface by setting: POWERLEVEL9K_IP_INTERFACE="eth0" -#### The 'time' segment +##### rspec_tests + +See [Unit Test Ratios](#unit-test-ratios), below. + +##### status + +This segment shows the return code of the last command, and the presence of any +background jobs. By default, this segment will always print, but you can +customize it to only print if there is an error or a forked job by setting the +following variable in your `~/.zshrc`. + + POWERLEVEL9K_STATUS_VERBOSE=false + +##### symphony2_tests + +See [Unit Test Ratios](#unit-test-ratios), below. + +##### time By default the time is show in 'H:M:S' format. If you want to change it, just set another format in your `~/.zshrc`. As an example, this is a reversed @@ -325,43 +218,7 @@ segment, as well: # Output time, date, and a symbol from the "Awesome Powerline Font" set POWERLEVEL9K_TIME_FORMAT="%D{%H:%M:%S \uE868 %d.%m.%y}" -#### Showing Status - -Usually we display always the status, and in case a command failed, the return -code of the last executed program. In case you want to display the status only -if something special happend, you can set `POWERLEVEL9K_STATUS_VERBOSE=false` -in your `~/.zshrc`. - -#### 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. - -#### VI-Mode Indicator - -This Segment shows the current mode of your ZSH. If you want to use your ZSH in -VI-Mode, you need to configure it separatly in your `~/.zshrc`: - - # VI-Mode - # general activation - bindkey -v - - # set some nice hotkeys - bindkey '^P' up-history - bindkey '^N' down-history - bindkey '^?' backward-delete-char - bindkey '^h' backward-delete-char - bindkey '^w' backward-kill-word - bindkey '^r' history-incremental-search-backward - - # make it more responsive - export KEYTIMEOUT=1 - -#### The 'vcs' Segment +##### vcs 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 @@ -380,7 +237,7 @@ You can also disable the branch icon in your prompt by setting # Hide the branch icon POWERLEVEL9K_HIDE_BRANCH_ICON=true -##### Symbols +**vcs Symbols** 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` @@ -401,6 +258,36 @@ from the [Installation](#Installation) section above. | None | None |  | Repository is a git repository | None | None |  | Repository is a Mercurial repository +##### vi_mode + +This Segment shows the current mode of your ZSH. If you want to use your ZSH in +VI-Mode, you need to configure it separately in your `~/.zshrc`: + + # VI-Mode + # general activation + bindkey -v + + # set some nice hotkeys + bindkey '^P' up-history + bindkey '^N' down-history + bindkey '^?' backward-delete-char + bindkey '^h' backward-delete-char + bindkey '^w' backward-kill-word + bindkey '^r' history-incremental-search-backward + + # make it more responsive + export KEYTIMEOUT=1 + +#### 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. + + ### Styling You can configure the look and feel of your prompt easily with some built-in @@ -519,63 +406,3 @@ your prompt even further. These Segments are `context`, `vcs`, `rspec_stats`, # symfony2_tests for poor test coverage POWERLEVEL9K_SYMFONY2_TESTS_BAD_FOREGROUND='red' POWERLEVEL9K_SYMFONY2_TESTS_BAD_BACKGROUND='white' - -### Troubleshooting - -Here are some fixes to some common problems. - -#### Gaps Between Segments - -You can see this issue in the screenshot, below: - - - -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.,). - -#### Segment Colors are Wrong - -If the color display within your terminal seems off, it's possible you are using -a reduced color set. You can check this by invoking `echotc Co` in your -terminal, which should yield `256`. If you see something different, try setting -`xterm-256color` in your `~/.zshrc`: - - TERM=xterm-256color - -#### Strange Characters in prompt - -If your prompt shows strange character like this: - - - -it is most likely that you set `POWERLEVEL9K_MODE="awesome-patched"`, but -did not install an [awesome-font](https://github.com/gabrielelana/awesome-terminal-fonts). For most other modes, you need a [powerline-patched](https://github.com/powerline/fonts) font. - -### Meta - -#### Kudos - -This theme wouldn't have happened without inspiration from the original -[agnoster](https://github.com/agnoster/agnoster-zsh-theme) 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 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). |