1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
*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.4 Powerline_theme ................ |Powerline_theme|
4.5 Powerline_colorscheme .......... |Powerline_colorscheme|
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.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"
==============================================================================
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:
|
