mirror of
https://github.com/romkatv/powerlevel10k.git
synced 2024-11-14 00:50:08 +00:00
408 lines
18 KiB
Markdown
408 lines
18 KiB
Markdown
## powerlevel9k Theme for ZSH
|
|
|
|
Powerlevel9k is a theme for ZSH which uses [Powerline
|
|
Fonts](https://github.com/powerline/fonts). It 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).
|
|
|
|
Look like a bad-ass. Impress everyone in 'Screenshot Your Desktop' threads. Use powerlevel9k.
|
|
|
|
|
|
|
|
There are a number of Powerline ZSH themes available, now. The developers of
|
|
this theme focus on four primary goals:
|
|
|
|
1. Give users a great out-of-the-box configuration with no additional
|
|
configuration required.
|
|
2. Make customization easy for users who do want to tweak their prompt.
|
|
3. Provide useful segments that you can enable to make your prompt even more
|
|
effective and helpful. We have prompt segments for everything from unit test
|
|
coverage to your AWS instance.
|
|
4. Optimize the code for execution speed as much as possible. A snappy terminal
|
|
is a happy terminal.
|
|
|
|
<!-- 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 'ip' segment](#the-ip-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)
|
|
- [Disable Right Prompt](#disable-right-prompt)
|
|
- [Light Color Theme](#light-color-theme)
|
|
- [Icon Customization](#icon-customization)
|
|
- [Segment Color Customization](#segment-color-customization)
|
|
- [Special Segment Colors](#special-segment-colors)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Gaps Between Segments](#gaps-between-segments)
|
|
- [Segment Colors are Wrong](#segment-colors-are-wrong)
|
|
- [Strange Characters in prompt](#strange-characters-in-prompt)
|
|
- [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
|
|
|
|
* Supports `git` and `mercurial` repo information through ZSH's `VCS_INFO`:
|
|
* branch / tag name
|
|
* current action status (rebasing, merging, etc.,)
|
|
* being behind / ahead of your remote by some number of commits
|
|
* number of stashes (git only)
|
|
* conditionally shows remote tracking branch if the name differs from local
|
|
* current active bookmark (mercurial only)
|
|
* 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 (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)
|
|
* Several built-in color configurations to choose from
|
|
|
|
**If you would like an OMZ theme that provides some of the same features but
|
|
doesn't require Powerline fonts, check out the sister font,
|
|
[hackersaurus](https://github.com/bhilburn/hackersaurus).**
|
|
|
|
Here is a detailed screenshot showing `powerlevel9k` with default settings and
|
|
varying terminal status indicators:
|
|
|
|
|
|
|
|
### Installation
|
|
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.
|
|
|
|
[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 are plenty of segment customization options available if you
|
|
are interested.
|
|
|
|
### Customization
|
|
|
|
#### 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:
|
|
|
|
POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(context dir rbenv vcs)
|
|
POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(status history time)
|
|
|
|
#### 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)
|
|
* **dir** - Your current working directory.
|
|
* **history** - The command number for the current line.
|
|
* **ip** - Shows the current IP address.
|
|
* **load** - Your machines 5 minute load average and free RAM.
|
|
* **node_version** - Show the version number of the installed Node.js.
|
|
* **os_icon** - Display a nice little icon, depending on your operating system.
|
|
* **php_version** - Show the current PHP version.
|
|
* **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.
|
|
* **vi_mode** - Vi editing mode (NORMAL|INSERT).
|
|
* **virtualenv** - Your Python [VirtualEnv](https://virtualenv.pypa.io/en/latest/).
|
|
* **vcs** - Information about this `git` or `hg` repository (if you are in one).
|
|
|
|
|
|
##### aws
|
|
|
|
If you would like to display the [current AWS
|
|
profile](http://docs.aws.amazon.com/cli/latest/userguide/installing.html), add
|
|
the `aws` segment to one of the prompts, and define `AWS_DEFAULT_PROFILE` in
|
|
your `~/.zshrc`:
|
|
|
|
export AWS_DEFAULT_PROFILE=<profile_name>
|
|
|
|
##### 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
|
|
when it's likely you need it).
|
|
|
|
To use this feature, make sure the `context` segment is enabled in your prompt
|
|
elements (it is by default), and define a `DEFAULT_USER` in your `~/.zshrc`:
|
|
|
|
export DEFAULT_USER=<your username>
|
|
|
|
##### dir
|
|
|
|
The `dir` segment shows the current working directory. You can limit the output
|
|
to a certain length:
|
|
|
|
# Limit to the last two folders
|
|
POWERLEVEL9K_SHORTEN_DIR_LENGTH=2
|
|
|
|
To change the way how the current working directory is truncated, just set:
|
|
|
|
# truncate the middle part
|
|
POWERLEVEL9K_SHORTEN_STRATEGY="truncate_middle"
|
|
# truncate from right, leaving the first X characters untouched
|
|
POWERLEVEL9K_SHORTEN_STRATEGY="truncate_from_right"
|
|
# default behaviour is to truncate whole directories
|
|
|
|
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.
|
|
|
|
##### 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.
|
|
In the case that this is not the right IP address you can specify the correct
|
|
network interface by setting:
|
|
|
|
POWERLEVEL9K_IP_INTERFACE="eth0"
|
|
|
|
##### 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
|
|
time format:
|
|
|
|
# Reversed time format
|
|
POWERLEVEL9K_TIME_FORMAT='%D{%S:%M:%H}'
|
|
|
|
If you are using an "Awesome Powerline Font", you can add a time symbol to this
|
|
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}"
|
|
|
|
##### 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
|
|
`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_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
|
|
|
|
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
|
|
|
|
**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`
|
|
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
|
|
|
|
##### 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
|
|
options.
|
|
|
|
#### Double-Lined Prompt
|
|
|
|
By default, `powerlevel9k` is a single-lined prompt. If you would like to have
|
|
the segments display on one line, and print the command prompt below it, simply
|
|
define `POWERLEVEL9K_PROMPT_ON_NEWLINE` in your `~/.zshrc`:
|
|
|
|
POWERLEVEL9K_PROMPT_ON_NEWLINE=true
|
|
|
|
Here is what it looks like:
|
|
|
|
|
|
|
|
You can customize the icons used to draw the multiline prompt by setting the
|
|
following variables in your `~/.zshrc`:
|
|
|
|
POWERLEVEL9K_MULTILINE_FIRST_PROMPT_PREFIX="↱"
|
|
POWERLEVEL9K_MULTILINE_SECOND_PROMPT_PREFIX="↳ "
|
|
|
|
#### Disable Right Prompt
|
|
|
|
If you do not want a right prompt, you can disable it by setting:
|
|
|
|
POWERLEVEL9K_DISABLE_RPROMPT=true
|
|
|
|
#### Light Color Theme
|
|
|
|
If you prefer to use "light" colors, simply set `POWERLEVEL9K_COLOR_SCHEME`
|
|
to `light` in your `~/.zshrc`, and you're all set!
|
|
|
|
POWERLEVEL9K_COLOR_SCHEME='light'
|
|
|
|
The 'light' color scheme works well for ['Solarized
|
|
Light'](https://github.com/altercation/solarized) users. Check it out:
|
|
|
|
|
|
|
|
#### Icon Customization
|
|
|
|
Each icon used can be customized too by specifying a variable named like
|
|
the icon and prefixed with 'POWERLEVEL9K'. If you want to use another icon
|
|
as segment separators, you can easily do that:
|
|
|
|
POWERLEVEL9K_LEFT_SEGMENT_SEPARATOR=$'\uE0B1'
|
|
POWERLEVEL9K_RIGHT_SEGMENT_SEPARATOR=$'\uE0B3'
|
|
|
|
You could get a list of all icons defined in random colors, by adding the
|
|
special segment `icons_test` to your prompt:
|
|
|
|
POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(icons_test)
|
|
|
|
This special prompt does not work on the right side, as it would be too long,
|
|
and ZSH hides it automatically. Also have in mind, that the output depends on
|
|
your `POWERLEVEL9K_MODE` settings.
|
|
|
|
You can change any icon by setting a environment variable. To get a full list
|
|
of icons just type `get_icon_names` in your terminal.
|
|
|
|
#### Segment Color Customization
|
|
|
|
For each segment in your prompt, you can specify a foreground and background
|
|
color by setting them in your `~/.zshrc`. Use the segment names from the above
|
|
section `Segment Customization`. For example, to change the appearance of the
|
|
`time` segment, you would use:
|
|
|
|
POWERLEVEL9K_TIME_FOREGROUND='red'
|
|
POWERLEVEL9K_TIME_BACKGROUND='blue'
|
|
|
|
Note that you can 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.
|
|
|
|
#### Special Segment Colors
|
|
|
|
Some segments have additional color options if you want to customize the look of
|
|
your prompt even further. These Segments are `context`, `vcs`, `rspec_stats`,
|
|
`symfony2_tests`:
|
|
|
|
# Customizing `context` colors for root and non-root users
|
|
POWERLEVEL9K_CONTEXT_DEFAULT_BACKGROUND="green"
|
|
POWERLEVEL9K_CONTEXT_DEFAULT_FOREGROUND="cyan"
|
|
POWERLEVEL9K_CONTEXT_ROOT_BACKGROUND="red"
|
|
POWERLEVEL9K_CONTEXT_ROOT_FOREGROUND="blue"
|
|
|
|
# Advanced `vcs` color customization
|
|
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'
|