|
*Powerline.txt* For Vim version 7.3. Last change: 2011 Nov 23 |
|
|
|
______ |
|
_________ \ /__ |
|
\_____ \______ _ _____________ / /'__' ___ ____ |
|
| ___/ _ \ \/ \/ / __ \_ ___\ / | |/ \_/ __ \ |
|
| | | (_) \ _ / ___/| | / /__| | | \ ___/ |
|
'___' \____/ \/ \/ \___ |__' /___ /'__'__| /\___ \ |
|
\/ / / \/ \/ |
|
| / |
|
|/ |
|
' |
|
|
|
============================================================================== |
|
CONTENTS *Powerline-contents* |
|
|
|
1. Introduction ....................... |Powerline-introduction| |
|
2. Usage .............................. |Powerline-usage| |
|
3. Requirements ....................... |Powerline-requirements| |
|
3.1 Recommended settings ........... |Powerline-recommended-settings| |
|
4. Configuration ...................... |Powerline-configuration| |
|
4.1 Powerline_cache_file ........... |Powerline_cache_file| |
|
4.1.1 Clearing the cache ....... |:PowerlineClearCache| |
|
4.2 Powerline_cache_enabled ........ |Powerline_cache_enabled| |
|
4.3 Powerline_symbols .............. |Powerline_symbols| |
|
4.3.1 Compatible symbols ....... |Powerline-symbols-compatible| |
|
4.3.2 Fancy symbols ............ |Powerline-symbols-fancy| |
|
4.3.3 Overriding symbols ....... |Powerline_symbols_override| |
|
4.3.4 Overriding dividers ...... |Powerline_dividers_override| |
|
4.4 Powerline_theme ................ |Powerline_theme| |
|
4.5 Powerline_colorscheme .......... |Powerline_colorscheme| |
|
4.6 Powerline_stl_path_style ....... |Powerline_stl_path_style| |
|
5. Fonts .............................. |Powerline-fonts| |
|
6. Customization ...................... |Powerline-customization| |
|
6.1 Basic customization ............ |Powerline-basic-customization| |
|
6.2 Advanced customization ......... |Powerline-advanced-customization| |
|
6.2.1 Colorschemes ............. |Powerline-cust-colorschemes| |
|
6.2.2 Functions ................ |Powerline-cust-functions| |
|
6.2.3 Segments ................. |Powerline-cust-segments| |
|
6.2.4 Themes ................... |Powerline-cust-themes| |
|
7. License ............................ |Powerline-license| |
|
8. Known issues ....................... |Powerline-known-issues| |
|
9. Contributing ....................... |Powerline-contributing| |
|
|
|
============================================================================== |
|
1. Introduction *Powerline* *Powerline-introduction* |
|
|
|
Powerline is a utility plugin which allows you to create better-looking, more |
|
functional vim statuslines. |
|
|
|
============================================================================== |
|
2. Usage *Powerline-usage* |
|
|
|
Powerline is automatically enabled when it's installed, either by unzipping |
|
the provided archive or by adding it as a Pathogen/Vundle bundle. |
|
|
|
============================================================================== |
|
3. Requirements *Powerline-requirements* |
|
|
|
Powerline has been developed and tested in vim 7.3, but it should run without |
|
any problems in vim 7.2. The default configuration requires a Unix-like system |
|
to work properly. |
|
|
|
The plugin only works with vim running in an 88/256-color terminal or gvim. |
|
|
|
Vi-compatible mode must be disabled. |
|
|
|
------------------------------------------------------------------------------ |
|
3.1 Recommended settings *Powerline-recommended-settings* |
|
|
|
The following configuration options should be set in your |vimrc|: > |
|
|
|
set nocompatible " Disable vi-compatibility |
|
set laststatus=2 " Always show the statusline |
|
set encoding=utf-8 " Necessary to show unicode glyphs |
|
|
|
Note: If you're using an 88/256-color terminal but still don't see the colored |
|
statusline, you may have to set the following option as well: > |
|
|
|
set t_Co=256 " Explicitly tell vim that the terminal supports 256 colors |
|
|
|
============================================================================== |
|
4. Configuration *Powerline-configuration* |
|
|
|
Powerline will work fine without any user configuration, but default behavior |
|
can be overridden by setting configuration variables globally in your |vimrc| |
|
file. |
|
|
|
------------------------------------------------------------------------------ |
|
4.1 Powerline_cache_file *Powerline_cache_file* |
|
|
|
By default Powerline caches all the statuslines and colors in a cache file in |
|
the plugin's directory (or the vim directory, depending on the installation |
|
method used). |
|
|
|
It's recommended that you enable the cache, as this dramatically improves vim |
|
startup time after the cache file has been generated (the plugin usually loads |
|
within ~100ms without the cache and ~1ms with the cache). |
|
|
|
Note: The default cache filename includes the current theme, colorscheme and |
|
symbol settings in order to tie the cache file your current configuration, so |
|
the cache file will be regenerated when you change any settings. This may |
|
leave several old cache files in your vim folder, and these may safely be |
|
deleted. |
|
|
|
Defaults: "<plugin_directory>/Powerline_<theme>_<colorscheme>_<symbols>.cache" |
|
|
|
------------------------------------------------------------------------------ |
|
4.1.1 Clearing the cache *:PowerlineClearCache* |
|
|
|
Powerline provides a command to easily clear the cache after changing your |
|
settings or updating your theme. Simply run the following command to clear |
|
your cache, and restart vim afterwards: > |
|
|
|
:PowerlineClearCache |
|
< |
|
------------------------------------------------------------------------------ |
|
4.2 Powerline_cache_enabled *Powerline_cache_enabled* |
|
|
|
It's possible to disable statusline caching by setting this option to 0. This |
|
is mostly useful when developing statuslines. |
|
|
|
Default: 1 |
|
|
|
------------------------------------------------------------------------------ |
|
4.3 Powerline_symbols *Powerline_symbols* |
|
|
|
This option defines which set of symbols and dividers you want to use. There |
|
are currently three available options: "compatible", "unicode" and "fancy". |
|
|
|
TYPE DESCRIPTION ~ |
|
compatible Doesn't use any special characters. |
|
unicode Simulates icons and arrows using similar unicode glyphs. |
|
fancy Custom icons and arrows. Requires a patched font. |
|
|
|
Symbols can be inserted into statuslines by using the following variables |
|
(just insert the variables as text in your segments): |
|
|
|
VARIABLE DESCRIPTION ~ |
|
$BRANCH Inserts a branch symbol |
|
$RO Inserts a read-only symbol |
|
$FT Inserts a filetype symbol |
|
$LINE Inserts a line number symbol |
|
|
|
Default: "compatible" |
|
|
|
------------------------------------------------------------------------------ |
|
4.3.1 Compatible symbols *Powerline-symbols-compatible* |
|
|
|
These symbols will work in any configuration, and do not require a special |
|
font to work. This option will replace the fancy icons with plain text, and |
|
the pointy dividers with straight lines. |
|
|
|
------------------------------------------------------------------------------ |
|
4.3.2 Fancy symbols *Powerline-symbols-fancy* |
|
|
|
These symbols require a custom font to work. A font patcher is provided for |
|
adding the required symbols to any outline font and some bitmap fonts, see |
|
|Powerline-fonts| and the provided README file for usage details. |
|
|
|
------------------------------------------------------------------------------ |
|
4.3.3 Overriding symbols *Powerline_symbols_override* |
|
|
|
You can override symbols by adding your symbols to the |
|
g:Powerline_symbols_override dictionary. Example: If you want the branch |
|
symbol to be "∓" (hex code 0x2213) and the line symbol to be "L" you can add |
|
the following to your |vimrc|: > |
|
|
|
let g:Powerline_symbols_override = { |
|
\ 'BRANCH': [0x2213], |
|
\ 'LINE': 'L', |
|
\ } |
|
< |
|
------------------------------------------------------------------------------ |
|
4.3.4 Overriding dividers *Powerline_dividers_override* |
|
|
|
If you for some reason want to override the dividers then you can set |
|
g:Powerline_dividers_override to a list with exactly four elements: |
|
|
|
1: Hard right-pointing arrow |
|
2: Soft right-pointing arrow |
|
3: Hard left-pointing arrow |
|
4: Soft left-pointing arrow |
|
|
|
Example: > |
|
|
|
let g:Powerline_dividers_override = ['>>', '>', '<<', '<'] |
|
< |
|
----------------------------------------------------------------------------- |
|
4.4 Powerline_theme *Powerline_theme* |
|
|
|
This option defines the theme Powerline uses. The available themes are located |
|
in autoload/Powerline/Themes/. |
|
|
|
Default: "default" |
|
|
|
------------------------------------------------------------------------------ |
|
4.5 Powerline_colorscheme *Powerline_colorscheme* |
|
|
|
This option defines the colorscheme Powerline uses. The available colorschemes |
|
are located in autoload/Powerline/Colorschemes/. |
|
|
|
Default: "default" |
|
|
|
------------------------------------------------------------------------------ |
|
4.6 Powerline_stl_path_style *Powerline_stl_path_style* |
|
|
|
There are currently four ways to display the current path and file name. The |
|
default is to only display the file name like the %t statusline item. By |
|
setting this configuration value you can choose from the following ways |
|
display the current path and file name: |
|
|
|
VALUE DESCRIPTION ~ |
|
filename Display only the file name using the %t statusline item. |
|
short Display a short path. The home directory is substituted with |
|
"~", the first directory is displayed with its full name, and |
|
subsequent directories are shortened to their first letter. |
|
I.e. "/home/user/foo/bar/baz.vim" becomes "~/f/b/baz.vim" and |
|
"long/relative/path/foo/bar/baz.vim becomes |
|
"long/r/p/f/b/baz.vim". |
|
relative Display a relative path, similar to the %f statusline item. |
|
full Display the full path, similar to the %F statusline item. |
|
|
|
Default: "relative" |
|
|
|
============================================================================== |
|
5. Fonts *Powerline-fonts* |
|
|
|
TODO |
|
|
|
============================================================================== |
|
6. Customization *Powerline-customization* |
|
|
|
There are currently two ways of customizing Powerline: Basic customization |
|
using a couple of functions to insert and remove existing segments from the |
|
statusline, and advanced customization using your own autoload files. The |
|
customization features of Powerline allow you to create your own statuslines |
|
without ever touching the original source code. |
|
|
|
------------------------------------------------------------------------------ |
|
6.1 Basic customization *Powerline-basic-customization* |
|
|
|
Powerline provides the following functions to alter the default statusline |
|
look. These functions should be called from your |vimrc| file or another file |
|
which is sourced at vim startup. |
|
|
|
Note: These functions are currently applied to all statuslines, so if you |
|
insert a segment after a segment which is present in many statuslines (e.g. |
|
the "filename" segment), all the statuslines will have the inserted segment. |
|
This behavior may be changed in a future version of Powerline. |
|
|
|
Note: Remember to clear your cache with |:PowerlineClearCache| after changing |
|
your statusline! |
|
|
|
Example: > |
|
|
|
" Insert the charcode segment after the filetype segment |
|
call Pl#Theme#InsertSegment('charcode', 'after', 'filetype') |
|
|
|
" Replace the scrollpercent segment with the charcode segment |
|
call Pl#Theme#ReplaceSegment('scrollpercent', 'fileinfo') |
|
< |
|
*Pl#Theme#InsertSegment* |
|
Pl#Theme#InsertSegment({newsegment}, {location}, {targetsegment}) |
|
|
|
This function inserts {newsegment} before or after {targetsegment}. The |
|
{location} parameter specifies the location of the new segment, valid values |
|
are "before" and "after". You can see all the available segments in |
|
autoload/Powerline/Segments.vim and the files specified in |
|
|Powerline-cust-segments|. |
|
|
|
Pl#Theme#RemoveSegment({targetsegment}) *Pl#Theme#RemoveSegment* |
|
|
|
This function removes the {targetsegment} segment entirely. |
|
|
|
Pl#Theme#ReplaceSegment({oldsegment}, {newsegment}) *Pl#Theme#ReplaceSegment* |
|
|
|
This function replaces {oldsegment} with {newsegment}. |
|
|
|
------------------------------------------------------------------------------ |
|
6.2 Advanced customization *Powerline-advanced-customization* |
|
|
|
Because Powerline utilizes vim's autoload functionality, you can easily create |
|
your own segments, themes, functions and colorschemes without touching the |
|
original source code. This is a bit more complex than using the utility |
|
functions, but it allows you to do a lot more with your statusline. |
|
|
|
Your custom autoload files should be stored in your |runtimepath| (usually in |
|
"~/.vim/autoload/Powerline/*"). |
|
|
|
Note: Remember to clear your cache with |:PowerlineClearCache| after changing |
|
your statusline! |
|
|
|
6.2.1 Colorschemes *Powerline-cust-colorschemes* |
|
------------------------------------------------------------------------------ |
|
|
|
Colorschemes should be stored as separate files in |
|
{runtimepath}/autoload/Powerline/Colorschemes/. |
|
|
|
SYNTAX ~ |
|
|
|
TODO |
|
|
|
EXAMPLE ~ |
|
|
|
TODO |
|
|
|
6.2.2 Functions *Powerline-cust-functions* |
|
------------------------------------------------------------------------------ |
|
|
|
Functions should be stored as separate files in |
|
{runtimepath}/autoload/Powerline/Functions/. |
|
|
|
SYNTAX ~ |
|
|
|
TODO |
|
|
|
EXAMPLE ~ |
|
|
|
TODO |
|
|
|
6.2.3 Segments *Powerline-cust-segments* |
|
------------------------------------------------------------------------------ |
|
|
|
Segments should be stored as separate files in |
|
{runtimepath}/autoload/Powerline/Segments/. |
|
|
|
SYNTAX ~ |
|
|
|
TODO |
|
|
|
EXAMPLE ~ |
|
|
|
TODO |
|
|
|
6.2.4 Themes *Powerline-cust-themes* |
|
------------------------------------------------------------------------------ |
|
|
|
Themes should be stored as separate files in |
|
{runtimepath}/autoload/Powerline/Themes/. |
|
|
|
SYNTAX ~ |
|
|
|
TODO |
|
|
|
EXAMPLE ~ |
|
|
|
TODO |
|
|
|
============================================================================== |
|
7. License *Powerline-license* |
|
|
|
Creative Commons Attribution-ShareAlike 3.0 Unported |
|
|
|
http://creativecommons.org/licenses/by-sa/3.0/ |
|
|
|
============================================================================== |
|
8. Known issues *Powerline-known-issues* |
|
|
|
See the issue tracker at |
|
https://github.com/Lokaltog/vim-powerline/issues |
|
|
|
============================================================================== |
|
9. Contributing *Powerline-contributing* |
|
|
|
If you experience any bugs or have feature requests, please open an issue on |
|
GitHub. Fork the source repository on GitHub and send a pull request if you |
|
have any code improvements. |
|
|
|
Author: Kim Silkebækken <kim.silkebaekken+vim@gmail.com> |
|
Source repository: https://github.com/Lokaltog/vim-powerline |
|
|
|
============================================================================== |
|
vim:tw=78:sw=4:ts=8:ft=help:norl: |